**Legacy** DocuSign eSignature for Salesforce - Best practices for Using Merge Field writeback feature versus Connect

**This article pertains to Legacy DocuSign eSignature for Salesforce.**


If information needs to be pulled from Salesforce into a DocuSign envelope, you can either utilize DocuSign Merge fields or DocuSign Connect to push data from Salesforce into an envelope (or vice versa).

Merge fields can be used to pull information from Salesforce fields directly. Writeback can be used to push information back to Salesforce fields. You can also set up a custom Connect object to push and pull data between an envelope and a Salesforce record. 

The following article will outline the best practices for Merge Field and Connect and explain the differences between both options.

Merge Field Best Practices

The easiest way to pull Salesforce data into an envelope is using a DocuSign Merge field. This allows you to map a DocuSign fields directly to a Salesforce fields. 

When creating a DocuSign field, if your DocuSign account has the proper settings, you will see a Relate to Salesforce option. Selecting this field will allow you to map the DocuSign field to a Salesforce field.

Merge Field Mapping

To map a DocuSign field to a Salesforce field, you will have up to 4 drop down options to navigate to the field. This means that from the object you are sending from, you can drill down 4 levels from that object (through related lists or connected records). 

The best practice for mapping a field is to start with the object you are sending from. For example, let's say that you are sending from an opportunity and you want to opportunity name to appear in a DocuSign envelope. In the first dropdown, you will select the object. Then, dynamic options will appear in the second drop down, based on what's available on that object. The image below depicts how you should set up mapping to populate the Opportunity name when sending from an Opportunity:
Let's say that you'd like something more complex. For example, you're sending an envelope from an Account but you'd like to have an opportunity's Close Date appear on the envelope.

To map from the Account to information on the Opportunity, start with Account in the first drop down. In the second drop down, you'll need to reference that the information you want doesn't live on the account, but on an Opportunity. Select Opportunity (child_relationship) in the second drop down. Child relationship referenced that this is a related list on the Account record. Lastly, select the information you'd like to populate from the Opportunity: Close Date.

For more information on what the values in the parenthesis mean, reference this Salesforce guide .

Merge Field Writeback

Below merge field mapping, you will then see two additional options relating to merge fields:
  • Allow Writeback to Salesforce:  Select this check box to automatically update the Salesforce data when the data is changed by a signer.
  • Allow sender to edit custom fields: Select this check box to let senders modify the value of the custom tag when the tag is added to a document during the sending process.

Allow writeback is essential to ensuring data can write back to Salesforce. When investigating writeback issues, if writeback is failing for all users, ensure the merge field has writeback enabled before troubleshooting Connect issues.

Connect Writeback

As mentioned previously, data can be pushed from DocuSign to Salesforce using Connect. This option should typically be used when an Envelope is created outside of Salesforce (such as when a PowerForm is used) and data needs to be sent to Salesforce when the envelope is completed. We typically do not recommend using this option if you're sending from Salesforce and can utilize Merge fields. Using Connect to push data back requires manual setup and will require many more steps to ensure data writes back successfully. This option should be reserved for complex, multi object writeback or writing back data from envelopes that originate outside of Salesforce.  For more information, review the article push data back to a specific Salesforce record
With a customized DocuSign Connect for Salesforce configuration, individual Salesforce records can be updated upon Envelope Status changes when using Bulk Send. This is explored in greater depth: how to initiate a Bulk Send and update Salesforce records .

For more information on how Connect works with Salesforce, refer to this guide: DocuSign Connect for Salesforce