Apex Toolkit: Using the BulkSendService
If you are a Salesforce developer looking to integrate DocuSign into your Salesforce workflows and processes, the Apex Toolkit is your new best friend. Similar to an SDK, the Apex Toolkit exposes a full set of programmatic objects and methods that you call from your Apex code to access the DocuSign eSignature REST API.
To use the Apex Toolkit, you'll need to set up a few things first:
- Create a Salesforce org; a Salesforce developer account will work.
- Enable My Domain in your developer org.
- Open a free DocuSign developer demo account..
- Install the DocuSign Apps Launcher from the Salesforce AppExchange.
Now that you’re all set up, I’ll be showing you how to use the BulkSendService class to send an envelope to each member of a Salesforce Chatter group. BulkSendService enables you to send envelopes in bulk to multiple recipients. This is useful for scenarios where you want to send the same document to a list of people; for example, to send a waiver to the participants of a workshop.
If you’re not up for reading and you’d rather see the code in action, check out Lauren Dunne’s video walking you through the same example:
https://www.youtube.com/watch?v=BlQ1fxXp_oc&feature=youtu.be
First, write a method that creates a list of recipients, assigning each of them to an empty envelope. To build the list of recipients, you’ll be using the membership of a Chatter group in your Salesforce org. Start by assigning the variable myGroupId to the ID of the Chatter group that you want to use. Then, use a for loop to iterate through each contact within the group and create a copy of an empty envelope for each of them. Inside the loop, use the Recipient.newBulkRecipient method to create a new Recipient object for each contact, passing in the contact's name, email, and Salesforce Entity Object reference ID. Use the Envelope.newBulkCopy method to create an empty envelope for each recipient, adding all of the envelopes to the list myBulkCopies. After you have an envelope for each contact in the Chatter group, pass the myBulkCopies list to the dfsle.BulkSendService.createLists method. The list of envelopes is now created and a reference to the list's ID is stored in the myListId variable.
public static Id buildList(){
Id myGroupId = xxxxxxxxxxxxxxxxx; // A Chatter group ID
// Build 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, // Name
m.Member.Email, // Email
new dfsle.Entity(m.Member.Id)))); // Source Salesforce object
}
// Create the bulk list. This list persists after sending and may be reused for multiple 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;
}
Once you have created your list of recipients and empty envelopes, you’re ready to attach a document to the envelopes and send them. You can use a document that you have already uploaded to a Salesforce library by assigning the ContentDocumentId of that document to the variable myDocumentId. The getDocuments method takes a ContentVersionId parameter, so you need to use a Salesforce Object Query Language (SOQL) query to get the ContentVersion that corresponds to the ContentDocumentId of your document, assigning that to myFileId. Attach that document to a new draft envelope using the dfsle.BulkSendService.getDraftEnvelope method, then send the envelope using the dfsle.BulkSendService.sendEnvelope method.
You might have noticed the @future annotation at the beginning of the method defined below and wondered what its purpose was. Apex has a known limitation where it does not allow you to update a record with a Data Manipulation Language (DML) statement within the same transaction as a Web Service Callout. Our first method includes a DML insert that requires the code in that method to be executed separately from the callout in the second method. The @future annotation ensures that the call to the DocuSign eSignature API is made asynchronously to prevent any conflict with the DML insert. Working with the Apex Toolkit will require that you become very familiar with the @future annotation, because every call to the eSignature API is handled by Apex as a Web Service Callout.
@future(callout=true)
public static void sendBulk(Id myListId){
Id myDocumentId = xxxxxxxxxxxxxxx; //The id of a document stored in a Salesforce library
Id myFileId = [SELECT id from ContentVersion where ContentDocumentId = MyDocumentId LIMIT 1].id; // Content version ID of document to send
// Create the draft bulk envelope. This will have exactly one placeholder bulk recipient
dfsle.Envelope myEnvelope = dfsle.BulkSendService.getDraftEnvelope(
dfsle.DocumentService.getDocuments(ContentVersion.getSObjectType(), new Set<Id> { myFileId }), // Documents to send
null); // Optional Salesforce source entity
// Send envelope with a placeholder bulk recipient
dfsle.BulkList.Result myResult = dfsle.BulkSendService.sendEnvelope(myListId, myEnvelope);
}
Together, the two methods defined above give you everything you need to bulk-send envelopes. The second method, sendBulk, takes one parameter, myListId. You can pass the value returned by the first method, buildList, to the second method, as demonstrated below.
Id myListId = BulkSendingClass.buildList();
BulkSendingClass.sendBulk(myListId);
To execute your code, open the Developer Console in Salesforce and select Debug > Open Execute Anonymous Window. Type the two lines from above and select Execute.
And you’re all done! Each member of your Chatter group should see an email containing the envelope in their inbox.
f9db.png)