Configuring DocuSign in ClientSpace

Docusign is one of the most widely used e-signature applications in the world allowing you to sign documents anywhere from any email-enabled device without overnighting, faxing, or waiting. The following document describes how to configure ClientSpace to connect to DocuSign through the API and provide integrated electronic signatures for your ClientSpace documents.

The DocuSign API requires the purchase of DocuSign licensing. You should discuss DocuSign licensing with your account manager prior to configuring DocuSign in your ClientSpace installation.

Before You Begin

Before you begin your DocuSign configuration, contact your DocuSign representative to request the following API login information. You must have this information before you begin configuring the ClientSpace DocuSign API:

Username: DocuSign user account code. Provided by DocuSign as the API UserName and is in the form of a Globally Unique Identifier or GUID, a 32-digit character string formatted as xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx.
Password: DocuSign user account password. Provided by DocuSign.
Endpoint: This is the DocuSign server URL to connect to their system and is determined and provided to you by DocuSign.

Step-by-step guide

DocuSign Configuration

Configuring the DocuSign API is a multi-step process.

The process includes:

An API configuration to enable ClientSpace to log in to DocuSign
A triggered email template that acts as the main conduit for the transfer of information between ClientSpace and DocuSign
Several scheduled processes that periodically review queued DocuSign requests and also sweep through DocuSign to gather document changes which it then pushes into ClientSpace

API Configuration

API Configuration connects ClientSpace with the third-party software API. Most of the following settings must be provided by your DocuSign representative before you begin the configuration.

Go to System Admin > Advanced > API Configuration.
The API Configuration list is displayed
Click Add.
The New API Configuration form opens.
Complete the form fields:
Items marked with an asterisk * should have been provided by your DocuSign representative. If you have not received these, stop and contact DocuSign.
- API Type: DocuSign
- Application Code: DOCUSIGN
- Application Name: DocuSign
- Username*: DocuSign user account code. Provided by DocuSign as the API UserName and is in the form of a Globally Unique Identifier or GUID, a 32 digit character string formatted as xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx.
- Password*: DocuSign user account password. Provided by DocuSign.
- Description: DocuSign account info. This is customizable but should be a brief description of how you are using DocuSign in your ClientSpace environment.
- Endpoint*: Provided by DocuSign. This is the server URL to which we connect.
- Secondary ID: Integration key (Contact the BA of the Account for Key).
- Logging Level: not used
- Additional Parameters: not used
- Active: Inactive API configurations are ignored.
Click Save.

Email Template Configuration (Step 1)

The next step is to configure an email template.

Go to System Admin > Email Templates.
The Email Templates list is displayed.
Click Add.
The Add Email Template form opens.
Complete the form:
- Type: Select DocuSign.
- Table Name: Select the dataform to which this DocuSign process will be connected.
- Template Code: Provide a unique value to identify this Template.
- Template Name: Provide a brief, descriptive name for your template. The name is visible in list view.
- API Configuration: Select the API config that contains the DocuSign login and connection record.
- Description: Provide a brief description. The description is visible in list view.
- Subject: Text data containing the Email Notification Subject - this will be visible in the docusign email received. Note - Docusign email templates cannot contain replaceable fields.
- Body: HTML text data containing the Email Notification Body text - Nothing from this field will be used in Docusign email functionality. Note - Docusign email templates cannot contain replaceable fields.
Click Apply.
Click Next.
The Triggering (Step 2) form opens.

Email Template Triggering (Step 2 optional)

The next step is to define the trigger. This step is optional.

Complete the form fields:
- Trigger Field: Select the field from the dataform you selected in Step 1, which, when changed will trigger the DocuSign Send request.
- Execution Pipeline: Select the execution pipeline that determines the rules to trigger (defaults to Default).
- Execute On: This determines whether the email will be sent the first time the form is saved, only when the form is changed, or every time.
- Merge Procedure: Note - Docusign email templates cannot contain replaceable fields.
Click Apply.
Click Next.

Email Template Addresses (Step 3)

Step 3 defines who the email is from, who it will be sent to, and any CC recipients. You can also use a custom stored procedure to include email addresses from system objects other than the triggering form.

Complete the form:
- Address Stored Procedure: This optional stored procedure generates data that provides the additional recipient email address from system objects, such as user fields, other than those that may be selected below.
- From Address: Select the "From" address for this email template. It can be set from a specific user, the current user, or from a field on a form.
  Unlike other email templates, the address portion of the DocuSign template determines to whom the email is sent, and the order of delivery, and actions they must take to move the document to its next step.
