OneSpan Sign Developer: Conditional Fields – Part 2

Duo Liang, May 6, 2020
Conditional Fields

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 Fields

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!