OneSpan Sign Developer: Bulk Signing for Capture Signature

One of the most important features introduced by OneSpan Sign 11.20 release is that “Bulk Signing” and “Sign All” now support Capture Signature type and mixed Signature type. That is to say, as an integrator, when you want to Sign All for your sender or signer when the signatures have mixed type, you can rubber-stamp your transactions and still allow captured signatures.

In this blog, we will first explore what you can expect with this new feature, then learn about how to programmatically implement them in both SDK and REST methods

Sign Documents vs Bulk Sign for Signer

The “Sign Documents” feature allows you to sign all signatures for yourself in one single call, instead of navigating through documents successively, and signing each signature sequentially. As an extension, “Bulk Sign for a Signer” feature allows you to sign on behalf of a signer with one single call without signing through signing ceremony.

For more detailed information, refer to our Sign Documents and Bulk Sign for a Signer  guides.

What’s New?

On top of the existing behavior, when your transaction includes multiple signature types especially Capture/Mobile Signature, you can expect the following when calling the bulk signing function/API:

• Allow bulk signing with Click-to-sign, Initials, Capture, and Mobile Capture signature. Versions before 11.20 do not allow signing for Capture type.
• Enforce required fields. Namely, all optional signatures will be signed.
• Ignore Enforce Capture signature. All capture signatures within function/API request will show up with the same hand drawn value even if the signature requires Enforce Capture signature.
• If signer already has an OSS account, you can use the signer’s capture setup in the account.
  

In REST method

HTTP Request
POST /api/packages/{packageId}/documents/signed_documents

HTTP Headers
Accept: application/json
Content-Type: application/json
Cookie: ESIGNLIVE_SESSION_ID={sessionToken} //bulk sign for signer
Or Authorization: Basic api_key	//sign documents

Request Payload
{
  "documents": [
    {
      "id": "default-consent"
    }
    ,
    {
      "id": "3b71ec27e29076dd74458807cba42fe9107e86e161c39b51"
    }
  ],
  "handdrawn": "AQAAAAIcDeoYTaHiVvjKkwDJLWb6AFAAAwADADkAAAADAAAA+gBQABoAAAACRQaAQAdiEkAeQBmChTITI4BQF1Aon1CBRAhErESGVFVQ6FCVUHNQc4iamYQ="
}

Most noticeably, a new property "handdrawn" is being added to the existing json object. This property represents the actual captured signature, which was converted to a string value.

This property is optional. If you don't use capture signature, you don't need to have this property, which means that the new introduced feature won’t affect your existing working code if your workflow already contains this API.

You will be also able to utilize our capture signature widget externally and pass the signature as a property for both internal senders and third-party signers.

In Java & .Net SDK

You can find the basic usage of this new feature for Java SDK and .Net SDK from our Github page.

And in this section, we will extend the example a little bit by talking about two scenarios you may encountered when developing with it. To notice that all codes will be presented in Java, and .Net users just need to change the code a little bit to make it compiled with C# syntax.

Below are functions newly added in SDK:

In EslClient class:
public void signDocument(PackageId packageId, String documentName, CapturedSignature capturedSignature)	// Sign a document using current api key
public void signDocuments(PackageId packageId, CapturedSignature capturedSignature)		// Sign documents using current api key
public void signDocuments(PackageId packageId, String signerId, CapturedSignature capturedSignature)	// Sign documents using signer id
In CapturedSignature class:
public CapturedSignature(String handdrawn) 	//constructor

1. How to allow an existing OSS Account’s handdrawn value

If your signer already has an OSS Account and has signature stored at account level, you can use it in the following two ways:

eslClient.signDocuments(new PackageId("package_id"), "signer id/email");
eslClient.signDocuments(new PackageId("package_id"), "signer id/email", new CapturedSignature(""));

And signDocuments() function will automatically use hand drawn value setup in account to bulk sign for all capture/mobile capture signatures.

Note, if your signer doesn’t have an OSS account and you call the function in this way, you will receive the error below:

{"messageKey":"error.validation.missingAutograph","parameters":{"approvalName":"Dhwe7ODvTgIR"},"code":400,"name":"Validation Error","message":"The approval cannot be confirmed because no autograph was provided."}

And if your signer has an OSS account but does not have a pre-set signature attached to the account, you will receive the error below:

{"messageKey":"error.validation.signatureData","code":400,"name":"Validation Error","message":"Signature data is not populated."}

2. Can I use my sender’s setup signature when I “send on behalf of sender”?

Yes, as long as the signer has an OSS account with same email. No matter whether your internal sender or external signer, you can use the same function mentioned above in Question 1.

Note that if you are trying to “send on behalf of sender” and building your package, include:

.withSenderInfo(SenderInfoBuilder.newSenderInfo("[email protected]"))

And if you did not manually set your sender as a signer with function .withSigner(), you’ll use eslClient.createPackage()instead of eslClient.createPackageOneStep() to create your package.

“Support Capture Signature type in Bulk Signing” feature is important for senders and integrators when your package includes capture type and you need to bulk sign for your sender/owner or simply an external signer and allows you to use the existing setup signatures of these accounts.

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!