Click Add.
A row opens to provide the following: Type, Address, Legal Name, Signature Order, Signature Type, # Tabs, Signature Anchor, Display Text, Label, and Ignore if not present.
Configure the row using the Configuring addresses table.
When you are done, click Apply and then click Next.

Configuring addresses

Source	Choose a source from which the recipient is selected. Options include recipient stored procedure, user fields from a single dataform in the system (the system uses this field to find the email address of the associated user record.), or Adhoc email address (see below). To choose the recipient stored procedure, a stored procedure must be specified (see above). The Recipient Procedure must contain the following input parameters, even if they are not all used: @Key int @ProjectID int @ProjectTypeID int For more information about using a custom recipient stored procedure, contact one of our application specialists.
Type	Defaults to Signer
Address	If you selected Adhoc Email in the recipient source, use this field to store the email address to which you would like to send, such as bsmith@test.com
Legal Name	Store the Legal Name of the Adhoc email here, such as Robert Smith. If a field on a form was selected as the Source, this will be set to "TBD" and automatically filled when the email is sent.
Signature Order	This field determines in which order the signature fields will be presented in DocuSign. A recommended best practice is to use the order the signature tags are presented in the document, top to bottom, left to right as the signature order.
Signature Type	The signature action selected places the appropriate custom field on the form when it is compiled in DocuSign. We are not literally adding checkboxes and SSN boxes to the form, we put the action tag in the document and let Docusign do the heavy lifting for us when the document is compiled at DocuSign. These signature actions range from Approval, to initial, to sign here, and many other tags. Custom tags, such as custom formatted fields and Radio buttons require the assistance of an application specialist.
# Tabs	If Ignore if not present is enabled, the # Tabs field clones the Recipient and Tabs for the required number of Tags, appending "-1", "-2", and so on to the end of the tag. This provides a dynamic number of Tags generated by the merge SQL and placed into the document while only having to set up one Recipient record on the email template. Let's say you have a /Name/ tag for the signees name. Instead of creating separate /Name/-1, /Name/-2, /Name/-3 recipient entries, you would create a single recipient entry with the tag of /Name/ and set # Tabs to 3. It is a best practice to check the Ignore if not present option otherwise, DocuSign will reject the document if all tabs are not present.
Signature Anchor	This is the custom tag that you embed in your DocuSign document that is used to merge the Signature action in DocuSign. While there is no set standard, it is important to use a custom tag that will not occur naturally in written text. An example of a signature location for Initial 1, for example, could be /init1/. The associated tag in the merged document must match this signature pattern exactly. If a Signer must sign in multiple tags on a document: Create multiple Recipients for that Signer Legal Name and Email Address MUST BE IDENTICAL Routing Order MUST BE UNIQUE Signature/Initial/Date Locations MUST BE UNIQUE
Display Text	This is displayed near the signature location as instructions on what to do in DocuSign. Continuing the example above, an initial location might have a signature display text of “Initial Here”. Check Boxes might say “Select All that Apply” and so on.
Label	Descriptive text that is displayed in the ClientSpace list to provide a more complete description of that recipient item. For example, instead of multiple “Signature” items in the list, you may want to use the label to indicate the type of signature, such as “Principal Signature” or “Risk Signature” and so on.
Ignore if not present	DocuSign allows you to include a parameter on each Recipient/Tab in the envelope called Ignore if not present. This enables you to define and include a recipient and associated tags in the envelope but not throw an error if that tag is not found in the envelope's documents. This makes tags optional because the system allows the send to DocuSign with or without tags marked in this way. Always check this when the # Tabs property exceeds 1.

Action Tips

To ensure the signature action items are accurately placed in your document when compiled in DocuSign, add a text box to the document where you would like the DocuSign object to be placed, then put your signature tag within the text box. Textboxes allow much more accurate placement of the final DocuSign object.
After you are happy with the placement and have tested to ensure everything is working, change the color of the signature tag font to match the background color of the page, making the tag disappear.
When using radio buttons or other custom grouped controls, use the property groupName. This allows configured radio buttons to be grouped appropriately. For more information about DocuSign, contact your Account manager.

Conditions (Step 4)

Conditions can be used in conjunction with, or as a replacement for a default trigger from the primary dataform selected in Step 1.

