How to initiate a Bulk Send and update Salesforce records


Note: This is a custom workflow not supported by DocuSign Support. If you need assistance with this flow, please contact your Account Manager to schedule time with our Professional Services team.
 

Objective

The objective of this article is to demonstrate how you can integrate DocuSign's bulk sending feature and Salesforce. 

Overview

DocuSign’s enhanced bulk send feature allows senders to easily send a standardized document to many recipients at one time. As the envelopes sent using this feature are not sent from Salesforce, some of the challenges users face when combining a bulk send solution with their Salesforce organization are:
  1. How do I merge data from Salesforce into a DocuSign envelope?
  2. How do I publish updates from the bulk send envelopes into Salesforce?
  3. How do I relate the DocuSign Envelopes' Statuses to Salesforce records?
  4. How do I attach the completed document to the Salesforce records?
Without a customized Connect configuration, the individual Salesforce records that are related to the recipients of the bulk send cannot be updated. These challenges are important to address in order successfully migrate data from bulk sending to Salesforce and will be discussed in the following article.

Pre-Requisites

Task List Overview / Table of Contents

  1. Create a Custom Salesforce Report
  2. Create DocuSign Template
  3. Create DocuSign Custom Connect Workflows
    1. Update Recipient Status
    2. Update Salesforce Record (field values)
    3. Attach Completed Document
  4. Modify your CSV file for bulk sending
  5. Send the Bulk Send
  6. Following the Envelope's Status in Salesforce

Example Use Case

I am an owner of a gym called "Average Joe's Gym". I have made changes to my "Waiver and Assumption of Risk" document that I need all my current members to fill out and sign. In my waiver form, I also have a section to provide an emergency contact.

Here are the requirements that have been determined:
  1. Send the new waiver form to all active memberships.
  2. Pre-populate the membership number in the form from Salesforce. (Steps 2-4 are done as a courtesy to the member so that they don't have to fill in this information themselves in the Documents they sign.)
  3. Pre-populate the name of the membership owner from Salesforce.
  4. Pre-populate the emergency contact information from Salesforce.
  5. Allow the member to update emergency contact.
  6. Updates of the emergency contact should publish into their Contact record in Salesforce.
  7. Ability to track DocuSign Envelope recipient status on the Contact record.
  8. Signed version of the waiver form should publish to Notes and Attachments/Files of their Contact record in Salesforce when the Envelopes are completed. 
 

Create a Custom Salesforce Report

Overview

In order send an envelope in bulk, we will need to create a .csv file which will contain the list of all the contacts. Instead of creating this from scratch, we can leverage reports from Salesforce. Conveniently, Salesforce has the ability to output a custom report in a .csv format.

Steps (for demo purposes only)

Open the Reports application or tab in Salesforce.com, and start/create a new Report.
Select New Report button. 
One of the requirements was to send all "Active" members the new waiver form.
When creating my custom report, I started with Contacts & Accounts.
All my Contact records have a picklist label "Membership Status". In my report I made sure to filter off this field with the value of "Active".

In Salesforce Classic this could look like this: 
User-added image

I need to also gather the Gym Members' Names and Email Addresses. I've added the following columns to my report:
  1. Name
  2. Email Address
  3. Membership Number
  4. Emergency Contact
  5. Emergency Phone
  6. Relationship
  7. Contact ID (or "Record ID" as applicable to your scenario)
Notice I want to gather the "Contact ID" of each Contact or "Gym Member" in Salesforce. This will be important later as we want to write back the Emergency Contact information to specific Salesforce record pages in Salesforce and will use this to map that data.

Run the Report and click the button "Export". Within the Export File Format picklist, choose "Comma Delimited .csv". The default Export File Encoding choice is fine.

In Salesforce Classic this could look like this: 
User-added image

In Salesforce Lightning this could look like this: 
User-added image

Select the "Export" button to download the .csv file. Open the .csv file and save it somewhere to your computer or network that you can access later. 

Salesforce may add additional copyrights and meta data on who generated the report in your .csv file. Make sure that is removed for our purposes of handling the .csv file later. Re-Save your .csv file after deleting the excel rows, like those below, if applicable. 

User-added image
 

Create a DocuSign Template

Overview

Next, you will build a DocuSign Template which will be used to determine how the Envelopes will be sent. See an overview video on DocuSign Templates here if this is a new concept to you.
  1. Set a Template name.
  2. Then upload a sample base document that is, in my case, the "Waiver and Assumption of Risk" document that I want my Members to fill out and sign. 
  3. Add a Recipient Role like "Member" in my example. Leave the name and email fields blank.
  4. Set the Subject line to something appropriate; for my example it's "Please DocuSign: Waiver an Assumption of Risk Document". 
  5. Optional: After the Subject line place a dash and insert a merge field to dynamically input data that's specific to the Envelope when it becomes created. Click the box with an arrow inside it on the Subject line row and choose "[[Member_UserName]]" for example. If used, this will result in each Envelope that is sent out having a unique subject line, and thus easily identifiable later. 
  6. Optional: Enter a Message to all Recipients. 
  7. Optional: Click "Edit" next to Advanced Options and verify the settings of the Template so that you understand how the Envelopes will inherit certain settings when you proceed to Bulk Sending later. Adjust them as necessary, click Save. 
  8. Click NEXT.
  9. Add any Initial fields, Signature fields, or Date Signed fields, as needed. 
  10. Add Text fields to the document where data will be entered like the Membership Number, Emergency Contact info, etc. that we downloaded earlier from the Salesforce Report. After adding several text boxes to your document, click on them one at a time and set the property named Data Label to an easily identifiable term. A Data Label, also known as the name of the field, contains a field identifier that is only visible to the sender and will be used later to map the data in your .csv file into the Envelopes created in the Bulk Send upon the send process. The Text field that will be used for Membership Number for example will be labeled as "Membership Number". 

Example

CSV Column Header and data from the Salesforce Report:
User-added image

Template's Text Field's Data Label property, labeled appropriately to match:
User-added image
  1. Click SAVE AND CLOSE

IMPORTANT!

In your DocuSign Template, make sure to include a Text field that will be reserved for populating the Contact ID/Record ID. DocuSign's Connect feature will need to reference the Contact ID in order to publish data back to Salesforce records after the Bulk Send has actionable events (Sent/becomes Completed/is Voided, etc.). We'll pick this back up in the section "Following the Envelope's Status in Salesforce". 

Click on your Template, then click Edit. Or choose the dropdown arrow and select Edit. Create/Find the Text field with the Data Label "Contact ID" in the Template, after clicking NEXT, and set the following properties. (Select the field once to then see the Properties on the right hand side): 
  1. Ensure Contact ID is set for the Data Label.  
  2. Check the checkbox next to Read Only. (This will ensure that your recipients cannot change the value of this field.) 
  3. Expand Formatting, change the font color to " White". (Since my document is also white and the field is read only, this will hide the field from the recipient during signing, yet it will be on the document for purposes of connecting the final document back to a Salesforce record.)
  4. Place the Text field in an area of the template where there is no text, but only the background of the page. I placed mine in the upper, right-hand corner of my document.
  5. Save your Template by clicking SAVE AND CLOSE.
 

Create Custom Connect Workflows

Overview

DocuSign Connect for Salesforce is a push service that publishes envelope data back to connected applications, in this case Salesforce. With Connect, Envelope statuses, data, and signed documents can update in Salesforce as needed, per Connect's settings. 


Update Recipient Status

Overview
DocuSign Recipient Status is a default Connect object and workflow. When creating Envelopes from a Contact record with DocuSign for Salesforce, the Recipient Status records are automatically created and related back to the Contact record, because in this workflow the Record ID/Contact ID becomes an Envelope Level Custom Field that is not shown through that process, but happens behind the scenes. Since in this exercise you will send Envelopes from the DocuSign web application (DocuSign.com), we need to create a custom workflow in order to relate the status to the appropriate Contact record in Salesforce. Without this step, Recipient Statuses would be created in Salesforce (and could make their journey to DocuSign Recipient Status records, e.g.), but they would not relate to any specific Contact records. 
Steps
Log into DocuSign and navigate through the following as an Administrator:
  1. Go to Admin from the top, right corner menu.
  2. Optional: Select the correct Account, if you have multiple. Click on Accounts tile if you are an Organizational Administrator.
  3. Click on Connect on the left side bar. 
  4. Click on the Salesforce Configuration. (Note: if this is not present, we recommend you install and configure DocuSign for Salesforce.)
  5. Select the "New Object" button and click Salesforce Object to build a new Custom Connect Object.
User-added image

This will launch the "Object Edit" view
User-added image
 
  1. Update the Object Name, and Description (Not required). I've named mine "Bulk Send Recipient Status".
  2. Select DocuSign Recipient Status from the Select Salesforce Object dropdown. (Note: that choice may be near the bottom of the picklist.)
  3. Optional:  We will keep Add if no match unchecked so we can update only existing records in Salesforce (Our Gym Member's Record pages).
  4. Select Inactive Object at the top of the page and choose Activate Object.
  5. Set Select Where section as follows: 
    • Salesforce.com Field set to Record ID (id)
    • DocuSign Field set to Recipient Secure Field. Then set the additional text box that appears to "Record ID". This matches what we set on the DocuSign Template's Text Field Data Label. Use "Contact ID" if that's what you named the field in your Template. 
  6. Set the Update Fields section as follows:
    • Salesforce.com Field set to Salesforce Source ID (string)
    • DocuSign Field set to Recipient Secure Field (aka DocuSign field or tag)
    • With Recipient Secure Field selected, an additional field will be available to populate which represents the "Data Label" or name of the DocuSign field we set earlier. In my use case, this is Record ID.
    • Ignore the Attachments section; keep these unchecked for now. 
Example of a Custom Salesforce Object below:

User-added image

DocuSign Connect for Salesforce has the capability of running multiple workflows or Connect Configurations, one after another. It will attempt to execute them listed, when active, in a top to bottom logical, step by step fashion. 

User-added image

It is very important to run this custom work flow after the original "dsfs__DocuSign_Recipient_Status__c"

The dsfs__DocuSign_Recipient_Status__c is creating the statuses. Our custom work flow is updating those statuses so that they relate to a Contact record. If our custom work flow was executed before the record's creation (or in other words listed above dsfs__DocuSign_Recipient_Status__c in the Connect Objects list), it would fail to update because you can't update a record that does not yet exist.
 

Update Salesforce Record (field values)

Overview
The purpose of Connect workflows (objects) is to update or create new Salesforce records based off DocuSign metadata or field data that is mapped to Salesforce fields. We can leverage Connect again to publish data populated by the customer to push directly into Salesforce.
 
Steps
  1. Create custom Connect object
  2. Update the Object Name. Update Description (Not required)
  3. Select Salesforce.com Object is always the object you will be updating, in this use case it is Contact
  4. This use case is designed to update existing Contact records, so we will keep "Add if no match" disabled / unchecked.
  5. Set Select Where
    1. Salesforce.com Field set to Contact ID
    2. DocuSign Field set to Recipient SecureField
When the new blank field appears below "Recipient Secure Field", enter the Data Label (which is the name of the Field in DocuSign) that will match the record id field referenced in the CSV output from Salesforce ("Contact ID"). This specific step is allowing us to select one Salesforce record to update based off the record ID referenced from the CSV file. If you're more familiar with Salesforce SOAP API, it's equivalent to defining the id field within an update request.
User-added image
  1. Update Fields
For this section, you'll be mapping the Fields from DocuSign to fields in Salesforce that need to be updated or "written back" upon the Connect events triggering. Examples of these mappings are seen in the below image. One such example is: 
  1. Salesforce.com Field - Set to Emergency Contact (string)
  2. DocuSign Field - Set to Recipient Secure Field, then "Emergency Contact" - or whatever the Data Label is for your DocuSign Field. With Recipient Secure Field selected, an additional field will be available to populate which represents the "Data Label" of the DocuSign field. In my use case, the fields I will configure are "Emergency Contact", "Emergency Phone", and "Relationship".
User-added image
 

Attach Completed Document

Overview
By default, completed documents will not relate to your Salesforce records. The steps below will have completed documents publish to the Notes and Attachments/Files related list of the appropriate Contact.
Steps
  1. Open the same Connect object you created in the previous section,
  2. Scroll to the very bottom of the configuration that is labeled Attachments,
  3. Select the attribute for "Attach DocuSign Documents"
  4. Select the sub attribute for "Completed envelope only"
User-added image

Now your objects list in Connect should look similar to the below:

User-added image

Closing remarks on Connect
  • You'll also notice that these custom Connect objects have two available attributes. Active and On Complete Only.
  • Make sure to select the Active attribute (Actions > Activate), otherwise these work flows will not execute.
  • For the Recipient Status work flow it is appropriate to leave the attribute On Complete Only "disabled". Reason being, we want this work flow to execute when an envelope status is "Sent".
  • The work flow to attach the completed document and update the Emergency Contact details is different. We only want this to execute when the envelope status is "Completed". For that, we will enable the attribute On Complete Only.
 

Modify your CSV file for bulk sending

 

Reference the section entitled, "Generate a customized CSV file for the bulk recipient list" to work on this step.

When following the steps to send a Bulk Send set of Envelopes from DocuSign's web application, part of that process will be to Use the Template, and click the "i" in a circle (stands for Information), and download a CSV Template - click "Download the sample CSV template". Doing this will present you with a CSV file that can be edited to map data from your Salesforce Report to pre-populate the fields of Envelopes you sent from DocuSign. This is also the moment to make sure that any unnecessary columns are deleted (delete a column if you're not planning on pre-populating that field with data from Salesforce, e.g.), that all the CSV cells (in Excel) are filled out appropriately and completely. 

We suggest you copy/paste large sets of data from the Salesforce Report you ran earlier to this Excel file taken from the DocuSign Template. And further, that you test the Bulk Sending itself before sending a large amount of Envelopes out in Bulk Send. 
 

Send the Bulk Send

Following the steps laid out here in this Bulk Send Guide for Multiple Recipients will walk you through how to send a Bulk Send in DocuSign's web application. The most important distinction beyond what's in that guide is modifying the CSV file for bulk sending



Following the Envelope's Status in Salesforce

Once Envelopes are sent from DocuSign, and Connect objects are configured, we expect DocuSign Connect for Salesforce to publish updates back to Salesforce as it pertains to the status of the Envelope(s), fields that need to be updated (when applicable), and the final, signed document(s) to be written back to records in Salesforce. These actions will happen based on Recipient and Envelope Trigger Events

Given all of the above is followed, the completed document(s) from your Envelopes should be published back to your Contact Records in Salesforce, custom fields in Salesforce fields should be updated after signers fill out their Gym Membership document(s) that were sent to them, and you could potentially view the status of the Envelopes in Salesforce. All Salesforce users who have access to the records in question, as well as the DocuSign Recipient Status layouts on your Contact Records can see and follow along with the progress of the Gym Membership Envelopes that need to be signed. 

Pages 60-66 here explain how to add the Related List "DocuSign Recipient Status" to your Salesforce Layouts.



Originally created by Derrick Tran, Sr. Product Consultant - DocuSign Professional Services Team.
Updated in 2019 by Matthew Case, Tier II Technical Support.