How to bulk send envelopes

This topic demonstrates how to send envelopes in bulk to multiple recipients using the Apex Toolkit. Using the dfsle.BulkSendService class, this code demonstrates how to create and bulk send envelopes to each member of a Salesforce Chatter group.

Note: To learn about bulk sending with the eSignature REST API, see our guide and how-to.

The underlying Apex code shown in this example can be used in Lightning applications or components, Visualforce pages, Communities, and any other component that invokes Apex code in Salesforce.

Prerequisites

1. Install the Docusign eSignature for Salesforce managed package.

2. Create a subdomain for your Salesforce organization by enabling “My Domain.”

3. Select the Docusign Setup tab and complete the login step.

4. Create a Chatter group containing the contacts that you want to send your documents to.

5. Create a template in your Salesforce org with a role of ‘SignerOne’:

   1. Open the Docusign Apps Launcher and go to the Docusign Envelope Templates tab.
   2. Choose New to create a new template.
   3. Give your template a name and choose a data source.
   4. Add a recipient to the template. Choose By Role under Other Sources and give the recipient a role of “SignerOne.”
   5. Follow the steps to set the template options and add tabs or merge fields. Then Save and Close the template.

Required data

Running the code in this how-to requires this data:

Step 1. Define your class and methods

Create the class and methods that will contain the code in this example. You can skip this step if you are adding this code to an existing class.

Note: The steps outlined in this example need to be defined in separate methods because Apex does not allow you to update a record with a Data Manipulation Language statement within the same transaction as a Web Service Callout.

Step 2 of this example includes a DML insert that requires the code in that step to be executed separately from the callout in Step 3.

public with sharing class BulkSendingClass{
}

Step 2. Create contact list for bulk sending

Create the bulk send list with the contact information for each recipient. This list may be based on any group construct and contains copies of the envelope to be sent. A recipient note, authentication options, and email subject and message may be set for each copy, but each copy must have exactly one recipient.

The accompanying code demonstrates how to create a new envelope definition for each member of the specified Chatter group and how to create a contact list which will be used for bulk sending those envelopes. This example uses a Chatter group to generate the bulk copies, but you can take contact information from any data source to create the recipients with the dfsle.Recipient.newBulkRecipient method. Be sure to add the 'SignerOne' role to the recipients using the withRole method to match the role in your template.

Be sure to replace the value for myGroupId with your own Chatter group ID. To find your Chatter group ID, go to the Docusign Apps Launcher, search for Groups, and select your Chatter group. Copy the ID from the URL of your Chatter group page.

Note: Each created bulk list persists both in Salesforce and Docusign and may be reused to send multiple envelopes. The list definition can be updated when the underlying group membership changes with dfsle.BulkSendService.updateLists, or it may be removed with dfsle.BulkSendService.deleteLists when no longer relevant.

@AuraEnabled
public static Id buildList(){
    Id myGroupId = '0FXXXXXXXXXXXXXXAC'; // Substitute this value with your Chatter group ID
    // Build a list membership from a Chatter group
    // Recipient authentication, email settings, or private notes may be overridden using the Recipient.with* methods
    // Envelope email settings and notifications may also be overridden per copy using the Envelope.with* methods
    List<dfsle.Envelope> myBulkCopies = new List<dfsle.Envelope>();
    for (CollaborationGroupMember m : [
        SELECT Member.Id, Member.Name, Member.Email
        FROM CollaborationGroupMember
        WHERE CollaborationGroupId = :myGroupId
    ]) {
        myBulkCopies.add(dfsle.Envelope.newBulkCopy(
dfsle.Recipient.newBulkRecipient(
	m.Member.Name,
	m.Member.Email,
	new dfsle.Entity(m.Member.Id) // Source Salesforce object
    		)
    	.withRole('SignerOne')
  ));
        }
    // Create the bulk list. This list persists after sending and may be reused for multiple batches of envelopes
    dfsle.BulkList myList = dfsle.BulkSendService.createLists(new List<dfsle.BulkList> {
        dfsle.BulkList.newList(
            'My bulk list', // List name
            myBulkCopies, // Envelope copies
            new dfsle.Entity(myGroupId)) // The Salesforce source object
    })[0];
    // Save the ID for later operations
    Id myListId = myList.id;
    System.debug(LoggingLevel.INFO, myListId);
    return myListId;
}

Step 3. Create and send the bulk envelope

Once a list has been created, create an envelope with the document(s) you wish to send. You can use a Docusign template as the document or use a document that leverages Auto-place (anchor tagging) to add a recipient’s information automatically to generic tags within a document.

Be sure to replace the value for myTemplateId with the ID of a template in your Salesforce org. To find the template ID, go to the Docusign Apps Launcher and choose the Docusign Envelope Templates tab. Select the template you want to use and copy the Docusign template ID GUID under the Details tab.

Next, use the dfsle.BulkSendService.sendEnvelope method to bulk send the envelope to each member in the list you created previously, as demonstrated in the accompanying code. These steps need to be done within an @future method to prevent the code from failing due to Apex’s DML and callout limitations.

@future(callout=true)
/**
*  bulkSendEnvelopes method
*    Use myListId from buildList method
*    Assign myStatusId to the result of the BulkSendService call
*/
public static void bulkSendEnvelopes(Id myListId){
 dfsle.UUID myTemplateId = dfsle.UUID.parse('3d9fac4b-xxxx-xxxx-xxxx-6cd70d70f8ed'); // Substitute with your template ID
 dfsle.Document myDocument = dfsle.Document.fromTemplate(
	    myTemplateId, // templateId in dfsle.UUID format
	    'myTemplate'); // name of the template
 // Create the draft bulk envelope. This will have exactly one placeholder bulk recipient
 dfsle.Envelope myEnvelope = dfsle.BulkSendService.getDraftEnvelope(
 new List<dfsle.Document> { myDocument },	null); // Optional Salesforce source entity
 // Send envelope with a placeholder bulk recipient
 dfsle.BulkList.Result myResult = dfsle.BulkSendService.sendEnvelope(myListId, myEnvelope);
}

Step 4. Request bulk status

Once the bulk send job has been queued successfully, you can periodically check the status of the job using dfsle.BulkSendService.getStatus method.

// Retrieve status from the API
dfsle.BulkList.Status myStatus = dfsle.BulkSendService.getStatus(new Set<Id> { myStatusId })[0];
// Do something with the returned status
if (myStatus.queuedEnvelopes > 0) {
    // Still processing...
} else if (myStatus.failedEnvelopes > 0) {
    // One or more envelope copies failed to send
    for (dfsle.BulkList.StatusDetail sd : myStatus.details) {
        // Handle send failures
    }
}

Step 5. Execute your methods

To execute your code, go to the Developer Console in Salesforce, open the Debug menu, then select Open Execute Anonymous Window. Type the accompanying code in the window and select Execute.

Id myListId = BulkSendingClass.buildList();
BulkSendingClass.bulkSendEnvelopes(myListId);

Expected response

Each member of the Chatter group will receive an email asking them to sign the document in your template.

Next steps

• See all available Apex Toolkit How-to guides.
• See How to perform unit testing to ensure that you have adequate code coverage.