Complete the fields:
- Add: Click here to add additional triggering conditions. All conditions not included in a Condition Expression are treated as OR conditions.
- Field Source: What dataform or Stored Procedure will provide the triggering condition
- Trigger Field: Select the dataform or Stored Procedure field which will be compared to the trigger value.
- Operator: Choose the type of comparison.
- Trigger Value: The criteria against which the trigger field is compared.
- Condition Expression Label: The label to be used when constructing Condition Expressions for triggering. It is recommended that you keep this label short and representative of the Trigger Field.
- Condition Expression: Allows for AND as well as OR Conditions utilizing the Condition Expression feature. Using the Label field (see below) on the Condition you can combine trigger conditions into more complex expressions - for example (Condition1 AND Condition2) OR (Condition3 AND Condition4) OR Condition5. For a detailed explanation, see Condition Expressions.
  - If the Email Template trigger condition has been set in Step 2, then this dataform or task field (or HdrAction) must be changed to trigger the email to occur. In Step 4 you can also add more complex triggering conditions by choosing dataform/task field(s) and setting an Operator, Value, and Label.
    - If a Trigger action is selected in Step 2, these conditions are combined with the Trigger Action using an implied AND. If the Condition Expression field is not filled, the additional conditions that are set in Step 4 will all be treated as OR conditions, i.e., The Trigger Action AND Condition1 OR Condition2 OR Condition3.
  - If no Trigger Action is set in Step 2, these conditions are evaluated as either
    - A series of OR conditions if no condition expression is set (Condition1 OR Condition2 OR Condition3)
    - As a Complex expression if a condition expression is set using the Expression Labels (Condition1 AND Condition2) OR (Condition3 AND Condition4) OR Condition5.
  - If a Condition Expression is used, any conditions that are not included in the expression are ignored by the system.
  - For a detailed explanation about using conditions, see Condition Expressions.
Click Apply.
Click Next.

Attachments (Step 5) - optional

Attachments can be added at this step and are included with each copy of the email sent.

Complete the form:
- Mail Merge: Select the Mail Merge that will generate this DocuSign document (including the signature anchors set in Step 3).
- Link To Form: After the document has been signed, it can be returned to the system and attached to this form.
- Rename Signed Document: During the process that links the signed document to a form, the document can be renamed. Use this field to prepend the document name with an identifying tag.
- Link To Field: You can optionally select a file upload field on the "Link To Form" into which to save the document.
- Merge all Documents? - If checked, all signed and attached documents are merged into a single document.
- Add: Click Add to begin adding the attachment(s)
  - Dataform: Select the dataform from which the attachment will be copied.
  - Field: Select the field from the dataform selected previously that holds the dataform to be copied.
Click Apply.
Click Finish.

The DocuSign Process

The following contains technical process information for what happens at each step of the DocuSign API process.

Dataform Save Operation, Send File for Signatures

- Assuming trigger conditions are met and the Email Template type = DocuSign, the process continues

- System will Execute the Document Merge, renaming the file to RenameFileTo Additional Parameter from associated Email Template

- Retrieve Email Template Additional Parameters

"LinkTable", the dataform to attach the signed document
"LinkColumn", the field on the dataform to save the signed document (if not specified, the document will be attached to "LinkTable")

- Retrieve the RowGUID of the "LinkTable" dataform

- Create a new Uploaded Files Queue record (UFQ tblUploadedFilesQueue)

status = "new"
record type = "DocuSign"
DateQueued set to Now
ProcessingLog set to "Queue record created"
Subject set to Email Template Subject
set LinkTable, LinkColumn and LinkGUID values

- Attach Merged Document to new UFQ record (as an attachment)

- Create Document Signers (UFQR tblUploadedFilesQueueRecipient) records

Retrieve a list of Email Template Recipients
Resolve recipient proc recipients to 'Legal Name' and 'Email Address'
Resolve dataform recipients to 'Legal Name' and 'Email Address'
AdHoc recipients 'Legal Name' and 'Email Address' are stored when the recipient is created on Email Template
For each resolved Signer, create a UFQR record
- Legal Name
- Email Address
- Routing Order (Signing Order)
- Signature Location
- Initial Location
- Date Location

The document is then processed and sent to Docusign via the "DocuSign Request Signature" scheduled process.

Uploaded Files Queue Dashboard

The Uploaded Files Queue Dashboard provides insight into where your document is in the DocuSign Process and is updated automatically via the "DocuSign Get Docs Status" scheduled process.

Uploaded Files Queue Dashboard

To access the dashboard:

