Sending with merge fields using the Apex Toolkit

When it comes to the Apex Toolkit, everyone wants to learn how to use merge fields. We often see questions on StackOverflow or during API Office Hours about how to create merge fields in Apex. I’m excited to announce our latest Apex Toolkit code example that should answer some of those questions: How to send an envelope with merge fields. 

If you’re not familiar with merge fields, here’s a quick introduction to the concept. Merge fields are Docusign tabs that pull their values from the data stored in a Salesforce object. If you’re sending a Docusign envelope and you want to include a tab that displays your customer’s name, you can use a merge field that will take the customer’s name directly from the corresponding Salesforce record. When the recipients open the envelope, the tabs will be prepopulated with the relevant information from Salesforce. 

But merge fields don’t only take information from Salesforce; with the writeback option, they can write data to Salesforce objects as well. Let’s say you have a tab in your Docusign envelope that contains the customer’s email address. If you want to give the customer the option to update their contact information with a new email address, you can use a merge field for the tab. The merge field will pull the email address that is stored in Salesforce and display that in the tab, but the recipient will also be able to edit the text in the tab. Once the envelope is completed, any changes to the text in the tab by the recipient will be written back to Salesforce and stored on the customer record. 

Let’s take a look at what this looks like in the Apex code. To add a merge field to an envelope, you’ll need to create a dfsle.Tab.MergeField and a corresponding tab. In this case, I’m using a dfsle.TextTab. The code snippet below demonstrates how to define the MergeField object.

dfsle.Tab.MergeField myMergeField = new dfsle.Tab.MergeField (
    'opportunity.name', //The data that this merge field will pull its value from
    null, //N/A
    null, //N/A
    true, //Allows writeback to the Salesforce object
    false //Whether or not the field is read only for the sender
);

In the code snippet above, the first parameter is set to opportunity.name to indicate that the merge field’s value will be populated by the name field of an Opportunity object in Salesforce. The parameter set to true allows writeback to the opportunity object, meaning that the opportunity record in Salesforce will be updated to reflect any changes to the text in the tab. The last parameter set to false states that the tab is not read-only for the sender of the envelope. If you wanted to use a merge field without allowing writeback, you would swap the true and false values of those two parameters.

After defining your merge field, you need to create a tab to associate with the merge field. The code snippet below demonstrates how to create a text tab that will display the value of the merge field. 

dfsle.Tab myTextTab = new dfsle.TextTab()
    .withMergeField(myMergeField) //Associate this tab with the mergeField
    .withReadOnly(false) //true = read only or locked
    .withPosition(new dfsle.Tab.Position(1, 1, 200, 300, null, null))    
    .withDataLabel('Contact Name');

The merge field that you created previously should be passed as a parameter to the dfsle.ReadWriteTab.withMergeField method on the text tab. The .withReadOnly method determines whether the tab is editable by the recipient, and the withPosition method is used to place the tab in the document at a location defined by x and y coordinates. Once you have created your tab, you can assign it to an envelope’s recipient with the dfsle.Recipient.withTabs method. You can find the code for the full example in the new code example on the Developer Center.

I hope this helps answer the commonly asked question: “How do I send an envelope with merge fields?” Our team’s #1 goal is to make sure that our content addresses your needs, and we’re always looking for the gaps where we can address developer questions through content on the Developer Center or blog posts like this one. We love to hear from developers like you, so keep the questions coming!

Additional resources

• Docusign Apex Toolkit

• Docusign Developer Center

• @DocuSignAPI on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter