OneSpan Sign - Template

Hi gberde,

Thanks for your post!

Based on your description, I would suggest below API flows to bulk processing template fields:

(1)Clone a package out of the template

POST /api/packages/LAqIZlWguKSwjCLWx5KHrwYIWaE=/clone

At this step, just update transaction level settings like transaction name, description, signer information, and don't worry about field values for now

(2)Assuming that all the label fields and checkboxes are associated to one signature. Get this signature(approval) via below API:

GET /api/packages/BPxymZFpAPKGldLP-JiAjESZX8o=/documents/8e5ce87e625130eef0eb502a81996601cf67ad22620e47f8/approvals/sNUh3eWKOvoY

This returns all the fields including the label fields and checkboxes.

(3)Delete the signature 

DELETE /api/packages/BPxymZFpAPKGldLP-JiAjESZX8o=/documents/8e5ce87e625130eef0eb502a81996601cf67ad22620e47f8/approvals/sNUh3eWKOvoY

(4)Use the response from step(2) as a base JSON, enter the label values and remove checkbox nodes that are not required. Recreate the signature via below API:
POST /api/packages/BPxymZFpAPKGldLP-JiAjESZX8o=/documents/8e5ce87e625130eef0eb502a81996601cf67ad22620e47f8/approvals

The signature will be created with the same ID, and all the fields will be updated in bulk.

Let me know how this flow works for you.

Duo

Thanks for the quick response! Is "signature" and "approval" the same? If yes, then your assumption is correct - all labels and checkboxes are associated to one approval.

Questions - 

*. Before step 1, we have entire template json (because we call `Search` endpoint before clone). Can we use the approval Json in CLONE call to remove checkboxes that we don't need? 

*. question about step 4 in your description - Does OneSpan retain the same approval id - sNUh3eWKOvoY  ?

Hi gberde,

To answer your questions inline:
(1)signature and approval are the same

(2)I don't think changing approvals node in CLONE call takes effect, that's why you may have to follow this flow

(3)Yes, the recreated approval retains the ID

Duo

And just to confirm - in step 1, we need to Clone package in "Draft" status to be able to run thru the flow, correct?

Yes, you are right! Remember to invoke a PUT call at the end to send the transaction from draft status:

PUT /api/packages/{packageId}

{"status":"SENT"]

Duo

I tested the solution.. but we are losing "Conditions" (conditional logics in template). How do we retain conditions in Step 4 of your flow ?

Hi gberde,

If you also have field conditions, to disable those checkboxes (instead of deleting them) might be a cleaner solution. Disable attribute is under "approvals" > "fields" > "validation" > "disable" : true/false. The flow could look like this:
#1 Get template JSON

GET /api/packages?type=TEMPLATE&search={keyword}

#2 Clone a package out of the template. 

POST /api/packages/{templateId}/clone

#3 In template JSON, locate the approval node by ID and update its associated fields (you can both update label field value and disable checkboxes in this step).

An approval node example looks like below:

{
  "acceptedPackageTimezone": "",
  "fromFile": false,
  "fromFileData": null,
  "id": "sNUh3eWKOvoY",
  "role": "4c8222a4-7bad-42f2-9e6f-39d5f47a0862",
  "data": null,
  "disabled": false,
  "optional": false,
  "accepted": null,
  "enforceCaptureSignature": false,
  "signed": null,
  "fields": [
    {
      "binding": null,
      "validation": {
        "group": "",
        "required": false,
        "maxLength": null,
        "errorCode": null,
        "minLength": null,
        "disabled": false,
        "minimumRequired": null,
        "maximumRequired": null,
        "errorMessage": "",
        "enum": null,
        "pattern": ""
      },
      "id": "1NhuPEmbZoQ1",
      "page": 0,
      "data": null,
      "fontSize": null,
      "subtype": "LABEL",
      "extract": false,
      "width": 165.0,
      "height": 37.0,
      "formattedValue": "",
      "left": 205.0,
      "top": 854.0,
      "extractAnchor": null,
      "type": "INPUT",
      "value": "label field 1",
      "name": ""
    },
    {
      "binding": null,
      "validation": {
        "group": "",
        "required": false,
        "maxLength": null,
        "errorCode": null,
        "minLength": null,
        "disabled": true,
        "minimumRequired": null,
        "maximumRequired": null,
        "errorMessage": "",
        "enum": null,
        "pattern": ""
      },
      "id": "jg35zZmXGBI3",
      "page": 0,
      "data": null,
      "fontSize": 0,
      "subtype": "CHECKBOX",
      "extract": false,
      "width": 12.0,
      "height": 12.0,
      "formattedValue": "",
      "left": 141.0,
      "top": 858.0,
      "extractAnchor": null,
      "type": "INPUT",
      "value": null,
      "name": ""
    },
    {
      "binding": null,
      "validation": null,
      "id": "77iKdQjpec4F",
      "page": 0,
      "data": null,
      "fontSize": null,
      "subtype": "FULLNAME",
      "extract": false,
      "width": 165.0,
      "height": 37.0,
      "formattedValue": "",
      "left": 526.0,
      "top": 900.0,
      "extractAnchor": null,
      "type": "SIGNATURE",
      "value": "",
      "name": ""
    }
  ],
  "name": ""
}

With the approval JSON by hand, update the approval using:

PUT /api/packages/{packageId}/documents/{documentId}/approvals/{approvalId}

Compared to the above flow, we are updating (PUT) the signature instead of deleting (DELETE) then recreating (POST). Because we didn't delete the signature, the conditions will be retained.

Duo

Doesn't `Clone` endpoint honor `validation >> disabled` ? 

I am sending `value` of field nodes in my clone call (higlighted in bold) which is honored and reflected on my package.

here's what I send in my clone call -

•  
• {
•     "name": "Template Form",
•     "data": {
•         "senderVisible": false
•     },
•     "description": "Some description",
•     "type": "PACKAGE",
•     "visibility": "ACCOUNT",
•     "status": "SENT",
•     "emailMessage": "This is a package level email message.",
•     "roles": [
•         {
•             "id": "<roleGuid>",
•             "specialTypes": [],
•             "attachmentRequirements": [],
•             "data": null,
•             "reassign": false,
•             "emailMessage": {
•                 "content": "Please sign this Form"
•             },
•             "type": "SIGNER",
•             "index": 0,
•             "signers": [
•                 {
•                     "address": {
•                         "state": "TX",
•                         "country": "USA",
•                         "city": "Austin",
•                         "address1": "",
•                         "address2": "",
•                         "zipcode": ""
•                     },
•                     "company": "",
•                     "timezoneId": "",
•                     "email": "[email protected]",
•                     "external": null,
•                     "firstName": "John",
•                     "language": "",
•                     "lastName": "Owner",
•                     "phone": "+xxxx",
•                     "professionalIdentityFields": [],
•                     "signature": null,
•                     "title": null,
•                     "userCustomFields": [],
•                     "specialTypes": [],
•                     "passwordTimestamp": null,
•                     "idvAuthentication": null,
•                     "group": null,
•                     "knowledgeBasedAuthentication": null,
•                     "name": "",
•                     "auth": {
•                         "scheme": "NONE",
•                         "challenges": [
•                             {
•                                 "question": "+xxxx"
•                             }
•                         ]
•                     }
•                 }
•             ],
•             "name": "AdminSigner"
•         }
•     ],
•     "documents": [
•         {
•             "id": "default-consent"
•         },
•         {
•             "id": "32c24ac850fdeacf294689d14228808f9467c952348c41fe",
•             "approvals": [
•                 {
•                     "id": "3cblB0flwCYN",
•                     "fields": [
•                         {
•                             "id": "55ArymjQxDQT",
•                             "name": "Title",
•                             "value": "Admin Sr"
•                         },
•                         {
•                             "id": "K6pJVOheUzEG",
•                             "name": "PhoneNumber",
•                             "value": "xxxx"
•                         }
•                     ]
•                 }
•             ]
•         }
•     ]
• }

No, `validation >> disabled` wasn't honored from my tests.

Duo