Setup
Before you can use e-signatures, you must first create an app in your DocuSign account and connect it to our ERP solution via the DocuSign interface. Then you must select DocuSign as the provider in the e-signature setup and define the required email subjects. After successful setup, e-signatures are available for the following documents:
| Area | Documents | Prerequisite |
|---|---|---|
| Sales | Sales Quote, Sales Order | Status = Released |
| Service | Service Order, Service Quote, Service Item Worksheet, Maintenance Contract | none |
| Rent | Rent Quote, Rent Contract, Additional Contract | Status = Released Only available with Aptean Rental. |
This chapter is divided into the following sections:
- Creating the DocuSign App
- Setting Up the DocuSign Interface
- Setting Up E-Signatures
- Setting Up Email Subjects
- E-Signature Status
Creating the DocuSign App
For the connection, you need an app in DocuSign with an integration key and an RSA key pair. To create the app, proceed as follows:
- Sign in to your DocuSign account.
- Navigate to Admin > Integrations > Apps and Keys.
- Note the User ID and API Account ID values in the My Account Information section.
- Click Add App and Integration Key.
- Enter a unique name for the app.
- Select the Third-party integration key option in the Integration Type section.
- Select Yes in the dialog.
- Copy the Integration Key displayed below the app name. You need it later for the Issuer (iss) and Consent Client ID fields.
- Click Generate RSA in the Service Integration section.
- Copy the complete private key, including the
-----BEGIN RSA PRIVATE KEY-----and-----END RSA PRIVATE KEY-----lines. - Select the checkboxes of all HTTP methods in the Additional settings section so that the interface can perform all required calls.
- Save your entries.
Setting Up the DocuSign Interface
The connection to DocuSign runs via the DocuSign interface. Authentication is performed via a JSON Web Token (JWT) that is signed with the private RSA key from your DocuSign app. General information about interfaces and JWT application endpoints can be found in the Interfaces and Integrations chapter.
Setting Up the Interface and JWT Application Endpoint
Important
Private keys are stored in isolated storage and are not transferred when an environment is copied or restored. Enter the private key again after every environment migration.
As long as the interface is active, its connection settings cannot be changed. To set it up, you prepare the interface and then enter the private key and the details from your DocuSign app in the JWT application endpoint. To set up the interface, proceed as follows:
- Use the quick search (ALT+Q) to find the Interface List page.
- Open the DocuSign interface.
- Enter the API Account ID from DocuSign in the Value field of the account_id line in the Parameters FastTab.
- Select the value JWT in the Authorization Type field in the Authorization FastTab.
- Click the selection field in the Authorization Code field.
- Create a new entry.
- A new JWT application endpoint is displayed.
- Enter a code for your DocuSign app in the JWT Endpoint Code field on the JWT application endpoint card.
- Enter a meaningful description for your DocuSign app in the Description field on the JWT application endpoint card.
- Select the value RS256 (RSA-SHA256) in the Signing Algorithm field.
- Select the value PEM in the Key Format field in the RS256 Private Key FastTab.
- Paste the private key from DocuSign into the Private Key field.
- Fill out the fields in the Standard Claims FastTab according to the following table:
| Field | Value | Source |
|---|---|---|
| Issuer (iss) | Integration key | DocuSign app |
| Subject (sub) | User ID | DocuSign account |
| Audience (aud) | account.docusign.com |
fixed value for the environment |
| Token Expiry (sec.) | 3600 |
fixed value (one hour) |
- Activate the Use Token Exchange toggle switch in the Token Exchange FastTab.
- Fill out the displayed fields according to the following table:
| Field | Value |
|---|---|
| Token Endpoint URL | https://account.docusign.com/oauth/token |
| JSON Response Key | access_token |
| Consent Authorization URL | https://account.docusign.com/oauth/auth |
| Consent Client ID | Integration key of the DocuSign app |
| Consent Scope | signature impersonation |
- Leave the Consent Last Granted At and Token Expires At fields empty for now. They are filled automatically as soon as consent has been granted and the first token has been retrieved.
- Click New Line in the Custom Claims FastTab.
- Enter the value scope in the Claim Name field and the value signature impersonation in the Claim Value field.
- Click Apply Key in the menu bar.
- The Has Private Key toggle switch is activated.
Granting Consent and Activating the Interface
To allow the interface to send signature requests on behalf of the DocuSign user, you grant consent once. To do so, proceed as follows:
- Click Show Redirect URI in the menu bar of the JWT application endpoint card.
- Add the displayed URI to your DocuSign app in Additional settings > Redirect URIs.
- Click Request Consent in the menu bar.
- The DocuSign sign-in page is displayed.
- Sign in with the user whose User ID you have entered in the Subject (sub) field.
- Grant the requested consent.
- Close the JWT application endpoint card.
- Check on the interface card whether the Authorization Type field contains the value JWT and the Authorization Code field contains the new endpoint.
- Click Activate Interface in the menu bar.
Setting Up E-Signatures
On the E-Signature Setup page, you define which provider is used for e-signatures. As long as no provider is selected, all e-signature functions are hidden.
Note
First set up and activate the DocuSign interface completely. If the interface is not set up or not active, an error message is displayed when you select the provider.
To set up e-signatures, proceed as follows:
- Use the quick search (ALT+Q) to find the E-Signature Setup page.
- Select the value DocuSign in the E-Signature Provider field.
The e-signature functions are displayed in the supported documents.
Setting Up Email Subjects
DocuSign sends each recipient an email with a link to the document. You can define the subject of this email per language on the E-Signature Setup page. When an e-signature is created, the subject is prefilled based on the language code of the document. If no subject is defined for this language, a default English subject is used. To set up the subjects, proceed as follows:
- Use the quick search (ALT+Q) to find the E-Signature Setup page.
- Select the desired language in the Language ID field in a new line in the Email Subjects by Language FastTab.
- Enter the subject in the Text field. You can use the following placeholders:
| Placeholder | Replaced by |
|---|---|
%1 |
document name |
%2 |
current date |
%3 |
name of your company |
Tip
Click the selection field in the Text field to display an overview of the available placeholders.
E-Signature Status
Each e-signature passes through different statuses. The status is determined from the status of the individual recipients in DocuSign:
| Status | Description |
|---|---|
| Draft | The e-signature has been created but has not yet been sent to DocuSign. Only one draft can exist per document at a time. |
| Sent | The e-signature has been sent to DocuSign and the recipients have been notified by email. The status remains until all recipients have signed. |
| Completed | All recipients have signed. |
| Declined | At least one recipient has declined to sign. |
| Cancelled | The e-signature has been canceled. The recipients can no longer sign the document. |
| Expired | The signing deadline has expired in DocuSign. |
Tip
To keep the status of sent e-signatures up to date without manual intervention, a job queue entry is set up automatically. It runs the Update Status action for all e-signatures with the status Sent.