Configuring a DocuSign Integration

by Christina Moore Updated Sep 09, 2019

Onit accepts an integration with DocuSign, allowing the system to send out documents associated to Onit transactions for signature.

The configuration of this integration takes a bit of work to set up and includes a lot of little steps along the way. You'll need to use a template app, provided by Onit, to build out this integration. But in order to customize its signature workflow and integrate it into your use case, you'll need to understand the components and moving pieces that make this integration work.

We'll start this tutorial by overviewing the general anatomy of a DocuSign integration and reviewing the required DocuSign Credentials you'll need before we jump into how to customize the configuration for your use case.

Overview of the Integration

To go live, you must have a DocuSign account that has an active DocuSign API Plan subscription. Here are the available API plans that can be chosen. The plan to select depends on specific use case requirements such as how many documents need to be sent each month.

Onit’s DocuSign integration relies on an Onit Action to create a DocuSign envelope using the file requiring signature. The file is then passed through a DocuSign signature workflow, where one or more signers provide electronic signatures. For the most part, DocuSign (not Onit) facilitates the signature workflow by emailing each signer and linking them to a webpage where they can electronically sign the document.

After the envelope is created, DocuSign will make API calls to Onit when certain events occur. These events include:

  • Completion of the workflow: All signatures have been acquired.
  • Signature Declined: One of the signers declines to sign.
  • Error Occurs: DocuSign attempts to navigate through the signature workflow but encounters an error. (E.g., DocuSign attempts to email a signer but the email address is invalid.)

After one of the events above occurs and DocuSign notifies Onit, an Onit Conditional Compound Action (CCA) is triggered, which retrieves information from DocuSign about the event that occurred, and in turn triggers child CCAs conditional to the different DocuSign events.

The integration also supports “voiding” an envelope after it has been created. This option can be exposed to Onit end-users via a Button, which when clicked triggers Onit to make an API call to DocuSign to void the envelope and end its signature workflow.

Using the DocuSign Template App

To use this integration, it is highly recommended that you use a pre-built app named DocuSign Template. This app is where most of the major components (Actions, Conditions, Fields, etc.) necessary for the integration have already been created. It is not recommended to recreate all of these components from scratch in a brand-new app. Instead, you should apply your own customizations/changes to this template. This documentation assumes you will be using a copy of the DocuSign Template app. If you do not have this app in your Onit environment, talk with your Onit representative.

In most cases, the DocuSign Template app is a stand-alone, non-user-facing app, within which there is one record per DocuSign envelope. Records in this app act as an interface that sit between the Onit end-user-facing record and the DocuSign envelope.

Your end-user-facing app and DocuSign Template app should be related through a ManyToMany relationship.

Sample Workflow

Below is a step-by-step description of a basic implementation of this integration. In the example below, the end-user-facing app is named Contract Review and Approval.

  1. A record in the Contract Review and Approval app reaches a Phase named Out for Signature. As a result, a Create Related Transaction Action fires within this app, which creates a new and related record in the DocuSign Template app.
  2. Upon creation of the DocuSign Template record, Actions within the DocuSign Template app make an API call to DocuSign to create the envelope and start the signature workflow.
  3. DocuSign sends emails to each user in the signature workflow, one-by-one. Each user clicks a link in their email to launch a DocuSign webpage and electronically sign the document.
  4. When the signature workflow is complete, DocuSign makes a call to the Onit API, which triggers a Conditional Compound Action (CCA) that lives in the DocuSign Template app. This CCA, in turn, changes Phases/Field values on both the DocuSign Template record and the Contract Review and Approval record. For example, both records' Phases may be set to Signed.

DocuSign Template App Components

The following is an overview of the major components used in the integration. (Information on how to hook up and customize this integration is detailed in the steps provided later in this tutorial.) As an App Creator, you should be aware of each component to both understand how it functions and to understand how you can customize these components around your needs.

Note: All Actions, Conditions, properties, etc. listed below are from the DocuSign Template app.


