The Best Way to use DocuSign with Appian

---

So you have a new requirement and need to set up a DocuSign flow in your Appian application. You want to make sure you set it up to handle your current use case while ensuring future enhancements are implemented as painlessly as possible. We’ll walk you through how to implement a basic use case - a single signer on an envelope containing a single document that’s only used in one Appian application - but we’ll do it in way that:

• uses Appian’s out-of-the-box DocuSign Connected System,
• routes responses to our specific Appian application,
• uses OAuth 2.0 to authenticate with Appian, and
• stores our forms to be signed as templates in DocuSign.

---

Prerequisites

To follow along with the rest of the guide, you’ll need to have:

• an Appian environment with a System Administrator user (the environment we’ll be using in this tutorial is on version 22.4), and
• a DocuSign account (you can get a free developer account here).

---

Creating an Appian OAuth 2.0 Client

While logged in with your Appian System Administrator user, navigate to the Web API Authentication section of the Administration Console.

1. Click the OAuth 2.0 Clients tab
2. Click Create
3. Add an appropriate description (something like DocuSign Connect) and a new service account (something like docusign)
4. Click Create
5. Copy and securely store the Client ID, Client Secret, and Token Request Endpoint that are presented
6. Click OK

---

Setting Up DocuSign

Connect

Make sure that you do these steps on the same account you’re going to use for your eventual production DocuSign environment. Due to DocuSign’s Go-Live requirements, you’ll want to be able to promote the app you’re building here.

To set up Connect, follow the steps below.

1. Navigate to Connect OAuth 2.0 in Settings. You should see the following input fields on your screen.
2. Check the Enable OAuth checkbox
3. With the details you securely stored while creating your Appian OAuth Client, fill the Client ID, Client Secret, and Authorization Server URL. The Authorization Server URL will be the Token Request Endpoint.
4. No Custom Parameters are needed, so click SAVE

Apps and Keys

Although we are using JWT, we still need to set up an application to get the Integration Key and RSA Private Key for our Connected System.

1. Navigate to Apps and Keys in Settings
2. Note and securely store your API Account ID and Account Base URI
3. Click ADD APP AND INTEGRATION KEY
4. Enter an App Name (e.g., Appian)
5. Copy and securely store your Integration Key
6. Leave Authentication as Authorization Code Grant, as we will using a third option not listed (JWT Grant)
7. Click GENERATE RSA and securely store the Private Key
8. Click ADD URI under Redirect URIs
9. Add a safe domain that we will use when authorizing our Connected System. Feel free to use https://www.taberna.tech. We won’t need a live callback endpoint due to the authorization type we’re implementing.
10. Click SAVE

Users

Now we are going to add a new user to our DocuSign account that will serve as our application user.

1. Navigate to Users
2. Click ADD USER
3. Add an email address. Note that this must be unique from the email of other DocuSign users on your account.
4. Click NEXT
5. Add a Full Name (e.g., Appian Application)
6. Click NEXT
7. Enter an access code and securely store it
8. Click NEXT
9. Select Permission Profile of DS Admin. DS Sender is likely fine as well, but we have not tested this.
10. Click ADD USER
11. The user you have added will receive an email from DocuSign. They will need to login and provide the access code you entered to be added to the application.
12. After the user is setup, navigate to their user in Users.
13. Copy and securely store the User ID

Creating a DocuSign Template

DocuSign templates are a way we can send documents to be signed and only change the recipient-specific information. We’ll set up a sample document for use in the rest of the flow below. This example form from Carleton University is small and contains a name field and signature that we will use. Note that we have no affiliation with this university, but it was a nice simple form we found on Google.

1. Navigate to the DocuSign Templates section.
2. Click NEW then Create Template
3. Add a Template name and Template description
4. Upload your document to be signed
5. Under Add recipients, add signer under Role, leaving everything else the same
6. Click NEXT at the bottom
7. Select Delete data if DocuSign finds PDF form field data in your uploaded document. Click CONFIRM.
8. In the Standard Fields selection on the left, select Signature and drag it to the place where you want the signature to appear on your document
9. With the signature field selected, ensure Required Field is checked on the right side
10. In the Standard Fields selection on the left, select Name and drag it to the place where you want the signer’s name to appear on your document
11. Click SAVE AND CLOSE
12. Click the name of your template in the list of templates that appear
13. Click the Template ID field below to display the Template ID. Copy and store it securely.

---

Creating a DocuSign Appian Application

Depending on your license, as well as your current platform architecture, you will likely want to create a new Appian application to hold all of your DocuSign objects. This approach has a few benefits, namely

