OneSpan Sign Developer: Conditional Fields – Part 2
Conditional Fields can be useful when your signing process includes conditional work flows. In the last blog, we reviewed the functionalities, showcased how to create conditional logics through the UI, and demonstrated how it appears in the audit trail.
In part two, we will continue this series and explore how you can leverage the feature through REST API.
Conditional Logic Bases
Before we start off, let’s review the bases of the conditional logic. The conditional logic involves testing a condition and then taking an action:
IF {some conditions} THEN {take some action}
For example, the logic statements could be:
- “IF text field A is not empty, THEN disable text field B”
- “IF option A is selected, THEN enable text field B”
- “IF check box A is checked, THEN make signature B required”
Conditional Logic in REST API
How Are the Conditions and the Actions represented?”
One of the technical challenges is how to represent the condition and the action so that OneSpan Sign can precisely consume the input from the integration.
Take the use case “IF check box A is checked, THEN make signature B required”, for example. The condition and the action clauses can be represented by the following:
IF: document['3eb29c43d0c7bc89cb2ade919e59ed42eb6a961a87a1af17'].field['JhC78qm5yl41'].value == 'X'
THEN: document['3eb29c43d0c7bc89cb2ade919e59ed42eb6a961a87a1af17'].field['FnS4PJPF0EAY'].required = true
From there, we use the bracket notation to locate the field. Like the above condition expression, it references the field (with ID of “JhC78qm5yl41”) under the document (with ID of “3eb29c43d0c7bc89cb2ade919e59ed42eb6a961a87a1af17”).
Note: We did not specify the signature ID, therefore it’s important to make sure that the field ID is unique within the document to avoid any confusion.
In the table below, we will contrast all the underlying conditions and actions that could be applied to the supported fields.
Condition
| Field Subtype | Description | Property Name | Possible Values |
| Text Field / Text Area | IF text field A is (not) empty | empty | true/false (boolean) |
| Checkbox | IF checkbox A is (not) checked | value | ‘X’ / ‘’(string) |
| Radio | IF radio A is (not) selected | value | ‘X’ / ‘’ (string) |
| List | IF ‘optionX’ is selected from the list A | value | ‘optionX’ (string) |
Note: For a “List” field, the option value is case sensitive. And because the condition / action statements will be later passed in as a string, use an apostrophe instead of a quotation mark and don’t forget to escape them.
Action
| Field Subtype | Description | Property Name | Possible Values |
| All Supported Fields | THEN enable/ disable field B | disabled | true / false (boolean) |
| All Supported Fields | THEN mark field B as required / optional | required | true / false (boolean) |
Note: In the current implementation, the action is not available for the field types below:
- Custom Fields
- Notary Fields
- Auto-populated Fields (e.g., Name, Title, Date)
- Labels
- Attachments
As a quick exercise that references the table above, you can easily write the expression “IF checkbox A is selected, THEN enable text field B” as shown below:
IF: document[‘{document_ID}’].field[‘{checkboxA_ID}’].value == ‘X’
THEN: document[‘{document_ID}’].field[‘textfieldB_ID’].disabled = false
TIP: An easy way to test against your input is to implement the same logic at the designer page. Then, pull the package JSON and compare with your expression.
How Can I Pass in the Prepared Expressions?
Under the package JSON, you can find the metadata regarding the conditional logics at the “conditions” array. For each node, “condition” and “action” are two required attributes, where you can pass in the statements we prepared above as a string. Optionally, you can set an ID for the logic. The example below gives you an idea how the JSON appears:
"conditions": [
{
"id": "condition1",
"condition": "document['document1'].field['checkbox1'].value == 'X'",
"action": "document['document1'].field['textfield1'].disabled = false"
}
]
With this JSON, you can build a fully baked package JSON and sent out the transaction in one shot:
HTTP Request
POST /api/packages
HTTP Headers
Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key
Form-data Key “payload”
{
"conditions": [
{
"id": "condition1",
"condition": "document['document1'].field['checkbox1'].value == 'X'",
"action": "document['document1'].field['textfield1'].disabled = false"
}
],
"status": "SENT",
"roles": [
{
"id": "Signer1",
"name": "Signer1",
"signers": [
{
"email": "[email protected]",
"firstName": "John",
"lastName": "Smith"
}
]
}
],
"documents": [
{
"id": "document1",
"approvals": [
{
"role": "Signer1",
"id": "approval1",
"fields": [
{
"page": 0,
"id": "checkbox1",
"subtype": "CHECKBOX",
"left": 262,
"width": 20,
"height": 20,
"top": 318,
"type": "INPUT"
},
{
"page": 0,
"id": "textfield1",
"subtype": "TEXTFIELD",
"left": 263,
"width": 266,
"height": 59,
"top": 388,
"type": "INPUT"
},
{
"page": 0,
"id": "signature1",
"subtype": "FULLNAME",
"left": 236,
"width": 266,
"height": 59,
"top": 561,
"type": "SIGNATURE"
}
]
}
],
"name": "Document1"
}
]
}
There it is. This review will help you create the conditional logic expressions and include them in package creation API. In the next blog in this series, we will walk you through other APIs-related to conditional fields and investigate how to achieve the same goals in our SDKs.
If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!
