How to send an envelope

This topic demonstrates how to create and send envelopes using the Apex Toolkit. It uses a template that you can use as a baseline for developing more complex Salesforce customizations that dynamically create and send Docusign envelopes.

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.

Video walkthrough

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. Define the template for the envelope that you want to send in the Docusign Apps Launcher.

Required data

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

Step 1. Define your class and method

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

public class SendEnvelope {
    public static void sendEnvelopeMethod(){
    }
}

Step 2. Create the envelope definition from a template

Use the dfsle.EnvelopeService.getEmptyEnvelope method to create an empty envelope template definition that will be subsequently completed, created, and sent. Specify the Salesforce ID of the record in the dfsle.Entity parameter that is to be used as the source object for the envelope.

Id mySourceId; // The ID of the initiating Salesforce object
String templateId; // The ID of the DocuSign template
// Create an empty envelope
dfsle.Envelope myEnvelope = dfsle.EnvelopeService.getEmptyEnvelope(
new dfsle.Entity(mySourceId));
// The initiating Salesforce entity

Step 3. Specify the recipient data for the envelope

Create a dfsle.Recipient object for each recipient of the envelope. These recipient objects contain the full set of data on the recipient’s role in the signing process: their role, authentication data, status in the workflow, and contact settings.

In this example, the envelope will have one recipient: a document signer. Refer to the code comments for each parameter and its significance when creating a recipient. Once a recipient is created, use the withRecipients method to add it to the envelope.

// We will use a Salesforce contact record as a Recipient here
Contact myContact = [SELECT Id, Name, Email FROM Contact LIMIT 1];
//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
    'Signer 1', // Role Name. Specify the exact role name from template
    new dfsle.Entity(myContact.Id)); // Source object for the recipient
// Add a recipient to the envelope
myEnvelope = myEnvelope.withRecipients(new List<dfsle.Recipient> { myRecipient });

Step 4. Specify a Docusign template for the envelope

Create a new document and add it to the envelope. In this example, you create a document representing a Docusign template using the dfsle.Document.fromTemplate method and passing in the ID of a valid Docusign template. Then, use the Envelope’s dfsle.Envelope.withDocuments method to add the document to the envelope.

To find the template ID, go to the Docusign Apps Launcher in your Salesforce org and choose the “Docusign Envelope Templates” tab. Select the template you want to use and copy the ID under the Details tab.

Note: If you created your template with writeback options you will need to add those same options in your Apex code using the dfsle.Envelope.withOptions method.

// myTemplateId contains the DocuSign Id of the DocuSign Template
dfsle.UUID myTemplateId = dfsle.UUID.parse(templateId);
// create a new document for the Envelope
dfsle.Document myDocument = dfsle.Document.fromTemplate(
    myTemplateId, // Template Id in dfsle.UUID format
    'myTemplate'); // Name of the template
//add document to the envelope
myEnvelope = myEnvelope.withDocuments(new List<dfsle.Document> { myDocument });

Step 5. Send the envelope

Send the envelope using the dfsle.EnvelopeService.sendEnvelope method.

The sendNow parameter is set to true to indicate that you want to send the envelope immediately. Setting the sendNow parameter to false will save the envelope as a draft. The Apex Toolkit does not support sending a draft envelope. To send a draft envelope, you will need to call the eSignature REST API outside of the Apex Toolkit.

// Send the envelope
myEnvelope = dfsle.EnvelopeService.sendEnvelope(
    myEnvelope, // The envelope to send
    true); // True to send the envelope now

Step 6. Get envelope status

Docusign administrators can track the status of Docusign envelopes after sending them to recipients by using the dfsle.StatusService.getStatus method.

This method returns the current status of the envelope (Created, Deleted, Sent, Delivered, Signed, Completed, or Declined), the time and date of the most recent action on the envelope, and other information, as a list of Envelope.Status objects. This method is passed a set of Salesforce source records that are associated with envelopes and an integer specifying the maximum number of records that will be returned.

Getting envelope status is useful to ensure that the envelope operations you’ve already performed, such as sending, confirming delivery or signing, and completion, have been executed successfully and to detect new status changes for an envelope. You must be the sender of the envelopes to call this method.

Id mySourceId; // The Salesforce ID of the object from which DocuSign envelopes were sent.
// Retrieve the five most recent envelope statuses from the Salesforce source object.
// The status results are sorted oldest to newest.
List<dfsle.Envelope.Status> myStatus = dfsle.StatusService.getStatus(
    new Set<Id> { // IDs of the Salesforce objects with associated status.
        mySourceId
    },
    5); // Maximum number of records to return.
// Display or take action on the returned statuses.

Step 7. Execute your method

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.

ApexToolkit.sendEnvelopeMethod();

Next steps

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