• logical separation of a platform-level implementation from application-level code, and
• easier deployments as we will only be dealing with objects that directly relate to the DocuSign implementation.

If we take this approach it is important to ensure the security groups are setup such that your users are able to consume all of the objects we’re going to create with the correct permissions.

Design Approach

We are looking to accomplish a few goals with our implementation.

1. Create a generic application that can be consumed by any of our applications that require a document signing flow.
2. Keep our process models short-lived (for performance)
3. Segment our processes by events (e.g., one process model for user declines to sign, and one process for user signs successfully) instead of adding all of the events to one catch-all model. This helps with maintainability and system performance.

Keeping these goals in mind, let’s walk through the application and objects we’ll create in our DocuSign application.

DocuSign Application

1. Click New Application in Appian Designer.

2. Fill in your application details and make sure to check Generate groups and folders to secure and organize objects.

You should now have your fresh application scaffolded for you and we can begin fleshing it out.

Groups

When we created our application, Appian created us our Administrators and Users groups. The only other group we should add is an Alerts group to which we will send all of our process alerts.

1. Create a new group called Alerts. We’ll make our Users group the parent, but the rest of the information can be left as default.

CDTs

Our approach here is to map the DocuSign objects that we will be using (all of which are nicely laid out in DocuSign’s REST API Reference). We will not be adding them to a Data Store, as we don’t plan on writing any of them to the database. Create each of the CDTs outlined below in the order presented, ensuring all of the CDTs are in your DocuSign application namespace.

Connect Event Data

Connect Event Data will allow us to specify what information DocuSign will send back to Appian when Envelope and Signer events occur.

Event Notification

The Event Notification object allows a message to be sent a specified URL when the envelope or recipient changes status.

Template Role

This object allows us to specify a recipient of the documents (in our case we’re using templates) we will be sending via DocuSign.

Envelope

Envelopes are the containers for DocuSign transactions. They contain:

• One or more documents that will be signed electronically
• Information about the sender
• Information about the recipients, including all other objects (such as tabs) that are associated with those recipients
• Status information that tracks delivery and signature progress

Connected System

We will now create our connection to DocuSign. Ensure you have followed the steps in DocuSign Apps and Keys above, as we will be using a number of parameters from that step here.

1. Create a new Connected System in your Appian application. We’ll call ours TD DocuSign.
2. Select JWT Grant as the Authentication
3. Add the API Account ID value from your DocuSign Apps and Keys
4. Under API Username, you will need to add the User ID from your DocuSign user. This can be found in the specific user you added in Users.
5. Ensure the only DocuSign account you are actively logged in with is the same account as the User ID you are using.
6. Enter the Integration Key from your DocuSign Apps and Keys
7. Add the Private RSA Key that you stored from your your DocuSign Apps and Keys
8. Navigate to the following URL, ensuring you replace YOUR_INTEGRATION_KEY with the Integration Key you entered above.

   https://account-d.docusign.com/oauth/auth?
   response_type=code
   &scope=impersonation signature
   &client_id=YOUR_INTEGRATION_KEY
   &redirect_uri=https://www.taberna.tech

   If you have done it correctly, you should see the image below. When you deploy your application to production, you will need to do this step again, replacing account-d with account.
9. Select Development as the DocuSign Environment
10. Click TEST CONNECTION. You should see Connection successful (as in the image below).
11. Click CREATE
12. Click SAVE after reviewing the security (the default should be fine)

Expression Rules

The following expression rule will allow for repeatable construction of your DocuSign envelopes, abstracting as much boilerplate code as possible.

DocuSign Envelope Constructor

This will be used every time we want to create a new DocuSign Envelope.

1. Create a new Expression Rule, adding an appropriate name (e.g., TD_ConstructDocuSignEnvelope) and description

2. Add the following rule inputs

   Name	Description	Type	Array
   emailSubject	The subject of the email that DocuSign will send to your signers	Text	-
   eventNotificationUrl	The Web API URL that will receive your DocuSign events	Text	-
   templateId	The ID of the DocuSign template that will be signed	Text	-
   templateRoleList	A list of the Template Roles for the envelope	TD_templateRole	☑

3. Add the following expression definition (names assume you followed the naming convention we have used here)

   'type!{urn:com:appian:types:TD}TD_envelope'(
      emailSubject: ri!emailSubject,
      eventNotification: 'type!{urn:com:appian:types:TD}TD_eventNotification'(
         deliveryMode: "SIM",
         eventData: 'type!{urn:com:appian:types:TD}TD_connectEventData'(version: "restv2.1"),
         events: "envelope-completed",
         includeOAuth: true,
         loggingEnabled: true,
         url: ri!eventNotificationUrl
      ),
      status: "sent",
      templateId: ri!templateId,
      templateRoles: ri!templateRoleList
   )

