OneSpan Sign Release 11.25: Recent SDK API changes

OneSpan Sign version 11.25 was recently deployed to the preview and sandbox environment. In this new version, we implemented an auto resend mechanism for expired SMS codes, modified SDK behavior so that defective packages from a package creation call will be automatically deleted, extended the REST API and SDKs to provide the ability to search a list of groups by name, continuously updated the sender UI to be accessible, and added several bug fixes. You can find the deployment dates for all our environments on our Trust Center page.

In this blog, we’ll review recent REST API extensions and behavior changes in SDK designs. Before continuing, ensure that your OneSpan Sign Environment and SDK version are both later than 11.25, so that you can test these updates. 

DELETE FAILED CREATED PACKAGE

This is a behavior change to the package creation function EslClient.createPackage(DocumentPackage) for both Java and .Net SDK.

To better understand the value of this update, it is important to understand the differences between “createPackage” and “createPackageOneStep”.

When using the “createPackage” function, the SDK will use separate REST calls to first create a package and then upload the documents and their metadata. While in “createPackageOneStep” function, the SDK will create a fully baked package in one shot.

In previous implementations, if you were to use the “createPackage” function and any document failed to upload, a partially created package would be left in the Drafts folder. While with the “createPackageOneStep” function, either the package will be created successfully or it won’t be created at all. 

The createPackage function will now also catch exceptions when uploading the documents and call the PackageService.deletePackage(PackageId) function afterwards. Also an EslException with message "Could not create a new package” is thrown, so that it’s clear to the user what happened. 

RETRIEVE A LIST OF ALL GROUPS BY NAME

This is an API extension facilitating a group search. The “name” query parameter was newly added to API call to make your searches faster. So you don’t have to retrieve all available groups, loop through and filter the name by your custom code like before.

If you are not familiar with the OneSpan Sign Groups Feature, review our guide here. 

REST Method:

HTTP Request

GET /api/groups

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Optional Query Parameters

From: The first record that will be returned. Useful for pagination.
To: The last record that will be returned. Useful for pagination.
Name: All groups will be filtered by the name. This search is case-insensitive.
Dir: The direction according to which the data will be sorted. Give the value asc for ascending, ordes for descending.

Java SDK:

List<Group> getAllGroups = eslClient.getGroupService().getMyGroups();	//get all groups
List<Group> getGroupsByName = eslClient.getGroupService().getMyGroups(“test_”);	//get group by name

.Net SDK:

List<Group> getAllGroups = eslClient.GroupService.GetMyGroups();		//get all groups
List<Group> getGroupsByName = eslClient.GroupService.GetMyGroups(“test_”);		//get group by name

Let’s do a quick test in Web Portal and Postman. We’ve created some test groups in our dashboard.

Now we can perform some API tests via Postman. (Read this Developer Blog to learn how to use Postman)

As the above results show, the API successfully returned full and partial groups, including the cases in which special characters are used.

DELETE MULTIPLE DOCUMENTS IN ONE CALL

If a signer declines or opts out of the transaction during the signing ceremony, the package owner would typically need to delete multiple documents in order to upload and resend the package. This newly exposed API was designed to help you delete a list of documents without making repetitive API calls.

Let’s see the API reference first:

Let’s see the API reference first:
HTTP Request
DELETE /api/packages/{packageId}/documents
HTTP Headers
Content-Type: application/json
Authorization: Basic api_key
Request Payload
["document1ID","document2ID"]

Note:
•    This API only applies to DRAFT Transactions.
•    The request body should be a JSON array with document Ids.
•    At least one document Id should be passed in and all document Ids should be existing, accurate, and non-duplicate, otherwise an error will be returned

The corresponding SDK function are implemented as below:

Java SDK

eslClient.getPackageService().deleteDocuments(PackageId packageId, DocumentId... documentIds);

.Net SDK

eslClient.PackageService.DeleteDocuments (PackageId packageId, params string[] documentIds);

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!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today