OneSpan Sign Release 11.44: Grouped Checkboxes

OneSpan Sign version 11.44 was recently deployed to the preview environment. In this latest version, we enhanced the checkbox field, released new features for the OneSpan Sign Virtual Room, added support for the Arabic language in the New Signer Experience, introduced new Enterprise Administrator APIs, and more. For a complete list of product updates, check the 11.44 Release Note. Also, refer to our Trust Center and find the deployment dates for all our environments.

In this blog, we will explore the revamped checkbox field, showcase how these changes could facilitate your use cases, and then introduce you to the improved APIs for Subaccount feature. Without further delay, let’s get started!

Grouped Checkboxes

“I want to design a multiple choice question and allow my signer to select one answer from a defined list of choices during the Signing Ceremony.”

This can be set as a requirement when you design the document layout. OneSpan Sign accommodates this by enhancing the checkbox field and allowing the sender to associate multiple checkboxes to a group. Review the screenshot below:

Behind the scenes, the signature JSON looks like this:

{
  "role": "Signer1",
  "name": "Signature1",
  "fields": [
    {
      "validation": {
        "group": "PreferredLanguage",
        "required": true
      },
      "page": 0,
      "extract": false,
      "width": 12,
      "height": 12,
      "left": 405,
      "top": 218,
      "subtype": "CHECKBOX",
      "type": "INPUT",
      "name": "Portuguese"
    },
    {
      "validation": {
        "group": "PreferredLanguage",
        "required": true
      },
      "page": 0,
      "extract": false,
      "width": 12,
      "height": 12,
      "left": 405,
      "top": 218,
      "subtype": "CHECKBOX",
      "type": "INPUT",
      "name": "French"
    },
    {
      "validation": {
        "group": "PreferredLanguage",
        "required": true
      },
      "page": 0,
      "extract": false,
      "width": 12,
      "height": 12,
      "left": 405,
      "top": 218,
      "subtype": "CHECKBOX",
      "type": "INPUT",
      "name": "Italian"
    }
  ]
}

By enforcing validation rule and defining the group at “documents” > “approvals” > “fields” > “validation” > “group”, all checkboxes with the same group will be associated together. Furthermore, if any checkbox from the same group are flagged as required, the signer must select at least one option from the group during signing.

Note: 

• Conditional logic on a group of checkboxes is not supported. 
• SDK support is not yet available. It will be added in a future release. 
• Extraction is not yet available. It will be added in a future release. 
• This feature is not yet 100% ADA compliant. This will be added in a future release. 
• Periods (".") are not currently supported in Checkbox Group names. This issue will be resolved in a future release.

Revamped APIs for Enterprise Administration

Enterprise Administration has been released for a while, and the OneSpan Sign team is still working hard and enhancing the feature in order to facilitate more integration use cases. In this release, we have revamped and introduced new APIs which add flexibility to identify and assign the Account Roles to a user. Before you give these new APIs an attempt, make sure:

• Your account has “Roles & Permissions” feature turned on.
• The API user has to be an Admin role or a role with the “API Access” and “User Management” permissions.

Assign Account Roles 

Before 11.44, depending on whether the account has turned on the Subaccount feature, Admin users need to invoke either of the two APIs below in order to assign account roles to a sender:

POST /api/account/senders/{senderId}/account/{accountId}/roles 
POST /api/account/senders/{senderId}/roles 

In order to provide a more consistent integration experience, these two APIs have been revamped and unified into the same endpoint:

HTTP Request

POST /api/account/senders/{senderId}/roles

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Content-Type: application/json

Example Request:

{         
    "accountId" : "Us1VqQw3r3kN",
    "accountRoles": [ {"id": "owner"}, {"id": "member"}]
}

Note:

• It’s not encouraged to continuously use the old API schema
• If your account has the Subaccount feature turned on, the “accountId” in the payload is where you want this sender to have access. Otherwise, it’s not mandatory to supply the “accountId”. 
• For “accountRoles” array, you need to provide at least the account role ID for each node
• API Key/Token holder can’t update the account roles themselves

Retrieve Account Roles

To query a specific sender’s account role, use below two APIs:

HTTP Request

GET /api/account/senders/{senderId}/roles

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json

Example Response:

[
  {
    "accountId": "Us1VqQw3r3kN",
    "accountRoles": [
      {
        "permissions": [
          "templates_layouts.share_templates",
          "transaction.in_person",
          "transaction.change_signer",
          "templates_layouts.share_layouts",
          "transaction.transaction"
        ],
        "enabled": true,
        "description": "esl.account.account_role.default_role.member.description",
        "predefined": true,
        "inherited": false,
        "id": "member",
        "name": "esl.account.account_role.default_role.member.name"
      }
    ],
    "userId": "cE01BlwKLpYI"
  }
]

Note:

• The API fits both scenarios whether your account has Subaccount feature turned on. The response array will return multiple nodes if there are subaccounts.
• The API response schema has been changed compared to the versions before 11.44. Hence you may need to adjust your code, if you’ve already integrated with this API.

Conclusion

There it is. In this blog, we demonstrated how to use the checkbox to design multi-select questions and walked you through the newly introduced APIs for the Enterprise Administration feature. 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!