Skip to navigation

How to use embedded signing

View as Markdown

This topic demonstrates how to write Apex code that will use Embedded signing to create and send a Docusign envelope to the current Salesforce user for immediate signing within Salesforce.

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. If you are using this code in a Salesforce Community, make sure that you have satisfied the permission prerequisites described below.

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. In the Docusign Setup tab, choose Configuration in the left menu, then go to the Settings tab and choose a user next to Enable System sender. This allows Community users to send envelopes even if they are not a member of the Docusign account. In that case, envelopes will be sent from the admin user that you selected.
  5. Make sure that the sender’s account is assigned the Docusign Sender permission set. This gives them permissions to perform basic Docusign sending and signing permissions in Salesforce. This permission can only be granted by a Salesforce administrator, which is typically assigned when provisioning the user account. Docusign senders differ from users in that they do not have permission to access methods for retrieving envelope status.
  6. Create a Salesforce DX project. This requires that you have already set up Visual Studio Code with the necessary Salesforce development tools. You will be using Visual Studio Code to create a Lightning Web Component that will initiate your embedded signing session because Salesforce does not support development of Lightning Components in the Developer Console.

Required data

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

Data elementDescription
{TEMPLATE_ID}A GUID value that identifies a Docusign template that is used to create a Docusign envelope. This value is automatically generated by Docusign when the template is created.

Step 1. Define your class

Create the class that will contain most of the code in this how-to. To create a class in Visual Studio Code, navigate to the force-app/main/default/classes folder in your SFDX project structure, then right-click classes and select SFDX: Create Apex Class.

Apex
public class EmbeddedSigningController {
}

Step 2. Create and send an envelope

Before you can start the embedded signing process, you must first create a Docusign envelope and populate it with at least one document and recipient.

  1. Use the dfsle.EnvelopeService.getEmptyEnvelope method to create an empty envelope template definition that can be subsequently completed, created, and sent.

  2. Use the dfsle.Document.fromTemplate method to create a new document using a template in your Docusign account.

  3. Create a dfsle.Recipient object for each recipient of the envelope using the dfsle.Recipient.newEmbeddedSigner method, which indicates that the process will use embedded signing (as opposed to requesting a signature via email).

    In this example, the envelope will have one recipient, a document signer. Once a recipient is created, use the withRecipients method to add it to the envelope.

  4. Add the documents and recipients to the envelope and use the dfsle.EnvelopeService.sendEnvelope method to send it.

Apex
@AuraEnabled
public static String sendEnvelope(String template, String description, Id recordId) {
Id mySourceId = recordId; // The ID of the initiating Salesforce object
// Create an empty envelope and add a Salesforce Document and embedded signer recipient
// The embedded signer will be the current user with sequence and routing order 1 and role "Signer 1" by default
dfsle.Envelope dsEnvelope = dfsle.EnvelopeService.getEmptyEnvelope(
new dfsle.Entity(mySourceId)) // The initiating Salesforce entity--current SF user (salesperson)
.withDocuments(new List<dfsle.Document> {
dfsle.Document.fromTemplate(dfsle.UUID.parse(template), description)
})
.withRecipients(new List<dfsle.Recipient> {
dfsle.Recipient.newEmbeddedSigner() // An embedded signer
}
);
// Send the envelope.
dsEnvelope = dfsle.EnvelopeService.sendEnvelope(
dsEnvelope, // The envelope to send
true // Send now?
);
// Return string value of DocuSign envelope ID
return String.valueOf(dsEnvelope.docuSignId);
}

Step 3. Host an embedded signing session

After the envelope is sent, initiate an embedded signing session. The Apex Toolkit will verify that the current recipient matches the current Salesforce user and request a link to a one-time signing session.

The user will be redirected to this link to view or sign the envelope document(s). After signing is complete, the user is redirected back to the Salesforce application automatically.

Apex
@AuraEnabled
public static String getEmbeddedSigningUrl(String envId, String url) {
Url mySigningUrl = dfsle.SigningService.getEmbeddedSigningUrl(
dfsle.UUID.parse(envId), // envId value as a UUID
new URL(url) // url value as a URL
);
// Return string value of Url to controller
return mySigningUrl.toExternalForm();
}

Step 4. Create a Lightning Web Component

To create a new Lightning Web Component:

  1. Navigate to the force-app/main/default/lwc folder in the menu on the left.
  2. Right-click lwc and select SFDX: Create Lightning Web Component. This will generate the files that you need to create your component.
  3. Open the .js-meta.xml file to see metadata about your new component.
  4. Set the isExposed field to true and add targets for lightning__AppPage, lightning__RecordPage, and lightning__HomePage to ensure that your component can be added to pages in your org.
XML
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>50.0</apiVersion>
<isExposed>true</isExposed>
<targets>
<target>lightning__AppPage</target>
<target>lightning__RecordPage</target>
<target>lightning__HomePage</target>
</targets>
</LightningComponentBundle>

Step 5. Edit your component’s HTML

Open the HTML file under your component. You can use this file to style your Lightning Web Component however you like.

HTML
<template>
<div>
<lightning-button label="Embedded Signing" title="Start embedded signing session" onclick={handleClick}></lightning-button>
</div>
</template>

Step 6. Use your Lightning Web Component to initiate embedded signing

Finally, edit your Lightning Web Component’s JavaScript file so that the user’s interaction with the component executes the methods you defined in the previous steps.

  1. Open the JS file under your component.
  2. Import the sendEnvelope and getEmbeddedSigningUrl methods from your EmbeddedSigningController class.
  3. Save the ID of the Docusign template that you want to use to the template variable.
  4. Use JavaScript’s handleClick method to initiate embedded signing by calling your sendEnvelope method, getting an embedded signing URL, and redirecting the browser to the signing URL.

When you’re finished editing your component, you will deploy your source code to your Salesforce org. To do this, navigate to the force-app/main/default folder in the menu on the left and right-click default, then select SFDX: Deploy Source to Org.

Now, when you edit any page in your Salesforce org, you will see your new Lightning Web Component in the Lightning App Builder. You can add your component to a page and use it to initiate an embedded signing session.

View the source code for this how-to on GitHub: Apex

JavaScript
import { LightningElement, api } from 'lwc';
import sendEnvelope from '@salesforce/apex/EmbeddedSigningDemo.sendEnvelope';
import getEmbeddedSigningUrl from '@salesforce/apex/EmbeddedSigningDemo.getEmbeddedSigningUrl';
export default class EmbeddedSigningComponent extends LightningElement {
template = '27123f19-xxxx-xxxx-xxxx-adbcf9b8fa5f';
description = 'Embedded Signing';
@api recordId;
handleClick() {
sendEnvelope({template: this.template, description: this.description, recordId: this.recordId})
.then((envelopeId) => (
getEmbeddedSigningUrl({
envId: envelopeId,
url: window.location.href
})
))
.then((signingUrl) => {
window.location.href = signingUrl;
})
.catch((error) => {
console.log('Error:');
console.log(error);
});
}
}

Next steps