Docusign Integration Setup Guide

Introduction

The Appian Contract Lifecycle Management (CW) solution comes with an integration with Docusign eSignature software that can be used to facilitate and track the contract signing process automatically. Configuration for this integration will take place in both your Appian CW application and Docusign.

Please note, that while this guide strives to provide instructions for both the Appian CW application and Docusign, we strongly recommend consulting the Docusign documentation for Docsusign-specific tasks as often as possible or to troubleshoot issues with Docusign. You can also contact Appian support if you run into issues.

Overview

To ensure the integration works properly, you will need to complete the following steps:

1. Create application(s) and keys in Docusign
2. Create user account in Docusign
3. Configure Docusign Connected System in Appian CW
4. Enable Docusign Connect webhook service in Docusign
5. Configure Connect security in Docusign
6. Copy listener URL from Appian CW
7. Create custom Connect configuration in Docusign
8. Configure brand resource file
9. Turn on Docusign feature toggle

Resources

• Docusign Connected System configuration
• Key Docusign Concepts - Appian Community
• Docusign Documentation

Create Applications and Keys in Docusign

The steps in this section should be completed in your Docusign Admin account for each Appian CW environment (Dev, Test, Prod).

Reference Docusign’s Add Integration Keys documentation for the most precise and up to date steps.

To create an app:

1. Login to your Docusign Admin account.
2. Go to Settings, and select Apps and Keys.
3. Select ADD APP AND INTEGRATION KEY.
4. Enter a name for your app, such as, “CW Dev”, and select CREATE APP.
5. Select the authentication type: Service Integration (JSON Web Token Grant).

To generate a keypair:

1. Select GENERATE RSA to have Docusign generate a key pair.
2. Copy the RSA key pair to a safe location.
   1. You will need to paste the private key into the Docusign Connected System in the Appian CW solution later.
3. Select ADD URI to enter the redirect URI.
4. The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication.
   1. Follow the steps required to grant consent individually for your application to act on a user’s behalf. This is an important step for integration to work properly.
      1. More information on granting consent can be found here.
   2. Click SAVE.
5. On the Apps and Keys page, copy the API Account ID for the application you just created.
   1. You will need this API Account ID to populate the API Account ID field for the Docusign Connected System in Appian CW.
6. Select the application you created and copy the Integration Key to a safe place.
   1. You will need this Integration Key to populate the Integration Key field on the Docusign Connected System in Appian CW.

Create a user account in Docusign

The steps in this section should be completed in Docusign Settings.

To facilitate the integration between Appian CW and Docusign you will need a user account to act as, or “impersonate”, each user executing a call against Docusign from Appian CW.

Reference Docusign’s Add Users to Accounts documentation for the most precise and up to date steps.

To create a user account:

1. In DocuSign Settings, select Users.
2. Select ADD USER.
3. Enter the email address for the new user, and select NEXT.
4. Enter the profile information for the user, and select NEXT.
5. Select the Permission Profile, ideally DS Admin.
6. Select ADD USER.
7. Complete the steps in the activation email for the user account to be updated to Active.
8. For the newly created user, select ACTIONS, then View.
9. Copy the user’s User ID in a safe place.
   1. You will need this value later on for configuration of the Docusign Connected System in Appian CW.

Configure the Docusign Connected System in Appian

The steps in this section should be completed in Appian CW. This will enable Appian CW to authenticate with Docusign using the Docusign connected system included in the Appian CW application.

To configure the DocuSign Connected System:

1. Login to your Dev environment of Appian CW.
2. Go to Appian Designer.
3. Select Objects.
4. Select Connected System in the left panel under object type
5. Search for AS CW CS Docusign

1. Select the object to open the configuration modal.
2. Complete the Docusign Connected System configuration as follows.
   1. For Authentication, select JWT Grant.
   2. For Instance URL, enter https://demo.docusign.net. For production, use the production url.
   3. For API Account ID, copy and paste in the API Account ID displayed for the App you created in DocuSign Admin on the Apps and Keys page.
   4. For API Username, paste in the User ID you copied from the user account you created in DocuSign Settings > Users.
   5. For the Integration Key, paste in the Integration Key you copied from the application you created in DocuSign Settings > Apps and Keys.
   6. For Private RSA Key, paste the entire private key into the field.
   7. For DocuSign Environment, select the appropriate environment based on the Appian CW environment you’re configuring.
