Working with Templates using the Apex Toolkit

The Docusign Apex Toolkit provides predefined Apex methods, classes, and utilities, acting as an SDK. It encapsulates certain Docusign eSignature API functions, enabling developers to integrate Docusign and Salesforce features directly within their Apex code.

While standard Docusign workflows use the Docusign eSignature for Salesforce UI, the Apex Toolkit grants access to Docusign eSignature API functionality. This access allows for greater customization and automation of workflows and processes. 

Templates are pre-defined, reusable document packages that streamline the process of sending documents for signature. They allow you to set up documents, recipient roles, merge fields, signing fields, and workflow settings in advance, so you don't have to configure them from scratch each time.

This works great when you send an envelope from a template using the “Send with Docusign” button. However, there are a few caveats when sending a template using the Apex Toolkit as some settings defined on the template don’t flow through when you send it using the Apex Toolkit. I’ll explore some of the common options that get missed as well as what you can do to modify your code to include them. 

Reminders and Expiration settings

Much like the eSignature REST API, any templates created using the Apex Toolkit will not inherit the reminder settings defined on the template or the ones defined on your account. Instead, it will revert to the system default of expiration after 120 days with no reminders. So when you create an envelope from a template, you will need to explicitly define the reminder and expiration settings. Here’s a code example:

   // Code to create the envelope
        myEnvelope = myEnvelope.withNotifications(new dfsle.Notifications(true, 1, 1, true, 10, 5, false));
        /*
			What do these parameters mean? 
			new dfsle.Notifications(
			true,   // Whether or not to remind recipients to sign.
			1,      // How many days to wait before sending a reminder.
			1,      // How many days between sending reminders.
			true,   // Whether or not the envelope automatically expires (is voided).
			10,     // How many days before the envelope expires.
			5,      // How many days prior to expiration to send a warning to recipients.
			false   // This is a deprecated parameter. You can specify any boolean value. 
			)
		*/
        // Code to send the envelope

Merge Fields

You can declare merge fields directly on the template but you will need to explicitly define their values when you create an envelope from a template. Here’s how:

 // Create an empty envelope
        dfsle.Envelope myEnvelope = dfsle.EnvelopeService.getEmptyEnvelope(
            new dfsle.Entity('mysourceId'));
        // The initiating Salesforce entity. Can be any Salesforce object of your choosing

        dfsle.Tab.MergeField myMergeField = new dfsle.Tab.MergeField (
            'opportunity.name', //The data that this merge field will pull its value from. In my case, the initiating entity is an Opportunity
            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
        );

        		dfsle.Tab myTextTab = new dfsle.TextTab()
 .withMergeField(myMergeField) //Associate this tab with the mergeField
    		.withDataLabel('Opportunity Name'); // This Data Label should match the Data Label of the merge field defined on the template

        // Code to add the tab to a recipient and send the envelope

Envelope Writeback options

Docusign Apps Launcher allows you to define writeback options on the template directly. But if you use the Apex Toolkit to send an envelope with a template with writeback options declared, you will have to explicitly re-declare them to have them flow through. You can find more information on writeback options and how to use them in this blog post. I’ll include a basic example here. You can declare them with the withOptions method. 

More information on what parameters it takes and what they mean are available here.

myEnvelope.withOptions(new dfsle.Envelope.Options(
            // Whether to populate auto-place tags for default roles
            false,
            new dfsle.Document.WriteBack(
                // Where to link the completed document(s)
                mySourceId,
                // The completed document(s) file name format
                dfsle.Document.WRITE_BACK_ENVELOPE_STATUS_PDF,
                // Whether to combine all the documents into a single PDF
                true,
                // Whether to include the Certificate of Completion (CoC)
                true),
            // Envelope status event updates
            new Map<String, Map<String, Object>> {
                // Set Opportunity.StageName to "Closed Won" upon completion
                dfsle.Envelope.STATUS_COMPLETED => new Map<String, Object> {
                    'Opportunity.StageName' => 'Closed Won'
                        }
            },
            // Recipient status event updates
            new Map<String, Map<String, Object>>()));

The email subject and email body

You can use the withEmail method available in the Envelopes class to define a custom email subject and email body for your envelope. Note that this does not have to match the one already defined on the template, it can be anything that you need. 

myEnvelope = myEnvelope.withEmail('Test Email Subject', 'Test Email Message');

This way you can ensure that your envelopes carry through all the customization options that you have defined on your templates.