From the Trenches: Use the Apex Toolkit to send responsive HTML documents with dynamically set tabs

Geoff PfanderSenior Developer Support Engineer

•

Summary•3 min read

Step-by-step guide on how to send responsive documents from Salesforce using the Docusign Apex Toolkit

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"></ds-fullname></p>
<div><br><br>Customer Signature: <ds-signature data-ds-role="Customer"></ds-signature><div>

<p>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 <strong>ds-role</strong> 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.</p>

<code class="language-java" data-uuid="e5bSyKMZ">    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?
    }</dfsle.document></id></id></dfsle.recipient></code>

<p>To try this out, download the<a href="https://github.com/docusign/docusign-template-library/blob/master/Responsive%20HTML%20Samples/Responsive_AC_Order.html"> Responsive_AC_Order.html</a> and upload it to your contact in Salesforce. Edit the name of the contact in the <strong>SELECT</strong> statement in line 3 of this Apex code, and then you can run it in a class or in the Execute Anonymous Window.</p>

<p>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.</p>

<h2>Additional resources</h2>

<ul><li><a href="https://developers.docusign.com">Docusign Developer Center</a></li>
	<li><a href="https://twitter.com/docusignapi">@DocuSignAPI on Twitter</a></li>
	<li><a href="https://www.linkedin.com/showcase/docusign-for-developers/">Docusign for Developers on LinkedIn</a></li>
	<li><a href="https://www.youtube.com/playlist?list=PLXpRTgmbu4opxdx2IThm4pDYS8tIKEb0w">Docusign for Developers on YouTube</a></li>
	<li><a href="https://developers.docusign.com/#newsletter-signup">Docusign Developer Newsletter</a></li>
</ul></div></div>

Geoff PfanderSenior Developer Support Engineer

Beginning in the 1990s, Geoff's engineering career has followed the evolution of COM, Java and .NET on the machine and SOAP and REST in the cloud. Currently the Developer Support team's subject matter expert for the Apex Toolkit, Geoff has extensive experience as an engineer in support, test, and sales. You can find him on LinkedIn.