3. Select TEST CONNECTION to verify that Appian can successfully authenticate with DocuSign.

See also: Docusign Connected System

Enable Connect in Docusign

The steps in this section should be completed in Docusign to enable Connect, Docusign’s webhook service.

Reference Docusign’s Enable Connect documentation for the most precise and up to date steps.

To enable Connect:

1. In DocuSign, select Settings.
2. Select INTEGRATIONS, and select Connect.
3. Select ENABLE CONNECT.

Configure Connect Security in Docusign

Reference Docusign’s Connect Security Options documentation to determine which authentication method you want to enable for Docusign Connect webhook messages from Docusign to Appian CW. You’ll need to configure Connect for each Appian environment.

Copy the listener URL

The steps in this section should be completed in Appian CW. You need to retrieve the web API listener URL so you can configure it in Docusign.

To retrieve the web API listener URL:

1. Login to your Appian Development environment as an Administrator.
2. Go to Appian Designer.
3. Select Objects.
4. Select the Web API filter.
5. Search for docusign.
6. Select the object, AS CW WA STARTPROCESS Release Award.
7. Copy the listener URL, which should look like the following: https://customer-specific-domain/suite/webapi/releaseAwardOnDocuSign
   1. You will need this URL value when you configure Connect in Docusign so that Docusign Connect knows where to send webhook messages.

Create a Custom Connect Configuration

The steps in this section should be completed in Docusign. You’ll need to create a custom Connect configuration for each Appian CW environment.

Refer to Docusign’s Create a Connect Configuration for the most up to date and precise steps.

Also reference the following additional Docusign documentation to complete this setup:

• Connect Settings and Information
• Connect Events
• Recommendations for Receiving Documents from Connect

To create a custom Connect configuration:

1. In DocuSign, select Settings.
2. Select INTEGRATIONS, and select Connect.
3. Select ADD CONFIGURATION > Custom.
4. Complete the configuration web form as follows.
   1. For Name, name the custom configuration something specific which clearly indicates that the configuration is for webhook messages to Appian CWand the specific environment. For example, ‘AppianCWDev’.
   2. For URL to Publish, paste in the Web API URL you copied from the ‘CW_WEBAPI_Docusign_EventHandling’ object in the previous step.
   3. Check Enable Log.
   4. Check Require Acknowledgement.
   5. For Data Format, select REST v2.1: JSON.
   6. For Event Message Delivery Mode, select Send Individual Messages (SIM).
   7. For Appian CW to function properly, you will need to select the following events in Trigger Events to permit Connect to send messages to Appian CW:
      1. Under Recipient Events, select the following:
         1. Recipient Signed/Completed
   8. In Associated Users/Groups, select Select Users/Groups to include, and check the user account created in the earlier step.
   9. In Integration and Security Settings, check the authentication method you wish to use to authenticate webhook messages from DocuSign Connect to Appian. See Docusign’s Connect Basic Authentication Configuration documentation for specific steps to use Basic Authentication.
5. Select ADD CONFIGURATION.

Configure brand resource file

Use the brand resource file to control what recipients see in the email communications from the Docusign account and during the recipient signing session.

To properly configure the brand resource file:

1. Create an xml resource file with the code in this section.
   1. This code will hide:
      • Fax option from Print & Sign
      • Decline to Sign
      • Finish Later
2. Go to Brands in your Docusign account.
3. Upload the Changes File into the appropriate custom resource file (Signing Resource File) box.

Resource file code

1
2
3
4
5
6
7
8
<root>
<language twoletterisoname="">
    <data name="DocuSign_FinishLaterAllow">false</data>
 <data name="DocuSign_FinishLaterAllowForLoggedIn">false</data>
    <data name = "DocuSign_DeclineAllow" >false</data>
    <data name="DocuSign_FaxAllowForSignOnPaper">false</data>
</language>
</root>

Additional Docusign branding resources

To learn more, consult the following resources from the Docusign documentation on brands and resource file configuration:

• Best Practice Guide
• Branding concepts
• How to apply a brand to an envelope
• AccountBrands Resource
• DocuSign Signing Resource File Guide

Turn on Docusign feature toggle

Make sure the Docusign is Enabled in the Contract Writing Settings site.

Feedback