Creating DocuSign Envelopes:
The DocuSign Post Request Action named DocuSign Post, and Rest Request Action named Get Bearer Token are responsible for creating the DocuSign envelopes. They authenticate the user and define the type of envelope that should be created as well as the signature workflow a document should travel through. You'll do most of your customization for the integration on these Action.


Reacting to DocuSign Events:
As mentioned above, DocuSign will make API calls to Onit when certain events occur. When an event of any type occurs, DocuSign will make an API call to trigger an Onit Action named webhook, which is a Conditional Compound Action (CCA).

This CCA, in turn, triggers the following Actions:

  • An Action named hook. This Action makes a call to DocuSign to retrieve information about the DocuSign event that occurred. For example, it retrieves the event type (e.g., signed, declined, error) and the final signed document, and stores these objects into Onit Fields on the DocuSign Template record.

  • When the hook Action runs, it also saves a value into the DocuSign Template record’s docusign_status Field that identifies the current state of the envelope. Various other Actions in the DocuSign Template app investigate the value of the docusign_status Field to determine how the Onit workflow should proceed.
    • In most cases, you do not need to modify any properties in this Action.

  • A child CCA named When Completed Change to Signed. This CCA only fires if the docusign_status Field equals Completed, (which indicates that the entire signature workflow has been completed in DocuSign).

    You can place whatever child Actions you like into this CCA to change the Phase/Field values of any Onit records. At the least, it is recommended that you use this CCA to:
    1. change the Phase of DocuSign Template record to Signed,
    2. change the Phase of the user-facing record (e.g., the Contract Review and Approval record) to the appropriate Phase, and
    3. copy the signed document from the DocuSign Template record to the user-facing record. (There is already an Action in the app to do this named Copy Signed Document to Transaction).

  • A child CCA named When Declined Change to Declined. This CCA only fires if the docusign_status Field equals Declined, (which indicates that one of the signers declined to sign the document).

    You can place whatever child Actions you like into this CCA to change the Phase/Field values of any Onit records. At the least, we recommend copying the declined reason, (which will be saved into the DocuSign Template record’s declined_reason Field), over to the user-facing record.

Note: In DocuSign, if one user declines to sign, the entire envelope is marked as “declined” and all future signers in the workflow will not be emailed.


  • A child CCA named When bounced Change to Bad Email/Error. This CCA only fires if the docusign_status Field value equals Sent. In the context of this tutorial's sequential signature workflow, DocuSign returns a status of Sent if an email bounce occurs after attempting and failing to email a specific user. For example, let’s say that your signature workflow includes Signer A and then Signer B (in this order). If Signer A’s email is valid but Signer B’s email bounces, the signature workflow will proceed without issue up until DocuSign attempts to email Signer B, at which point DocuSign will notify Onit of the bounced email.

    You can place whatever child Actions you like into this CCA, to change the Phase/Field values of any Onit records. In general, we recommend that, in the event of an email bounce, you:
    1. void the entire envelope (voids are covered in more detail below) and then
    2. change the Phase/Fields of the appropriate records in Onit.

Note: It is critical that you account for email bounces when configuring this integration. Ensure that you exhaustively test to ensure that bounces are treated correctly. Failure to do so may lead to significant problems in production.

Voiding Envelopes:

An Action named Void DocuSign is provided for canceling out an entire envelope. (For more information on how DocuSign handles voided envelopes visit their user guide.)

It is highly recommended that you configure a Button to fire this Action so that end-users can void an envelope ad hoc.

Customization Options

As an App Builder, you can customize the following aspects of the integration:

  • Signature workflow. You can specify how many signers should be involved, who those signers should be, and the order in which the signers should provide their signatures. In addition, you can optionally define different signature workflow paths (e.g., if the value for the Onit department Field is "Sales", include Signer A, then Signer B, then Signer C; alternatively, if the department Field value is "HR", include Signer C and then Signer B).
  • Onit Phases and Fields: You have control over which Onit Phases the Onit records are in at any given time as the signature workflow is being traversed. In addition, you can change Onit Field values throughout the workflow, to save values returned by DocuSign (e.g., you can capture a “decline reason” into a user-facing Field).
  • Signature Tabs: You can specify exactly where DocuSign's “Sign Here” icons will appear throughout the file requiring signature.

