How to initiate a Bulk Send and update Salesforce records

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



There are many use cases where you can take advantage of DocuSign's "Bulk Sending" capabilities. The purpose of a bulk send is to send the same document to a large number of recipients. Some of the challenges that 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 Status to Salesforce records?
  4. How do I attach the completed document to the Salesforce records?
These challenges are important to address in order to maintain a complete solution that is provided by our standard DocuSign for Salesforce managed package. Without a customized configuration, the individual Salesforce records that are related to the recipients of the bulk send cannot be updated.


The objective of this article is to show how you can leverage DocuSign and CRM to address all the challenges referenced above.


Salesforce Reporting
Creating a Template
Building a Bulk Recipient File
Change DocuSign Connect for Salesforce Settings

Task List

  1. Create Custom Salesforce Report
  2. Create Bulk Recipient Template
  3. Create Custom Connect Work Flows
    1. Update Recipient Status
    2. Update Salesforce Record (field values)
    3. Attach Completed Document

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 asked of my solution team:
  1. Send the new waiver form to all active memberships
  2. Pre-populate the membership number in the form from Salesforce
  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 to publish into their Contact record in Salesforce
  7. Ability to track recipient status on the Contact record
  8. Signed version of the waiver form to publish to Notes and Attachments of their Contact record

Create a Custom Salesforce Report


In order send an envelope in bulk, we 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.


Navigate to the "+" symbol to get a full list of all objects.
Select Reports.
Select New Report
One of the requirements was to send all "Active" members the new waiver form.
When creating my custom report, I started with Accounts and Contacts.
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".

User-added image

Full configuration of my filter below:

User-added image

The required fields for a DocuSign bulk recipient file are "Name" and "Email". I knew I could place these same columns in my Salesforce report, but part of my requirements was to merge in additional membership details from Salesforce as well. For that reason, I've added the following columns to my report:
  1. Membership Number
  2. Emergency Contact
  3. Emergency Phone
  4. Relationship
  5. Contact ID
User-added image

Notice the last column I added "Contact ID". More details on this later when you Create Bulk Recipient Template and Create Custom Connect Work Flows.

Clicking on "Run Report" provides me with a full list of records that meets my filter criteria, in addition to the field values that I will use to populate my document.

From here I can click the button "Export Details". Within the Export File Format, "Comma Delimited .csv" is an option.

User-added image

Select "Export" button to download the .csv file.

Open your .csv file after saving. Salesforce will add additional copyrights and meta data on who generated the report. If these rows are not deleted, an error will be displayed when uploading the file into DocuSign.

User-added image

Re-Save your .csv file after deleting the excel rows.

You have now successfully created a bulk recipient file from a Salesforce report!! The image below is a preview after uploading your bulk recipient file when preparing an envelope (Import Bulk List).

User-added image

Create Bulk Recipient Template


Now that you have created your bulk recipient file, you can create a bulk recipient template. Within your template, you will use the exact same label names from your .csv columns to create your DocuSign Data Fields in the template. This will allow the data from the csv to push into the DocuSign envelope.


CSV Column:
User-added image

Template Data Field Label:
User-added image


In your template, make sure to include a data field that will be reserved for populating the record ID from Salesforce. The DocuSign for Salesforce managed package does this out of the box, but since we are creating the envelope outside of Salesforce, we need a location to push the data ourselves. Connect will need to reference the record ID for the post processing side that will also be explained later in this article.
  1. Label name of the data field should match your .csv file
  2. Formatting Properties should have "Locked" selected
    1. This will ensure that your recipients cannot change the value of this field and will be read only
  3. Under Formatting Properties, change the font color to " White"
    1. Since my document is also white and the field is locked, this will hide the field from the recipient
  4. Locate the field in an area of the template where there is no text. I placed mine in the upper right hand corner of my document
User-added image


Create Custom Connect Work Flows


DocuSign Connect for Salesforce controls all updates back into your Salesforce organization. Without this feature, no statuses, documents and/or field data can update in Salesforce.

Update Recipient Status

DocuSign Recipient Status is a default Connect work flow. When creating envelopes from a Contact record with DocuSign for Salesforce, the Recipient Status is automatically created and related back to the Contact record. Now that we are sending from the DocuSign web application, we need to create a custom work flow in order to relate the status to the appropriate Contact record in Salesforce. Without this step, Recipient Statuses would be created in Salesforce, but they would not relate to any Contacts from the bulk list.
Log into DocuSign and navigate to:
  1. Go to Admin
  2. Connect
  3. Salesforce
  4. Select the "New Object" button and click Salesforce Object
User-added image

This will launch the "Object Edit" view

User-added image
  • Update the Object Name and Description (Not required)
  • Select Object is always the object you will be updating, in this use case it is DocuSign Recipient Status
  • The Recipient Status is already created from a default work flow, we will keep Add if no match disabled so we can update an existing record only
  • Set Select Where
    1. Field set to DocuSign Recipient Id (string)
    2. DocuSign Field set to Recipient ID
User-added image
  • Update Fields
    1. Field set to Contact (reference)
    2. DocuSign Field set to Recipient Secure Field (aka DocuSign field or tag)
    3. With Recipient Secure Field selected, an additional field will be available to populate which represents the "Label" name of the DocuSign field. In my use case, this is Contact ID
      User-added image
  • Ignore the Attachments and keep these defaulted to disabled

Full configuration example below:

User-added image

DocuSign Connect for Salesforce has the capability of running multiple work flows. It also has the capability of organizing an order of operation on when to run the work flows.

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 work flows (objects) is to update or create new Salesforce records based off DocuSign meta data 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 and Description (Not required)
  3. Select 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 .
  5. Set Select Where
    1. Field set to Contact ID
    2. DocuSign Field set to DocuSign SecureField
and when the new blank field appears to the right, the label name will match record id field referenced in the CSV output from Salesforce and DocuSign field within the template which would be 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
  • Update Fields
    1. Field set to Contact (reference)
    2. DocuSign Field set to Recipient Secure Field (aka DocuSign field or tag)
    3. With Recipient Secure Field selected, an additional field will be available to populate which represents the "Label" name 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 related list of the appropriate Contact.
  1. Open the same Connect object you created in the previous section
  2. Scroll to the very end 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

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