DocuSign Workflow Integration for Document Signing

Documents and approvals are regular features in business process automation. Sometimes, document approvals require an additional step: signing the document to record the approval. DocuSign provides a common solution to this requirement: secure electronic signatures for documents. This article describes how you can integrate a DocuSign workflow in your approval processes by writing JavaScript code to access the DocuSign API.
The following process model diagram shows one way to implement a DocuSign workflow with Signavio Workflow Accelerator as part of a contract approval. In this model, the process starts with a request to approve a contract. The ‘Approve contract’ task at the start of the the process is a manual decision that results in either approval or rejection.
The difference between this example and a basic document approval is that this process includes a task for signing the approved document. First, the ‘Generate signing link’ sub-process uploads the contract to DocuSign and generates a link to the web page on the DocuSign web site that you can use to sign the document.
The ‘Sign document’ task displays this link, and is complete when the contract ‘approver’ has signed the document.
The rest of this article is a step-by-step guide to setting up a DocuSign workflow to prepare a document for signing, following the steps in the DocuSign API Quick Start. To do this, use Workflow Accelerator JavaScript actions to access the DocuSign API. This consists of three steps, each of which requires sending one HTTP request to the API:
These three steps are also a convenient way to set-up a process in Workflow Accelerator. This process encapsulates DocuSign API access, so you can call it as a sub-process.
To set-up this process in Workflow Accelerator:
The result of this process is a ‘Recipient view URL’ variable – a ‘Link’ variable containing the address of the web page that the signer can use to sign the document.
Each of the following sections will explain what each of these steps means. Before you start, however, you need to create a DocuSign developer account that you will use to access the DocuSign API.
The ‘Log in to API’ JavaScript action logs into the DocuSign API. The inputs are the user credentials included within the script. The output is a ‘Base URL’ – a ‘Link’ variable whose value is the common prefix for the API URLs that subsequent HTTP requests will use.
To configure this JavaScript action:
The complete script is as follows.
const credentials = JSON.stringify({
Username: 'alice@example.com',
Password: '123-456-789',
IntegratorKey: 'e25b6c71-74e6-4f25-aa38-9ab123456789'
})
const logInRequestOptions = {
url: 'https://demo.docusign.net/restapi/v2/login_information',
headers: { 'X-DocuSign-Authentication': credentials }
}
const handleResponse = (error, response, body) => {
console.log(`HTTP ${response.statusCode} ${response.statusMessage}`)
if (error || response.statusCode != 200) {
console.log(error ? error : `HTTP ${response.statusCode} ${response.statusMessage}`)
return
}
const loginInformation = JSON.parse(body)
baseURL = loginInformation.loginAccounts[0].baseUrl
}
request.get(logInRequestOptions, handleResponse)
This script has four parts:
To test the script:
The test output should include a value for the ‘baseURL’ variable in the ‘Update value’ column.
Now you have a base URL for your DocuSign demo account, you can use it to send more API requests.
After you’ve logged in to the DocuSign API, the next step is to create a DocuSign ‘envelope’. An envelope is a container for documents that require signatures, and is addressed to one or more ‘recipients’. For this example, create an envelope that contains one document and is addressed to one recipient.
To configure this JavaScript action:
const files = require('files')
const documentContents = files.getContent(document)
const envelopeDefinition = {
status: "sent",
emailSubject: "Signature request",
documents: [{
documentId: _case.number ? _case.number : 1,
name: document.name,
documentBase64: documentContents.buffer.toString('base64')
}],
recipients: {
signers: [{
name: `${signer.firstName} ${signer.lastName}`,
email: signer.emailAddress,
recipientId: _case.number ? _case.number : 1,
clientUserId: _case.number ? _case.number : 1,
tabs: {
signHereTabs: [{
xPosition: "25",
yPosition: "50",
documentId: _case.number ? _case.number : 1,
pageNumber: "1",
recipientId: _case.number ? _case.number : 1
}]
}
}]
}
}
const credentials = JSON.stringify({
Username: 'alice@example.com',
Password: '123-456-789',
IntegratorKey: 'e25b6c71-74e6-4f25-aa38-9ab123456789'
})
const apiRequestOptions = {
url: `${baseURL}/envelopes`,
headers: {
'Content-Type': 'application/json',
'X-DocuSign-Authentication': credentials,
},
body: JSON.stringify(envelopeDefinition)
}
const handleApiResponse = (error, response, body) => {
if (error || response.statusCode != 201) {
console.log(error ? error : `HTTP ${response.statusCode} ${response.statusMessage}`)
console.log(body)
return
}
const envelope = JSON.parse(body)
envelopeID = envelope.envelopeId
}
request.post(apiRequestOptions, handleApiResponse)
Although it is longer, this script has the same structure as the log in script.
To test the script:
Now that you have created an envelope by uploading a document, you can use DocuSign to sign the document.
After you have packaged a document in an envelope, you can use the DocuSign website to sign it. To do this from a DocuSign workflow, you need to generate the URL of the web page where the designated signer (the DocuSign ‘recipient’) can sign the document in the envelope. DocuSign calls this web page a ‘recipient view’.
You can create a recipient view the same way that you create an envelope: by sending an HTTP POST to the DocuSign API, whose request body contains the JSON representation of a recipientViewRequest.
To configure this JavaScript action:
const credentials = JSON.stringify({
Username: 'alice@example.com',
Password: '123-456-789',
IntegratorKey: 'e25b6c71-74e6-4f25-aa38-9ab123456789'
})
const recipientViewRequest = {
authenticationMethod: 'Email',
userName: `${signer.firstName} ${signer.lastName}`,
email: signer.emailAddress,
returnUrl: _case.link ? _case.link : 'https://workflow.signavio.com/',
recipientId: _case.number ? _case.number : 1,
clientUserId: _case.number ? _case.number : 1,
}
const apiRequestOptions = {
url: `${baseURL}/envelopes/${envelopeID}/views/recipient`,
headers: {
'X-DocuSign-Authentication': credentials,
'Content-Type': 'application/json'
},
body: JSON.stringify(recipientViewRequest)
}
const handleApiResponse = (error, response, body) => {
if (error || response.statusCode != 201) {
console.log(error ? error : `HTTP ${response.statusCode} ${response.statusMessage}`)
console.log(body)
return
}
const recipientView = JSON.parse(body)
recipientViewURL = recipientView.url
}
request.post(apiRequestOptions, handleApiResponse)
The ‘recipientViewRequest’ data identifies the recipient, and how they have authenticated, and includes the URL of the case in Workflow Accelerator, where the signer will be redirected after signing the document.
To test the script:
After running the test the ‘Update value’ column should include the ‘recipientViewURL’ value extracted from the API response.
Open the recipient view URL in a web browser to sign the document using DocuSign.
Finally, publish the process so you can run it from the document approval process.
Now that you have published the ‘Generate DocuSign signing link’ process, you can configure it as the ‘Generate signing link’ sub-process in the contract approval DocuSign workflow:
Select the ‘Generate signing link’ sub-process, and configure it by selecting the ‘Generate DocuSign signing link’ process and mapping the trigger form fields to the ‘Document’ and ‘Signer’ fields. First create these trigger form fields if you haven’t already done so.
Select the ‘Outputs’ tab and select the sub-process’ ‘Recipient view URL’ variable. Rename it to ‘Contract signing URL’ for the parent process.
Now, configure the ‘Sign document’ task by adding the existing ‘Contract signing URL’ variable to the form. Set the field ‘Read-only’.
Finally, you can see the DocuSign workflow in action.
To finish up the DocuSign workflow, use DocuSign to sign the document:
On this ‘recipient view’ the DocuSign tab is the yellow button on the document labeled ‘Sign’ with a downward arrow.
The recipient view URL expires after a short period, so in practice it would be necessary to add a decision after the ‘Sign document’ task to choose between ‘Document Signed Successfully’ and ‘Retry’. The latter case should loop back to the ‘Generate signing link’ sub-process action.
This DocuSign workflow example shows that you can use JavaScript actions to integrate your workflows with third-party services, to add sophisticated functionality to your workflow automation. This is an advanced technique that requires some coding, but much less than traditional enterprise application integration.
Signavio Workflow Accelerator’s integrated JavaScript actions and test runner greatly reduce set-up effort for developers. Instead of setting-up a development environment and their own testing infrastructure, developers can focus on writing a small amount of integration code.
To get started using Signavio Workflow Accelerator with a DocuSign workflow, then register for a free 30-day trial today.