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.
The objective of this article is to demonstrate how you can integrate DocuSign's bulk sending feature and Salesforce.
OverviewDocuSign’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:
- How do I merge data from Salesforce into a DocuSign envelope?
- How do I publish updates from the bulk send envelopes into Salesforce?
- How do I relate the DocuSign Envelopes' Statuses to Salesforce records?
- How do I attach the completed document to the Salesforce records?
- DocuSign for Salesforce is installed, configured, and working properly.
- Salesforce Reporting
- Have the Bulk Send Permissions and Feature enabled and available in your DocuSign Account and on your User. (Consult your DocuSign Account Team if you need this feature as DocuSign Support cannot enable this as it's an Advanced Feature, possibly paid.)
- Creating a Template
- Generate a customized CSV file for the bulk recipient list (Read the section entitled "To generate a customized bulk recipient CSV file")
- Change DocuSign Connect for Salesforce Settings (Read the section entitled "Change DocuSign Connect for Salesforce Settings")
Task List Overview / Table of Contents
- Create a Custom Salesforce Report
- Create DocuSign Template
- Create DocuSign Custom Connect Workflows
- Update Recipient Status
- Update Salesforce Record (field values)
- Attach Completed Document
- Modify your CSV file for bulk sending
- Send the Bulk Send
- Following the Envelope's Status in Salesforce
- Addendum: Bulk Send with Envelope Custom Field Mapping
Example Use CaseI 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:
- Send the new waiver form to all active memberships.
- 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.)
- Pre-populate the name of the membership owner from Salesforce.
- Pre-populate the emergency contact information from Salesforce.
- Allow the member to update emergency contact.
- Updates of the emergency contact should publish into their Contact record in Salesforce.
- Ability to track DocuSign Envelope recipient status on the Contact record.
- Signed version of the waiver form should publish to Notes and Attachments/Files of their Contact record in Salesforce when the Envelopes are completed.
OverviewIn 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:
I need to also gather the Gym Members' Names and Email Addresses. I've added the following columns to my report:
- Email Address
- Membership Number
- Emergency Contact
- Emergency Phone
- Contact ID (or "Record ID" as applicable to your scenario)
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:
In Salesforce Lightning this could look like this:
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.
OverviewNext, 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.
- Set a Template name.
- 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.
- Add a Recipient Role like "Member" in my example. Leave the name and email fields blank.
- Set the Subject line to something appropriate; for my example it's "Please DocuSign: Waiver an Assumption of Risk Document".
- 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.
- Optional: Enter a Message to all Recipients.
- 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.
- Click NEXT.
- Add any Initial fields, Signature fields, or Date Signed fields, as needed.
- 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".
Template's Text Field's Data Label property, labeled appropriately to match:
- 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):
- Ensure Contact ID is set for the Data Label.
- Check the checkbox next to Read Only. (This will ensure that your recipients cannot change the value of this field.)
- 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.)
- 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.
- Save your Template by clicking SAVE AND CLOSE.
OverviewDocuSign 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
OverviewDocuSign 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.
StepsLog into DocuSign and navigate through the following as an Administrator:
- Go to Admin from the top, right corner menu.
- Optional: Select the correct Account, if you have multiple. Click on Accounts tile if you are an Organizational Administrator.
- Click on Connect on the left side bar.
- Click on the Salesforce Configuration. (Note: if this is not present, we recommend you install and configure DocuSign for Salesforce.)
- Select the "New Object" button and click Salesforce Object to build a new Custom Connect Object.
This will launch the "Object Edit" view
- Update the Object Name, and Description (Not required). I've named mine "Bulk Send Recipient Status".
- Select DocuSign Recipient Status from the Select Salesforce Object dropdown. (Note: that choice may be near the bottom of the picklist.)
- Optional: We will keep Add if no match unchecked so we can update only existing records in Salesforce (Our Gym Member's Record pages).
- Select Inactive Object at the top of the page and choose Activate Object.
- 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.
- 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.
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.
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)
OverviewThe 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.
- Create custom Connect object
- Update the Object Name. Update Description (Not required)
- Select Salesforce.com Object is always the object you will be updating, in this use case it is Contact
- This use case is designed to update existing Contact records, so we will keep "Add if no match" disabled / unchecked.
- Set Select Where
- Salesforce.com Field set to Contact ID
- DocuSign Field set to Recipient SecureField
- Update Fields
- Salesforce.com Field - Set to Emergency Contact (string)
- 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".
Attach Completed Document
OverviewBy 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.
- Open the same Connect object you created in the previous section,
- Scroll to the very bottom of the configuration that is labeled Attachments,
- Select the attribute for "Attach DocuSign Documents"
- Select the sub attribute for "Completed envelope only"
Now your objects list in Connect should look similar to the below:
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.
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.
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.
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:
- Create a Custom Salesforce Report - This step would remain the same.
- Create DocuSign Template - This step would remain the same, except you'd add an Envelope Custom Field to your DocuSign Template.
- 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.
- Update Recipient Status - see below section entitled, "DocuSign Custom Connect Workflows for Envelope Custom Field Mapping"
- Update Salesforce Record (field values) - This would be the same.
- Attach Completed Document - This would be the same.
- 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.
- 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.
- 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.
Originally created by Derrick Tran, Sr. Product Consultant - DocuSign Professional Services Team.
Updated in 2019 by Matthew Case, Tier II Technical Support.