**Legacy** DocuSign eSignature for Salesforce - 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 visit our Contact Support Page and create a case to schedule time with our Professional Services team.


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


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.


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
  7. Addendum: Bulk Send with Envelope Custom Field Mapping

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


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


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 "Advanced Options" from the options on the top-right, 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". 


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


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


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

DocuSign Recipient Status is a default Connect object and workflow. When creating Envelopes from a Contact record with DocuSign eSignature 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. 
Log into DocuSign and navigate through the following as an Administrator:
  1. Have a DocuSign Administrator click the Settings tab from top banner across the main DocuSign page:Home - Settings.png
  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 eSignature 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 Contact 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)

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

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


Addendum: Bulk Send with Envelope Custom Field Mapping

This Addendum was added after the above walkthrough was published. While the above would work, there is now a more efficient way of mapping Envelopes to Salesforce by way of using an Envelope Custom Field in the Bulk Send process. Doing so, replaces the need for a Document-level Custom Field to be on the document(s) sent, and allows for a "behind the scenes" approach to map Envelopes to Salesforce that is just as effective (but not more so), than the above method of using Document-Level Custom Fields

Keep in mind, before attempting this approach, that there are limitations to Envelope Custom Fields. Until further product enhancements are created, for example, Envelope Custom Fields, once enabled on a DocuSign Account, will be required for all Envelopes sent from that Account thereafter. Envelope Custom Fields (at the time this is written) also have limitations such as:  they can't be created when sending from Salesforce with DfS, and they can't be added to Envelopes when sending from the DocuSign mobile app for iOS. (They can be added in the web application.) 

By Contrast, there are benefits of using Envelope Custom Fields on Envelopes you send, such as an added way to filter for Envelopes under the Manage Tab in the DocuSign Web Application. (See Reports and envelope custom fields here.)

How this solution would look: 
  1. Create a Custom Salesforce Report - This step would remain the same.
  2. Create DocuSign Template - This step would remain the same, except you'd add an Envelope Custom Field to your DocuSign Template. 
  3. Create DocuSign Custom Connect Workflows - This step remains the same, except you'd be using Envelope Custom Fields to map Envelopes back to Salesforce, instead of Document level Custom Fields. 
    1. Update Recipient Status - see below section entitled, "DocuSign Custom Connect Workflows for Envelope Custom Field Mapping"
    2. Update Salesforce Record (field values) - This would be the same. 
    3. Attach Completed Document - This would be the same. 
  4. Modify your CSV file for bulk sending - This section would be similar, but you'd add a column to map the Envelope level custom fields to your Connect objects in point 3. See point #5 in this article. In short, the Envelope Custom Fields are headers in the CSV file that have no role name (like Employee:Name, e.g.), but instead are simply listed as their own column, such as "EmployeeID" for an Envelope level Custom Field that maps to "EmployeeID" in your Template. 
  5. Send the Bulk Send - This step would be the same, except that you would fill in the Envelope Custom Field(s) in addition to the other steps you follow. 
  6. Following the Envelope's Status in Salesforce - This would remain the same. 

DocuSign Custom Connect Workflows for Envelope Custom Field Mapping
One of the important differences when it comes to this solution, when compared to the above article, is how DocuSign Connect must be configured to map the Envelope(s) you send through your Bulk Send to accomplish the mapping of Envelopes based on the Envelope Custom Field, instead of the Document Custom Field. 

You can follow the section Create Custom Connect Workflows and be sure to change point #10 as follows: 

When creating the "Select Where" section of your Custom Connect Object for a Contact, for example, set: 
  • Salesforce.com Field set to Contact ID (id)
  • DocuSign Field set to EnvelopeCustomField:[NAMEOFYOURENVELOPECUSTOMFIELDHERE].  This Field name will match what was set on the DocuSign Template's Text Field Data Label. An example of this could be "EnvelopeCustomField:EmployeeID" to match the example in this guide.
The other steps in the Custom Connect Workflows will remain the same. 


Originally created by Derrick Tran, Sr. Product Consultant - DocuSign Professional Services Team.

Updated for the New DocuSign Experience, and additional technical writing by Matthew Case, Software Consultant - DocuSign Adoption Team.