4. Ensure you add some test cases!

Integrations

We’ll now setup two integrations - one to create and send a document to a signer, and one to download a document (in our case it will be the signed document).

Create and Send Envelope

1. Create a new Integration using the TD DocuSign Connected System we created

2. Give the integration an appropriate name (e.g., TD_createAndSendEnvelope)

3. Add a description

4. Click CREATE. The new integration should open.

5. Add the following rule inputs (they’re the exact same as in our envelope constructor)

   Name	Description	Type	Array
   emailSubject	The subject of the email that DocuSign will send to your signers	Text	-
   eventNotificationUrl	The Web API URL that will receive your DocuSign events	Text	-
   templateId	The ID of the DocuSign template that will be signed	Text	-
   templateRoleList	A list of the Template Roles for the envelope	TD_templateRole	☑

6. Enter the following code as the Envelope Definition

   a!toJson(
      rule!TD_ConstructDocuSignEnvelope(
         emailSubject: ri!emailSubject,
         eventNotificationUrl: ri!eventNotificationUrl,
         templateId: ri!templateId,
         templateRoleList: ri!templateRoleList
      )
   )

7. Check Would you like to send the envelope to the signers?

8. Leave the Document untouched, as we’re using Template instead of composing documents in Appian

Download Document from an Envelope

1. Create a new Integration using the TD DocuSign Connected System we created

2. Give the integration an appropriate name (e.g., TD_downloadDocumentFromEnvelope)

3. Add a description

4. Click CREATE. The new integration should open.

5. Add the following rule inputs

   Name	Description	Type	Array
   envelopeId	DocuSign envelope ID	Text	-
   documentId	The ID of the DocuSign document to download	Text	-
   folder	The folder in which documents will be saved	Folder	-

6. Set Envelope ID equal to ri!envelopeId

7. Set Document ID equal to ri!documentId

8. Set Save Document In equal to ri!folder

---

Creating DocuSign Envelopes in Appian

In this section we’ll walk through creating an application through which we will send and receive DocuSign envelopes.

Consumer Application

We’re going to create a new application as part of the guide in which we’ll consume our DocuSign application objects in order to send and receive envelopes. You may already have an application in which you wish to do this, so a brand new application isn’t strictly necessary for this part.

If you’re going to set up a new application, you can follow the same steps outlined in the DocuSign Application we added above. The one we have created for our demonstration here is called Taberna Signature (TS) so you’ll see the TS prefix throughout the remainder of the guide.

Folders

We need a folder to store documents that have been successfully completed in DocuSign.

1. Create a Document Folder, providing an appropriate Name and Description
2. Create a constant pointing to your new folder. This is also outlined in Constants

Groups

In order for DocuSign to call us, the DocuSign service account must be added to our application users as well as be an editor on the Knowledge Center to which our Downloaded Documents Folder belongs.

1. Create a Knowledge Center Editors group as a child of your Users group. The default settings are fine.
2. Add the DocuSign service account that was created during the OAuth 2.0 Client setup to the Knowledge Center Editors group.
3. Add an Editor permission on your Knowledge Center for the new Knowledge Center Editors group.

Process Models

We are going to build 2 process models. One will create and send a document for us and the other will handle envelope completion events from DocuSign.

Create and Send Document

In this process model we will construct a new envelope and send it to DocuSign for signature. For the purpose of the demo, we will be hardcoding the recipient data in a script node, but by providing recipient data into the process model via an interface or separate process, you can extend this process to make it fit in your application with only minor changes. In our implementation, it would be best not to have a script node and just implement the hard-coded role in the input field of the integration node, but by doing it this way, we allow for easy replacement in your implementation.

1. Create a new process model, providing an appropriate name and description.
2. Adjust your alert settings to notify the proper user group(s)
3. Create a new process variable called templateRole of type TD_templateRole
4. Create a script node in which you output the following values to your templateRole variable. cons!TS_TEXT_DOCUSIGN_ROLE_SIGNER is defined below.

   'type!{urn:com:appian:types:TD}TD_templateRoles'(
      email: <YOUR EMAIL>,
      name: <YOUR NAME>,
      roleName:  cons!TS_TEXT_DOCUSIGN_ROLE_SIGNER,
      routingOrder: 1
   )

