Options and their definitions
When the contract is generated by SELL&SIGN on the basis of a standard contract, it is often the case that certain parts have to be filled. SELL&SIGN offers the possibility to define contract types by specifying its content. Once a contract of this type is created, all options in the contract can contain a value.
The value of these options can be set via API.
https://[host]/calinda/hub/selling/model/option/update?action=getOrCreateOption
input json:
{
"contract_id" : [contract id],
"element_definition_id": [the option's id],
"value": [the value to be assigned to the option]
}To set this value, you need an element identifier. This identifier can be kept as long as the model contract is not modified. To find it, you first have to solve the option you want to address.
Retrieving an option to fill in
A model contract is made up of option definitions. To define the associated value for a given contract, you must retrieve the option definition concerned:
https://[host]/calinda/hub/selling/model/optiondefinition/read?action=getOptionDefinitionByName
json input:
{
"option_definition_name": [ definition key ],
"contract_definition_id": [ contract model id ]
}The return is structured as follows:
{
"id": 34,
"name": "calinda_EDL_dossier",
"type": "TEXT",
"description": "",
"page_id": 20,
"optionDefGroupId": 0,
"syncTimer": 1469626143968,
"helpId": 1,
"userIdentifier": "",
"lastModificationPlace": "SERVER",
"required": false
}Since an option can be, as in the example above, a simple text field or a multiple choice list, each option definition will be broken down into elements. A single element in the case of a text field, or N elements in the case of a list.
You will therefore need to know to which element the value of your option will be assigned.
Retrieving the element concerned by the value of your option
https://[host]/calinda/hub/selling/model/elementdefinition/read?action=getElementDefinitionByName
json input:
{
"element_definition_name": [ element key ],
"option_definition_id": [ option definition id we got from above]
}You get the following response:
{
"id": 90,
"name": "calinda_EDL_dossier",
"type": "TEXT",
"description": "none",
"option_definition_id": 34,
"sync_timer": 1469626143971,
"lastModificationPlace": "SERVER",
"value": "",
"range": "",
"image_token": ""
}So, you got the ID we were looking for. This information can be kept as long as the standard contract has not been modified. So, you do not have to perform all these steps again for each new contract!
Assign a value to your TEXT field
As you saw at the beginning the method to be used is:
https://[host]/calinda/hub/selling/model/option/update?action=getOrCreateOption
input json:
{
"contract_id" : [contract id],
"element_definition_id": [the option's element definition id],
"value": [the value to be assigned to the option]
}The contract identifier is therefore the one you get when you create the contract (see Creating a contract to be signed).
In the case of a contract created with ID 100, you would get the following call:
{
"contract_id": 100,
"element_definition_id": 34,
"value": "option's value"
}You get this in return if everything went well:
{
"id": 100,
"contractId": 100,
"elementDefinitionId": 34,
"syncTimer": 1456828557186,
"value": "option's value",
"lastModificationPlace": "SERVER"
}Adding properties
Also called Smartfields, these properties can be handled by the API. The name of the property is taken from the PDF of the contract. So a Smartfield represented by [myField/] will become the property named ‘myField’ and will be accessible via this API.
To create reusable property like this in the PDF file, just call:
https://[host]/calinda/hub/selling/model/contractproperty/insert?action=addContractProperty
input json :
{
"key": [name of the property to be linked to a contract],
"value": [property value],
"to_fill_by_user": [true if the value is to be filled by the user, false for a blank field],
"contract_id": [contract's id]
}The answer will then be in the form:
{
"id": 2815,
"key": "myField",
"value": "myValue",
"contractId": 897,
"toFillByUser": false,
"syncTimer": 1475749946068,
"lastModificationPlace": "SERVER"
}The ‘toFillByUser’ attribute allows the user to fill in the value of the property.
Retrieving a property
To retrieve a reusable property from the PDF file, simply call:
https://[host]/calinda/hub/selling/model/contractproperty/read?action=getContractPropertyFor
input json :
{
"key": [property name associated to a contract],
"contract_id": [contract id]
}The response will be in this form:
{
"id": 2815,
"key": "myField",
"value": "myValue",
"contractId": 897,
"toFillByUser": false,
"syncTimer": 1475749946068,
"lastModificationPlace": "SERVER"
}The ‘toFillByUser’ attribute allows the user to fill in the value of the property.
Modifying a property
It is possible to modify the value of the property afterwards based on its identifier:
https://[host]/calinda/hub/selling/model/contractproperty/update?action=setContractPropertyValue
input json :
{
"id": [property id],
"value": [property value]
}This method simply returns a 200 OK for a successful modification.