Integrate OneSpan Sign into Salesforce with the APEX SDK

We all know that Salesforce is one of the most flexible and powerful cloud-based CRM systems on the market, and many of you probably know that OneSpan Sign has a world-class app available on the AppExchange for signing documents of all kinds. But, did you know that OneSpan Sign also offers an APEX SDK? Launched earlier this year, and a product that we’ll be featuring at Dreamforce next week is OneSpan Sign’s APEX SDK – a complete toolkit that allows Salesforce developers to quickly and easily introduce e-signature capabilities into the Salesforce and Force.com applications. So, if your needs move past simply being able to send documents for signature from Salesforce to integrating into custom apps and workflows, we’ve still got you covered. Download the APEX SDK [promotion id="17409"]

Simple APEX SDK Example

Like all of OneSpan Sign’s SDKs, the APEX SDK is straightforward and easy to get started with. I thought I’d walk through a simple example of creating an OneSpan Sign transaction with documents to show just how easy it really is. For this example, I will show creating a package with several different settings, like an email message, expiration date, and setting the auto complete property of a package. So, first thing, we’ll declare our function:

public static void createPackageWithDocumentsExample(String packageName, Boolean autocomplete, String packageDescription, DateTime packageDue, String emailMessage)
{

Next, we need to create our OneSpan Sign SDK object.

ESignLiveSDK sdk = new ESignLiveSDK();

Then, you set up the example package and document data

ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
Map<String,Blob> blobMap = new Map<String,Blob>();

Blob b1 = File1_Blob_Contents;
Blob b2 = File2_Blob_Contents;

blobMap.put('testDocumentOne', b1);
blobMap.put('testDocumentTwo', b2);

Here, I’m setting the package properties based on the values passed to the function.

pkg.name = packageName;
pkg.autocomplete = autocomplete;
pkg.description = packageDescription;

This section of the code creates a new text anchor to define where a signature block will go, relative to the text "testDocumentOne" within the document.

ESignLiveAPIObjects.ExtractAnchor ea = new ESignLiveAPIObjects.ExtractAnchor();
ea.text = 'testDocumentOne';
ea.index = 0;
ea.width = 150;
ea.height = 40;
ea.anchorPoint = ESignLiveAPIObjects.AnchorPoint.TOPRIGHT;
ea.characterIndex = 12;
ea.leftOffset = -20;
ea.topOffset = -60;

Here, the signature block field is actually created and the extract anchor we created above is used to place the signature block.

ESignLiveAPIObjects.Field f1 = new ESignLiveAPIObjects.Field();
f1.type = 'SIGNATURE';
f1.page = 0;
f1.extract = false; 
f1.left = 0;
f1.subtype = 'FULLNAME';
f1.top = 0;
f1.extractAnchor = ea;

This next block shows the creation of another anchor created for placement of a date field – notice the approval.signed binding in the field.

ESignLiveAPIObjects.ExtractAnchor ea1 = new ESignLiveAPIObjects.ExtractAnchor();
ea1.text = 'testDocumentOne';
ea1.index = 0;
ea1.width = 150;
ea1.height = 40;
ea1.anchorPoint = ESignLiveAPIObjects.AnchorPoint.BOTTOMRIGHT;
ea1.characterIndex = 12;
ea1.leftOffset = -40;
ea1.topOffset = 0;

ESignLiveAPIObjects.Field f2 = new ESignLiveAPIObjects.Field();
f2.type = 'INPUT';
f2.page = 0;
f2.extract = false; 
f2.left = 0;
f2.subtype = 'LABEL';
	f2.binding = '{approval.signed}';
f2.top = 0;
f2.extractAnchor = ea1;

Next, in the example, the authorization is set up. This is where you'd add the SMS pin authentication or Q&A, if needing a more secure transaction.

List<ESignLiveAPIObjects.AuthChallenge> challenges = new List<ESignLiveAPIObjects.AuthChallenge>();
        
ESignLiveAPIObjects.Delivery delivery = new ESignLiveAPIObjects.Delivery();
delivery.email = true;
delivery.provider = true;

ESignLiveAPIObjects.Auth auth = new ESignLiveAPIObjects.Auth();
auth.challenges = challenges;
auth.scheme = ESignLiveAPIObjects.AuthScheme.NONE;

The code below creates a signer and uses the authorization and delivery objects created above, then adds the signer to a list to be used below in the package role creation.

ESignLiveAPIObjects.Signer signer = new ESignLiveAPIObjects.Signer();
signer.auth = auth;
signer.delivery = delivery;
signer.firstName = 'firstName';
signer.lastName = 'lastName';
signer.email = '[email protected]';
signer.name = 'firstNamelastName';

List<ESignLiveAPIObjects.Signer> signers = new List<ESignLiveAPIObjects.Signer>();
signers.add(signer);

As stated above, the role object is now created and the signer list created above is used to define the signers within the role. You can also set things like a role name and ID.

ESignLiveAPIObjects.Role role = new ESignLiveAPIObjects.Role();
role.signers = signers;
role.reassign = true;
role.name = 'firstNamelastName';
role.id = 'firstNamelastName';
role.type = 'SIGNER';

Here, the approval object is created, using the role we just created and the fields created above (signature and date).

ESignLiveAPIObjects.Approval approval1 = new ESignLiveAPIObjects.Approval();
approval1.role = 'firstNamelastName';
approval1.fields = new List<ESignLiveAPIObjects.Field> {f1,f2};

What would a document package be without documents, right? So, the next thing to do is to create a document object for each of the blobs we plan to upload to the package. You’ll see that the approval object created in the last chunk is used here to set the approvals and fields for the document.

ESignLiveAPIObjects.Document doc1 = new ESignLiveAPIObjects.Document();
doc1.name = 'testDocumentOne';
doc1.approvals = new List<ESignLiveAPIObjects.Approval> {approval1};

ESignLiveAPIObjects.Document doc2 = new ESignLiveAPIObjects.Document();
doc2.name = 'testDocumentTwo';

If you’ve used eSignLive before, you know that the creation of a package boils down to two items, in the end: the documents and the roles/signers. This next chunk of code shows how to add those to the package object before creating the package.

pkg.documents = new List<ESignLiveAPIObjects.Document> {doc1,doc2};
pkg.roles = new List<ESignLiveAPIObjects.Role> {role};

Now that your package is all set up, you only need to call the createPackage function and pass the package object and blobMap that were created above.

String response = sdk.createPackage(pkg,blobMap);

Finally, print confirmation that the package was created, to the console and close out the function.

System.debug('=> PackageId: ' + response);
}

That is it. If you followed along to this point, you should have successfully created a document package with document binaries, using the APEX SDK. If you have any questions about the APEX SDK, take a look at the documentation or ask a question in the developer community.

Headed to Dreamforce?

Make sure you drop by booth 401 or 2112 to talk to Doug Exner, one of our application engineers who will be demonstrating our powerful e-signature integration with Salesforce. Don’t miss our session, "Making the Case for E-Signatures in Salesforce and Force.com" Thursday, October 6, 11:00 AM – 11:20 AM at Partner Theater 1 in Moscone South Thanks for reading! If you have any questions, feel free to post in the comments section.

 Join the OneSpan Sign Developer Community   – Michael Williams Twitter | Facebook | LinkedIn