From the Trenches: Use the Apex Toolkit to send responsive HTML documents with dynamically set tabs
Developer Support is seeing increased interest in our Apex Toolkit. The Apex Toolkit is a component of the DocuSign managed package DocuSign Apps Launcher and is very tightly integrated with Salesforce. Using the Apex Toolkit may require a shift of perspective for a developer accustomed to working with the DocuSign eSignature REST API or one of our SDKs based on it. A simple example is that you are probably used to thinking of the envelopeId as the GUID returned by the API when you send an envelope; but in the Apex Toolkit, the Envelope object returned from the sendEnvelope method has both a UUID type Envelope.docuSignId property, which is the GUID you are familiar with, and a global ID type Envelope.Id that is the ID of the envelope stored in Salesforce.
The most common use cases for sending envelopes with the Apex Toolkit involve the use of templates, and most of our how-to guides in the Developer Center employ that approach. Typically, developers use automatic anchor text and tabs to set tabs in templates, providing flexibility at runtime. Developers who are looking for a more dynamic way to place tabs have contacted Developer Support asking for methods and properties for placing tabs on an envelope. The Apex Toolkit does not include those features yet, but don't despair. You can take advantage of our responsive HTML feature to place tabs dynamically inline in the HTML document. These tabs can be placed as inline JSON or inline HTML. Using responsive HTML documents means you don’t need to have a previously prepared template to use in your API call. Your customers can sign on their mobile devices, and the responsive HTML documents will be automatically formatted to look great on the mobile devices’ smaller screens.
If you have not been using responsive documents in your API calls, you will need to contact DocuSign Customer Support and ask that “Enable Smart Sections/API for Responsive Signing” be turned on in your developer account. Then you can add inline tabs in the HTML of your document. In the below HTML example, I have added an email tab that will automatically fill in the email of the signer, a name tab that fills in the name, and the signature tab for this signer.
Customer Email: <input data-ds-type="email" data-ds-role="Customer" />
<p>Customer Name: <ds-fullname data-ds-role="Customer" /></p>
<div><br><br>Customer Signature: <ds-signature data-ds-role="Customer" /><div>
Using the Apex Toolkit, I can set the role name of my recipient dynamically. This is a nice differentiator from using the DocuSign eSignature for Salesforce defaults of Signer 1, Signer 2, and so on. I match the ds-role in the HTML tabs to the role name parameter when I define the recipient in my Apex Toolkit code. Notice also that I do not need to do anything special to define the document as responsive HTML. The Apex Toolkit handles that for me. In this code example I am sending all files attached to my contact. In my test there is only one file, Responsive_AC_Order.html, attached to my contact, but it would work with multiple files.
public static void SendDocsAttachedToContact(){
//Find your contact to add
Contact myContact = [SELECT Id, Name, Email FROM Contact WHERE Name = 'Black Beard' LIMIT 1];
// Create an empty envelope with Contact Id as the source Id
dfsle.Envelope myEnvelope = dfsle.EnvelopeService.getEmptyEnvelope(new dfsle.Entity(myContact.Id));
//use the Recipient.fromSource method to create the recipient
dfsle.Recipient myRecipient = dfsle.Recipient.fromSource(
myContact.Name, // Recipient name
myContact.Email, // Recipient email
null, //Optional phone number
'Customer', //Role name. Specify the exact role name to match the data-ds-role attribute on inline HTML tabs
new dfsle.Entity(myContact.Id)); // Using Contact as source entity
//add the recipient to the envelope
myEnvelope = myEnvelope.withRecipients(new List<dfsle.Recipient> { myRecipient });
//Setup a list of Ids to search. We just need the one myContact.Id
Set<Id> ids = new Set<Id>();
ids.add(myContact.Id);
//Find all the documents attached to the Contact
//Responsive_AC_Order.html needs to be attached to the Contact object
List<dfsle.Document> docs = dfsle.DocumentService.getLinkedDocuments(
ContentVersion.getSObjectType(), ids,
false);
//add documents to the envelope
myEnvelope = myEnvelope.withDocuments(docs);
// Send the envelope.
myEnvelope = dfsle.EnvelopeService.sendEnvelope(
myEnvelope, // The envelope to send
true); // Send now or save as draft?
}
To try this out, download the Responsive_AC_Order.html and upload it to your contact in Salesforce. Edit the name of the contact in the SELECT statement in line 3 of this Apex code, and then you can run it in a class or in the Execute Anonymous Window.
So give the Apex Toolkit and responsive HTML documents a try. You will find you have more control at runtime for placing tabs and you can give your customers a better user experience on their mobile devices.
