eSignatures are becoming more and more popular with businesses as they try to create a competitive advantage and complete business transactions faster.
With eSignature technology like Adobe Sign, you can obtain signatures from your staff and customers within minutes instead of days, and signatures can be obtained on any device. eSignature technology is a perfect fit for a Business Process Management platform like K2, allowing you to automate the collection of signatures as part of your business processes such as sales orders, employee onboarding, and contract creation.
While there is no Adobe Sign feature available for K2 (yet…) we can still integrate with K2 using the Adobe Sign REST API. This article will describe the steps required to integrate K2 with Adobe Sign, including:
- Create the Adobe Sign Developer Account and configuring OAuth
- Create the swagger file against the Adobe Sign REST API Reference
- Create an OAuth resource and resource type in K2
- Create the Adobe Sign Service Instance and generate SmartObjects
- Using Adobe Sign in your K2 applications
Adobe Sign Developer Account
To get started with Adobe Sign create a developer account. Once your account is created and verified, the first thing you will need to do is create an API application for your Adobe Sign account. Select API Applications under the API menu to create a new application.
Give your application a useful name and display name, and select the Customer option for Domain.
Once created, select your application and click the Configure Oauth for Application link. On this page, you will need to copy your Client Secret and Client ID for later use. You will also need to enter a Redirect URI and select the required scopes.
Your redirect URL will be in the form:
https://<k2 server name>/identity/token/oauth/2
Be careful as this URL is case sensitive. You can add multiple URIs by comma separating them.
Adobe Sign and REST/Swagger
To use the Adobe Sign REST API in K2 you will need to create a swagger file. Swagger files are used to describe the service, and K2 uses these files to create the service objects when you create a REST service instance.
There are many ways to create a swagger file (for example you can do it manually using an online editor like swagger.io). The example below uses REST United, an online tool that uses wizards to generate REST API Libraries. REST United offer a free account that can be used to generate swagger files.
Before you start, it is important to find the Base URI for your location. You will need the Base URI to ensure you enter the correct path in REST United.
Open the API Reference and find the base_uirs operation. Click the button to create an OAuth resource token and click the Try it Out button. You will need the api_access_point from the response.
Open REST United and select REST API -> New REST API Wizard
Enter an endpoint URL (see the API reference), ensuring you select the correct method (e.g. GET) and use the base URI you obtained above. The wizard will work out the Base URL. Enter a useful Method Name. Don’t enter a response body yet, and leave “Authentication” as none. We will look at authentication later, but for now, we can ignore it as K2 will take care of this for us.
On the next page of the wizard, you can add any more parameters.
If you added a path parameter in the Request Path this will automatically be created for you. Check the API reference for the parameters you need. Ignore the “Access-Token” header parameter – K2 will create this for you automatically when we use the OAuth authorisation type for the service instance.
Click Next to get to the Response Page. Here you can paste in the example response. Get the example response from the Adobe Sign API reference by clicking on Model Schema.
Paste the example in and click the button “Guess Response Type using Example Response”
REST United will create Models for you based on the sample.
**TIP** Use the same name for your Model as the Model Name in the API Reference. This way your SmartObjects will be named the same, making life easier when trying to work out what SmartObject methods to call.
Be careful at this step as the response type may not match the Model you just created
You will need to come back later to select this, as it will not be immediately available (don’t ask me why!)
Click Next to get to the Test page. You won’t be able to test as you do not have an OAuth token.
Click Next again to get to the Release SDK page. Here you can click On Endpoint to add more endpoints, or select Test and Export to generate the swagger.
The 2 REST operations that you will need to send an agreement are:
|POST||/agreements||Creates an agreement. Sends it out for signatures, and returns the agreementID in the response to the client|
|POST||/transientDocuments||Uploads a document and obtains the document’s ID.|
To generate the swagger simply select the Swagger option and click Export to download the file.
You will need to host the file somewhere the K2 server can access (such as the K2 server file system, or for Cloud on an Azure file storage).
When you create your REST service instance enter the address for the Swagger file in the Descriptor Location.
Adobe Sign and OAuth
The Adobe Sign REST API requires an OAuth Access Token to authorize each REST operation (more details can found here). OAuth is “an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications” 1. The details of how OAuth works are beyond the scope of this post, however, what is important to know here is that K2 has a mechanism to allow you to use OAuth so your users can seamlessly authenticate with your providers that use OAuth. You may have noticed that we did not need to add in the “Access-Token” header parameter in our swagger file. That is because when we use to create service instance with OAuth as the authentication mode K2 takes care of obtaining and adding this parameter to all smartobject method calls.
The following steps outline how to set this up for Adobe Sign.
The first step is to create a Resource Type and Resource in K2 Management.
Under the Authentication Node in Management select OAuth->Resource Types.
Add a new Resource Type called “Adobe Sign”
Then add the following resource parameters:
Then click on the Resources node and click New under Resources and add a new Resource.
Take care with the region part of the URL (e.g. au1) as this might be different for your region. You can get you full path by calling the base_uris method (see https://secure.echosign.com/public/docs/restapi/v5)
Then add in the parameter setting, using the client id, client secret and redirect URI you got from the Connect application. For the scope you need to enter the scopes required as space-separated values, e.g. user_login:self agreement_send:account user_read:account agreement_read:account agreement_write:account widget_read:account widget_write:account
|Name||Authorization Value||Token Value||Refresh Value|
|client_id||<your client id>||<your client id>||<your client id>|
|redirect_uri||<your redirect uri>||<your redirect uri>||<your redirect uri>|
|client_secret||<your client secret>||<your client secret>||<your client secret>|
Once this is done you can now use this Oauth resource when creating your service instance.
When you create the service instance you will get a message that you need to redirect for authentication.
You will be directed to the Adobe Sign login page. Once you have logged in you will be asked to accept the scopes you asked for, and then the authorization token will be created and returned to K2.
K2 securely stores these for you-you can find them under Authentication -> OAuth -> Tokens in Management if you need to delete them for any reason.
The good news is that K2 also takes care of refreshing the token for you if it expires (the token has an expiry of one hour) so you don’t need to keep re-authenticating.
When creating the service instance you can tick the option to create the SmartObjects. If you don’t select this option you can either click the button to Generate SmartObjects on the Service Instance list or create them manually.
Using Adobe Sign in your K2 Application
Once you have completed all the above steps and created your SmartObjects, you are ready to use Adobe Sign in your K2 applications
Adobe Sign uses the concept of an Agreement to manage document signing. An agreement contains one or more documents and one or more recipients.
The basic process for sending a document for signing with Adobe Sign is as follows:
- Upload a document/s
- Add the recipient/s
- Create an Agreement
You can create “groups” (called Recipient Sets) of recipients, with multiple recipients in each group. You can then indicate if you want all recipients in a group to sign, in which case they will be asked to sign in order, or just one.
Let’s look at the basic steps to create a form like the following that will allow a document to be sent to multiple signers.
- you could also do some or all of these steps in a workflow if needed.
- Your smartobject names and methods may differ from those below. If you followed the naming of your models using the API names then the smartobject names should match.
The first we will do is to upload a document.
You should have a “TransientDocumentId” SmartObject with an UploadDocument method (otherwise find your SmartObject that has this method). This method accepts a File_Name and File (document).
The output from this method will be a “TransientDocumentId” text property. You will need to store this somewhere for later use.
Next, you will need to add the recipients. This step involves serializing each recipient to a typed array and then adding these recipients to a Recipient Set. Note that the following steps will result in a single “Recipient Set” containing all recipients, with only one required to sign. If you need all recipients to sign you will need to create a “Recipient Set” for each recipient.
If you are using a list for recipient emails, loop through the list and add each recipient to a typed array (using a data field to store the updated value).
Finally, create a Typed array of RecipientSetMembersInfo and store in a data label.
The next step is to create the FileInfos object that stores the documents. Call the Serialize Add Item To Array method of the FileInfos SmartObject passing in the document id obtained earlier, and store the output in another data field.
The next step is to create the DocumentCreationInfo using the Serialize method on the DocumentCreationInfo SmartObject. Check the API Reference for valid values for Signature Flow and Signature Type. Store the output in a data label.
Next, you need to create the AgreementCreationInfo using the Serialize Method of the AgreementCreationInfo SmartObject. Pass in the DocumentCreationInfo created in the previous step, and store the output in a data label.
Note that some of these SmartObject methods could be chained together to reduce the number of methods called and make the process simpler. I have chosen to do each step individually to make it easier to describe each step.
Finally, create the Agreement. This will send the document for singing. Using the AgreementCreateResponse SmartObject call the CreateAgreement Method, passing in the AgreementCreateInfo created in the previous step. You can store the output from this method if necessary.