Out of Documentation Scope

Though potentially possible to achieve with the Onit/DocuSign integration, the following functionality is not covered in this tutorial:

  • Using the integration to collect physical signatures via DocuSign. This tutorial only covers electronic signatures.
  • Including more than one document as part of the same envelope. This tutorial assumes one document per envelope.
  • A signature workflow that involves parallel signers. This tutorial assumes that each signer will be prompted for a signature sequentially (i.e., one after the other).
  • Using Onit to create draft envelopes. This tutorial describes an integration where Onit requests DocuSign to immediately start the signature workflow. Alternatively, it is possible for Onit to simply create a draft envelope in DocuSign, where a user must log into DocuSign to turn the draft envelope into an actual envelope, (and while doing so, the user can build out the signature workflow using DocuSign’s website, as well as manually define where the “sign here” tab(s) should appear). This draft approach is not covered in this document.

DocuSign Credentials

The integration requires that you provide various Onit Actions with valid DocuSign credentials to facilitate authentication by Onit to DocuSign.

Development versus Production Credentials

The set of credentials and server details used for configuration will be different when developing the integration than those used when the project is in Production.

For most projects, the following events will occur:

  1. Before starting the project with Onit, most clients will already have their own (non-developer) Production account in DocuSign that they use to facilitate electronic signature workflows outside of Onit. If they do not have such an account, however, they must create one.
  2. In addition to the Production account, the client should create a free and separate Developer account in DocuSign. To do so, the client should browse to https://appdemo.docusign.com/home to add the new account.
  3. After creating the Developer account, the client must create an Integrator Key and send information about both this key and their Developer account to the App Creator building out the integration so that they can manually plug it into various Onit Actions (described later in this tutorial). This allows Onit to authenticate to DocuSign using the Developer account and the Integrator Key during development. As a result, all testing will be performed on a Development DocuSign server (e.g., https://demo.docusign.net).
  4. When the project is ready to go into the Production, the client must promote the Integrator Key to their Production account. This is referred to as the DocuSign API Go Live Process, and it is documented here (see the section of the FAQ titled How do I start the Go Live Process?).
  5. Once the Integrator Key has been promoted to the Production  account, some of the Onit Actions must be manually modified to use the Production Account details (rather than the Developer account). In addition, some Onit Actions must be modified so that they no longer communicate with the Development DocuSign server, and instead interface with the Production DocuSign server. More information will be provided throughout this tutorial about the specific places where these changes will need to be made, or you can reference the Switching to Production Checklist at the end of the tutorial.

Credential Requirements

There are four DocuSign credentials/objects that you will need to provide to various Onit Actions:

  • API Account ID
  • Integration Key
  • RSA Keypairs
  • JSON Web Token 

To retrieve these credentials/objects follow the steps below:

API Account ID

The API Account ID is the unique account ID of the DocuSign Developer account. To retrieve this ID navigate to the Admin page of your DocuSign Developer account by right-clicking your profile picture and selecting Admin. Then from the sidebar on the left click Users.

Click on the user you wish to impersonate when sending envelopes from Onit. Find the ID under the heading API Username. The ID will have the following format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Copy this ID for later use.

Integration Key

The unique integration key of your DocuSign developer App. To retrieve this key navigate to the Admin page of your DocuSign account then click on API and Keys from the left sidebar. You should see your Integration Key displayed on the page.

Note: If you do not see an Integration Key here you must first create a DocuSign App.

Copy this key for later use.

RSA Keypairs

A Public / Private Keypairs used to authorize the DocuSign workflow. To retrieve the keypair click on your DocuSign App in the API and Keys page.

Scroll down until you see the Service Integration section and click Add RSA Keypairs.

Once you click Add RSA Keypairs you will only be shown the keypairs once. You must copy both the public and private keys for later use. If you lose the key, you must generate another pair.

Copy the public and private key for later use.

JSON Web Token

Allows for the generation of the user’s unique bearer token to authenticate the DocuSign workflow in Onit. Generating the JSON Web Token is the most involved step in this process and requires some set-up first.

Scroll down to Additional Settings and click Add URI, we recommend you use https://onit.com/ as the URI. This URI will allow the client to provide consent for the developer to impersonate a signatory.

Now you must grant consent to impersonate the user. 

  1. Replace the Integration key and Redirect URI in the appropriate spots in this URL:
  1. Paste the modifyed URL in your browser. If successful, you will see the following webpage.

Click Accept to consent.

  1. Now that you have granted consent, navigate to jwt.io to generate the JSON Web Token.
  2. Change the algorithm to ‘RS256’ from the drop down.
  3. Change the header section to:
{
  "typ": "JWT",
  "alg": "RS256"
}
  1. Change the payload data as follows:
{
  "iss": "Your Integration Key, gathered earlier",
  "sub": "Unique User ID, gathered earlier",
  "iat": 1,
  "exp": 1669758361,
  "aud": "account-d.docusign.com",
  "scope": "signature impersonation"
}

Note: When the integration is changed to production the “aud” property will be changed to remove the -d in the URL.

  1. Paste your public and private keys in the appropriate spaces under Verify Signature.
  2. Your JWT Token should look like the following:

Copy the created token for later use.

Note: Since the User ID is unique to each user account you must generate a new JWT Token for each user you wish to impersonate in your workflow.

Let's Get Started!

Now that you have a general picture of the different components we'll be working with and have the credentials we'll need to use in our configuration, let's roll up our sleeves and hook one of these up.

Note you must perform all the relevant configuration changes mentioned below in order for the integration to work.

1. Relate the DocuSign Template App to the End-User-Facing App

The DocuSign Template app contains a ManyToMany Field named econtracts that is designed to connect the DocuSign Template app to the end-user-facing app. In the Wizard for the DocuSign Template app, you'll need to change the Target app property to point to your end-user-facing app.

In our example, our user-facing app is named Contract Approval.

We'll also need our end-user-facing-app to have a ManyToMany Field pointing back at our DocuSign Template app.

Once both of these steps have been completed, you can now relate records in these two apps together as siblings. This will be required so that you can change Phases and Field values in the end-user-facing app as events occur in the DocuSign Template app.

For more details on ManyToMany relationships, see our Creating a Sibling Relationship article.

2. Configure a REST Request Action

Add a new Rest Request Action to your DocuSign Template App. This Action will be responsible for generating the bearer token used to authenticate users. Configure the Action as follows:

  • URL: https://account-d.docusign.com/oauth/token
  • Call: POST
  • Headers:
Accept: json,
Content-Type:application/json
  • Body JSON: 
{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "Your JSON Token, generated earlier"
}
  • Status Field: Bearer Key (bearer_key)

Note: The Bearer Key Field should be a read-only hidden text Field used to store the generated Bearer token.

Click Save to save your Action.

3. Configure a DocuSign Post Request Action

Add a new DocuSign Post Request Action to your DocuSign Template app. This Action will be responsible for defining the type of the DocuSign envelope and creating it. It is also where the signature workflow is set for your process.

Before continuing it is crucial to understand the Get Bearer Token Rest Request action created earlier must always fire before making any API call to DocuSign. The Bearer token generated by that Action is what authenticates the user to DocuSign and only lasts 1 hour so we recommend creating a CCA for all API calls that bundles the Rest Request and API Call Action together.

For example, here we would create a CCA to first perform the Rest Request Action to get the Bearer token (which would populate in the bearer_token Field) then the CCA would fire the DocuSign Post Request Action which requires that Bearer token.

Below are descriptions of the configuration options and requirements for this Action:

  • URL: The value of this property will need to be changed depending on whether or not you're configuring this Action during development of the integration or you are switching to production. In both cases, you'll need to edit the account number (highlighted in the screenshot below) for this URL.

For development: The default URL value in this property refers to a non-Production DocuSign server (demo.docusign.net) and is the appropriate URL to use while configuring for a non-Production Onit environment. You'll still need to edit the account number (highlighted in the screenshot above) for this URL. The account number you use should be the DocuSign account number described previously in this tutorial.

For production: Use a Production DocuSign server for the URL (e.g., https://www.docusign.net/restapi/v2/accounts/4158891/envelopes). The account number in the URL will also likely change again in production to the client's DocuSign Production account number, as opposed to the Developer account.

  • Headers: Change this property's value so that the Authorization header references the appropriate Bearer. The Liquid should parse through the JSON returned by the Get Bearer Token Rest Request Action (created earlier) and extract the bearer token. 
  • Body JSON: This property is where the bulk of your customization will be configured. Configuration details are provided below in Step 4 of this tutorial.
  • Document Field: This property identifies the Onit Attachment Field containing the file that will move through your DocuSign workflow for signature.
  • Status Field: This property identifies the Field that DocuSign will use to save API responses. For example, when an envelope is successfully created, DocuSign will save a status to this Onit Field indicating success.

    Other Onit Actions involved in the integration will require you to define a status Field for the same purpose. As a result, it’s important that all Onit Actions are configured to use the same Field for DocuSign statuses. In addition, be aware that various Conditions within the DocuSign Template app will refer to the value of this Field.

Note: This Action is unique to each user. For API requests authenticating as a different user you must create a new Rest Request Action and DocuSign Post Request Action for each.

4. Customize the DocuSign Post Request Action's Body JSON Property

The Body JSON property of the DocuSign Post Request Action is where the heavy lifting is done. The JSON you provide here identifies the type of DocuSign envelope that will be created.

The out-of-the-box DocuSign Template app contains some sample JSON, which you will likely need to customize. Below are some pointers for configuring:

You can, and very likely should, use Liquid to generate portions of this JSON. For example, to define the email addresses and names of the signers, you will likely want to retrieve these values from Onit Fields with Liquid.

Note: Only some portions of the JSON are described in this document. DocuSign’s API documentation provides an exhaustive overview.

 

  • FileExtension: The value of this property identifies the type of file DocuSign should expect. By default, the Onit integration sets this to docx, though you can change this value to any supported file type.
  • emailBlurb: The value of this property identifies the text that will appear in the body of the email sent to each signer (e.g., Please sign this document).
  • emailSubject: The value of this property identifies the text that will appear in the subject of the email sent to each signer (e.g., Test DocuSign Email).
  • recipientEventStatusCode: It's important that you do not edit (or remove) this value, as doing so will cause Onit to not react appropriately to signer email bounces.
  • url: The URL property within the eventNotification node tells DocuSign which Onit app to notify when events occur. Replace this URL with the one that matches your Onit environment. While doing so, note that the URL contains a URL parameter that is an Onit auth_token. Ensure that you provide a valid auth_token token value, which maps to a user that has been granted the API User role.

For production:
Remember to change this URL (including the auth_token) once you move into production.

  • signers: This is the the portion of the JSON that you will customize the most as this is where you define your signature workflow by identifying each of your signers and their properties. The out-of-the-box DocuSign Template app creates a very hardcoded and basic signature workflow that you’ll need to customize.

Remember that you can use Liquid to generate this JSON. For example, you’ll want to use Liquid to dynamically define each signer. If necessary, you can use Liquid if/then statements to create different signature workflows that are conditionally executed. (E.g., if Onit Field X equals Foo then generate JSON that uses a different signature path than if Field X equals Bar).

Below is a sample Body JSON value and beneath it is a table calling out various portions of the value by line number. Only the most important and least obvious portions of the JSON are described in this tutorial, however. For more complete documentation, you can refer to DocuSign’s API documentation.

Line # Description
51 The signer’s email address. In most cases, you’ll use Liquid to extract this value from an Onit Field
52 The signer’s full name. In most cases, you’ll use Liquid to extract this value from an Onit Field.
53 Each signer must be assigned a unique ID number. You’ll re-use this same ID number when creating signHereTabs and dateSignedTabs for a signer (i.e., Line 70 and Line 86 above, respectively).
56 signHereTabs is the object that the signer clicks to provide their digital signature. This object appears on the page of the file being signed.
59 This is the anchorString property for a signHereTabs object.

To determine where to place the signHereTabs object on the document, DocuSign will look for a string in the document that exactly matches the value you provide for the anchorString property. For example, in the sample JSON above, the signHereTabs object will appear directly on top of a string in the document that equals /Sig1/.

In most cases, you’ll want to add formatting to this string in the document, so that end-users can’t see it. For example, in this example we’d apply a font-color of white to the /Sig1/ value in the document template. This allows DocuSign to find the value but it prevents signers from actually seeing this value.
79 A dateSignedTabs is the object that appears after a signer provides a digital signature which shows the signing date.

Multiple Signers: In the example above, only a single signer is defined but you can define as many signers as you want in your JSON; Separate signers with a comma if your workflow requires more than one as seen in the example JSON shown here.

Phew! Ok, we've got our DocuSign Post Request Action configured. Let's tie up the rest of this app.

5. Provide a Button for Voiding Envelopes

It is highly recommended that you provide an Action Button to end-users that allow them to void an envelope ad hoc. The DocuSign Template app comes with a Void DocuSign Action; You just need to create an Action Button for your users to fire it and adjust a few of the properties of the Action itself.

To make this Action work, you'll need to change the URL and Header properties to the values used for the properties of the same name in your DocuSign Post Request Action configuration above. These values will also need to change when you move your configuration over to production.

Refer to the DocuSign Post Request Action's URL and Headers property configuration instructions above to set the URL and Header values of this Action.

6. Customize the App's Conditional Compound Actions

The out-of-the-box DocuSign Template app comes equipped with various Conditional Compound Actions (CCAs) that orchestrate the overall integration. You can configure the Actions inside of these CCAs to control Phase changes, Field value changes, and many other aspects of your Onit records. The out-of-the-box CCAs contain some default configuration in this area, but you’ll likely want to customize it around your needs.

Remember, each API call made to DocuSign must be preceded by the Get Bearer Token Rest Request Action. Create your CCA’s accordingly.

Switching to Production Checklist

When you move your apps over to production, remember that you'll need to change a few values. Check off this list and your configuration should survive the transplant well:

  1. It's critical that you exhaustively test to ensure email bounces are treated correctly. Failure to do so may lead to significant problems in production.
  2. Promote your Integrator Key. Here is a link to DocuSign's FAQ on promoting the Integrator Key.
    • To go live, you must have a DocuSign account that has an active DocuSign API Plan subscription. Here are the available API plans that can be chosen. The plan to select depends on specific use case requirements such as how many documents need to be sent each month.
    • This process involves sending 20 or more documents through a signature workflow via the Onit integration on a single day, using the Integrator Key.
    • Once you hit 20 on a single day using the Integrator Key, then and only then will DocuSign's website allow you to log in and complete the promotion process.
    • Here is the specific link to guide you through the promotion of an Integrator Key into a production key.
    • For the JWT Token: Change the ‘aud’ payload property to remove the ‘-d’ in the URL. Replace all JWT Tokens in your configuration with the new generated Token.
  • For the DocuSign Post Request Action:
    • Change the URL property to point to the Production DocuSign server and include the DocuSign Production account number.
      • There is a chance that on promotion to production, the standard 'https://www.docusign..." endpoint will not work. If you receive a USER_AUTHENTICATION_FAILED error message, you will need to change the beginning of the endpoint to "https://na2.docusign..."
    • Change the Headers property so that it uses the DocuSign Production account's Bearer Token generated by Rest Request.
    • Change the Body HTML's url value to point to the Production DocuSign server, including the correct auth_token
  • For the Void DocuSign Action:
    • Change the URL property to point to the Production DocuSign server and include the Production account number.
      • There is a chance that on promotion to production, the standard 'https://www.docusign..." endpoint will not work. If you receive a USER_AUTHENTICATION_FAILED error message, you will need to change the beginning of the endpoint to "https://na2.docusign..."
    • Change the Headers property so that it uses the DocuSign Production account's Bearer Token generated by Rest Request.
Previous Article Data Integration Configuration
Next Article Configuring iManage

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.