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.

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.

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.

• 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.

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.

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.

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.

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.

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:

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

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.

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.

Now you must grant consent to impersonate the user. 

1. Replace the Integration key and Redirect URI in the appropriate spots in this URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=INTEGRATION_KEY&redirect_uri=REDIRECT_URI

2. Paste the modified URL in your browser. If successful, you will see the following webpage.

Click Accept to consent.

3. Now that you have granted consent, navigate to jwt.io to generate the JSON Web Token.
4. Change the algorithm to ‘RS256’ from the drop down.
5. Change the header section to:

{
  "typ": "JWT",
  "alg": "RS256"
}

6. Change the payload data as follows:

{
  "iss": "Your Integration Key, gathered earlier",
  "sub": "Unique User ID, gathered earlier",
  "iat": 1,
  "exp": 2147483647,
  "aud": "account-d.docusign.com",
  "scope": "signature impersonation"
}

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

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.

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.

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. See Step 4 of this tutorial.
• Generate Documents Array: This checkbox will generate the document array for you instead of using custom JSON in the Body JSON Field. If you wish to use the Additional Documents Field, this checkbox must be checked.

• Document for Signature Field: This property identifies the Onit Attachment Field containing the file that will move through your DocuSign workflow for signature.
• Additional Documents: (Optional) This property allows you to include additional documents in the signature packet.
  • The Display property determines how the document will display when viewed in DocuSign. Inline documents will be displayed directly following the document for signautre, while modal documents are shown as pop-ups.
  • Check the Include Modal In Download box if you want viewers to be able to download modal documents with the DocuSign packet. Inline documents will always be downloaded with the packet.

• Envelope ID Field: This property identifies the Field that will hold the envelope ID. The envelope ID is a unique identifier assigned to your signature packet by DocuSign.
• Status Field: This property identifies the Field that DocuSign will use to save API responses.
• Success Status Message: Message displayed to user on success.
• Error Status Message: Message to displayed to user on error of DocuSign packet.
  
  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.

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:

• 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.

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

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.

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.