Go to System Admin > Advanced > Uploaded Files Queue.
The Uploaded Files Queue list is displayed. From here you can search, view, and delete entries.
Select an entry and click View. Alternatively, you can (Jump) to the record from the row entry.
The Uploaded Files Queue Detail page opens. The detail page is read-only.
- To view signed and unsigned files attached to this record, click Attachments.
- Queue Status displays the current status in the DocuSign pipeline.
- Signers displays a list of signers and associated email addresses who received the DocuSign item along with the requested action for them to take.
- Log Data presents detailed information about the DocuSign process.

Voided Documents

The DocuSign process handles void documents, allowing the user to void a document that has already begun processing through the DocuSign system.

This is accomplished via two business rules specifically for Void documents:

The biz rule (core) _VoidDocuSignDocument updates the Uploaded Files Queue record status to voided. The scheduled process "DocuSign Request Signature" voids the envelope(s) in DocuSign. The Scheduled process "DocuSign Get Docs Status" retrieves any voided documents and attaches to the dataform if configured to attach (otherwise the voided document is attached only to the Uploaded Files Queue record).
A new soft error (core) _SE_VoidDocuSignDocument warns the user that documents (envelopes) will be voided. This rule will also identify the number of envelopes that are affected.

Both rules are configurable with the following parameters:

DataformOnly (checkbox). When checked, only voids envelopes (and thereby documents) associated with the Dataform on which the rule is configured. When unchecked, voids all envelopes in the Workspace associated with the Dataform on which the rule is configured.
AllowVoidStatus (comma delimited string). Provide the statuses of Uploaded Files Queue records that can be voided. See the Signature Status lookup group for valid statuses and use the CODE in this parameter, separated by a comma, with no spaces.

Scheduled Process Descriptions:

"Request Signature" Scheduled Process

When the Request Signature Scheduled Process runs, it performs the following actions:

- Retrieve a list of all UFQ records with status = "new"

- Retrieve a list of Document Signers for this UFQ record

- Retrieve the LinkGUID of the unsigned document attached to this UFQ record (this file was attached when the Email Template triggered)

- Retrieve the file data for this LinkGUID

- Construct an Envelope Definition packet

- add Document bytes
- add Document Name
- add Signer 'Sign', 'Initial' and 'Date' tabs for each Signer(s)
- set Envelope status = "sent" (instructs DocuSign to immediately send this document out for Signatures)

- Send Envelope Definition to DocuSign

- Updates UFQ status = "sent"

"Get Docs Status" Scheduled Process

The "Get Docs Status" Scheduled Process performs the following actions when it runs:

- Retrieves the Envelope ID and Status of all DocuSign Envelopes since the earliest UFQ Last Checked date (where UFQ status != "processed")

- The system attempts to match Envelope ID's to UFQ SecondaryIdentifier values

- If there is no matching UFQ record, the message envelope is ignored

- Match found

if UFQ status = Envelope status, ignore as nothing has changed
if UFQ status = "processedsigned/processeddeclined", ignore as this Envelope and UFQ record no longer need to be managed
if Envelope status = "completed", download signed document, UFQ set to "processedsigned"
if Envelope status = "declined", download declined document, UFQ set to "processeddeclined"
if Envelope status = "created, deleted, delivered, signed, sent, voided, correct", update UFQ to that status, do nothing with the document

The final step in the DocuSign process is to Download Signed or Declined document (from Get Docs Status).

This step will:

- Get 'combined' document set from DocuSign by Envelope ID

- Store file locally in AppVar "TempPath" + "/docusign"

- filename is 'newguid' + "_tempdocusignfile.pdf"

- Upload file to ClientSpace

- rename file to 'envelopestatus' + "_" + RenameFileTo Additional Parameter (envelope status will be 'COMPLETED' or 'DECLINED')
- attach file to UFQ record (always as an attachment on the record)
- attach file to Dataform record
  - Email Template "LinkTable" additional parameter
  - Email Template "LinkColumn" additional parameter (if empty, file is stored as an attachment to the dataform)
  - always save the LinkTable dataform record
  - HdrAction = "DOCUSIGN_COMPLETED" or "DOCUSIGN_DECLINED"
  - Pipeline = "DocuSign"
  - RulesToRun = "BizLogic"
  - If LinkColumn is specified, that field will contain the signed/declined file

- After the file is uploaded, the temp file is deleted

KnowledgeSpace

Configuring DocuSign in ClientSpace

Step-by-step guide

API Configuration

Email Template Configuration (Step 1)

Email Template Triggering (Step 2 optional)

Email Template Addresses (Step 3)

Conditions (Step 4)

Attachments (Step 5) - optional

Dataform Save Operation, Send File for Signatures

Uploaded Files Queue Dashboard

Related articles