5. Create a Call Integration node pointing to TD_createAndSendEnvelope, ensuring a 1:1 mapping of the integration rule inputs in the input fields of the Data tab.
   • Set the subject to any text you’d like
   • Set the eventNotificationUrl to equal cons!TS_TEXT_DOCUSIGN_EVENT_ENDPOINT. This is outlined in Constants and Web API.
   • Set the templateId to equal cons!TS_TEXT_DOCUSIGN_TEMPLATE_ID. This is outlined in Constants.
   • We only have a single templateRole so you’ll need to set the value of templateRoleList in the expression editor to be equal to our process variable.
6. Save and Publish your process. It should look like the image below.

Handle Envelope Complete

In this process model we will handle the event that DocuSign sends when an envelope is completed (i.e., all documents are signed).

1. Create a new process model, providing an appropriate name and description.
2. Adjust your alert settings to notify the proper user group(s)
3. Create a new process variable called body of type Map. This allows us to take an unshaped set of data that DocuSign provides and parse the envelopeId.
4. Create a Call Integration node pointing to TD_downloadDocumentFromEnvelope
   • Set the envelopeId to pv!body.data.envelopeId
   • Set documentId to 1. Note that we can do this because we know there is only 1 document we are signing and the only one we want back is the signed document. This will not be the case in every implementation.
   • Set folder to TS_FLDR_COMPLETED_DOCUSIGN_DOCUMENTS (as outlined in Constants)
5. Save and Publish your process. It should look like the image below.

Web API

Our Web API will be used to receive notifications from DocuSign for the events we indicate in our envelope.

1. Create a new Web API
2. Select Create from scratch
3. Add an appropriate Name and Description
4. Select POST as the HTTP Method
5. Set an appropriate Endpoint value (e.g., docusign-event)
6. Click CREATE
7. Confirm the security settings look good and click SAVE
8. Set the expression equal to the code below.

   a!localVariables(
      local!body: a!fromJson(http!request.body),
         a!match(
         value: local!body.event,
         equals: "envelope-completed",
         then: a!startProcess(
            processModel: cons!TS_PM_HANDLE_DOCUSIGN_EVENT_ENVELOPE_COMPLETED,
            processParameters: { body: local!body },
            onSuccess: a!httpResponse(statusCode: 200),
            onError: a!httpResponse(statusCode: 500)
         ),
         default: a!httpResponse(statusCode: 200)
      )
   )

Constants

Ensure the following constants have been created for your application.

Sending the Document

Now that everything has been tied together, let’s try it out.

1. Start your Create and Send Document process (you can use Start Process for Debugging). This should successfully call DocuSign.
2. Check your email for a message from DocuSign with a link to sign your document. Click through to the signing link.
3. Click to sign your document in DocuSign.
4. Click Finish.
5. Check the monitoring tab of your Appian instance for a completed instance of your Handle Envelope Complete process.
6. Once you see it complete successfully, check your Completed Documents Folder. You should see a signed PDF inside that looks like the document below. As you can see, we’ve successfully added a signature and the signatory’s name.

---

What We Didn’t Cover

DocuSign has a vast number of features and we have only scratched the smallest of surfaces here, to provide you with a good foundation for the remainder of your DocuSign implementations. Most notably, we didn’t touch on any of the following topics, but the objects we have created allow for all of them with only small enhancements.

• Multiple signers
  • Documents can be signed by more than one signatory in any combination of signing orders.
• Signer authentication
  • Signers can be authenticated in a number of ways, including SMS and a provided access code.
• Embedded signing
  • You can embed the DocuSign signing ceremony within your Appian application to gather signatures as part of your business workflow.
• Composite templates
  • You can combine your standard DocuSign templates with dynamically created Appian documents in one envelope.
• Error handling
  • We have not handled any integration errors in this demo. This is not best practice and any production application should contain a robust error handling framework.
• Other roles
  • Some document signing flows involve roles where users won’t be signing the documents but must view or receive the envelope.
• Other events
  • DocuSign users can decline signing, envelopes can be voided, and we can add a number of other nice-to-have events. We didn’t touch on any of these topics but a robust production application should at the very least handle the event where a recipient declines to sign.

---

Conclusion

We’ve now set up a straightforward signing flow from Appian to DocuSign. Our pattern is extensible and you can easily expand it to include multiple signers, multiple documents, or even multiple roles.

Do you need help implementing your document signing flow? Do you have any questions on how to implement any of the feature we didn’t cover? Don’t hesitate to reach out to us. We’d love to work with you!