Custom signature workflow

Basics

When a signature request is created using the API, the workflow that signers need to follow can be highly customized. This article explain how this customization can be achieved.

The minimal signature workflow is the following:

1. An email asking to sign the document is sent to each signer by the Woleet platform. This email must include a link redirecting to a signature page.
2. The signer reads the email, clicks on the link and is redirected to a signature page.
3. The signature page eventually signs the document by authenticating using the secret identifier of the signer included in the redirection link.

The default signature workflow sends more emails (see below for a full description) but all additional emails can be disabled or customized.
Note that although emails are always sent by the Woleet platform, the sender's email and name can also be customized.
The default email asking to sign the document redirects sirgners to the default signature page hosted by the Woleet platform. However, the redirection can be easily modified to redirect to a custom signature page. Since implementing a custom signature page is straightforward (it can be as simple as one POST call) it is easy to implement a fully customized signature workflow.

Email types

Here is the list of all email types sent by the Woleet platform when using the default signature workflow:

Templating engine

Each email type is associated to a default template. The Woleet platform uses Velocity Engine 2.2 as templating framework.
Default templates are made of HTML content using Velocity Template Language annotations and can be overwritten by custom templates.
Custom templates can also use Velocity Template Language annotations.

Customize the workflow

The default signature workflow can be customized using the vars property of the signature request. This property can be used to store a set of variables as key/value pairs. These variables can be used to:

• disable some email types
• provide custom templates for some email types
• define or overwrite variables used by templates

Templates have access to some predefined variables depending on the type of email (eg. requesterName) plus to all variables defined at signature request level. Variables defined at signature request level can overwrite predefined ones, and can themselves be overwritten by variables defined at signer level.

Disable some email types

To disable a given email type, set a {email type identifier}Disabled boolean variable to true:

{
  ...
  "vars": {
    "signatureProofConfirmedSigneeEmailDisabled": true,
    "signaturefConfirmedSigneeEmailDisabled": true      
  }
}

Note that all email types but signatureRequestSigneeEmail and signatureRequestFeedbackRequesterEmail can be deactivated.

Provide custom templates for some email types

To provide a custom template for a given email type, store the template in a {email type identifier}Template string variable:

{
  ...
  "vars": {
    "signatureRequestSigneeEmailTemplate": " "Hi, Please sign at <a href=\"https://sign.acme.com/?signatureRequestURL=$tools.urlEncode($signatureRequestURL)\">Sign</a>"
  }
}

Define or overwrite variables used by templates

Depending on the email type, some variable are predefined and can be used in the related template.
To overwrite a predefined variable, simply define a variable with the same name at signature request level:

{
  ...
  "vars": {
    "requesterName": "ACME Corp."
  }
}

Predefined variables

Here is the list of all predefined variables that can be used in email templates:

Utilities

You can use the tools.urlEncode macro to URL encode any URL parameter:

<a href="$signingURL?signatureRequestURL=$tools.urlEncode($signatureRequestURL)">
  #if($lang == "en")
    Sign
  #elseif($lang == "fr")
    Signer
  #end
</a>

Examples

Here is a sample curl call creating a customized signature request:

• it disables all optional emails
• it provides a custom template for email sent to signers
• the custom template provides the name and a link to the file to sign to the signer, so that he can download it
• it redirects the signer to a custom signature page using a srURL argument to retrieve the signature request URL
• it overwrites the name of the requester to "ACME Corp."
• it uses "ACME Corp." and "[email protected]" as the name and email for all emails sent

curl -u login:password -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "name": "ACME Corp. Terms and Conditions",
  "vars": {
    "serviceName": "ACME Corp.",
    "serviceEmail": "[email protected]",
    "requesterName": "ACME Corp.",
    "signatureConfirmedSigneeEmailDisabled": true,
    "signatureConfirmedRequesterEmailDisabled": true,
    "signatureProofConfirmedSigneeEmailDisabled": true,
    "signatureAttestationEmailDisabled": true,
    "signatureRequestSigneeEmailTemplate": "Hi $signeeName,<br>$requesterName invites you to sign <a href=\"$fileURL\">$fileName</a><br><a href=\"https://sign.acme.com/?srURL=$tools.urlEncode($signatureRequestURL)\">Sign</a>"
  },
  "hashToSign": "c8db8eaef2524d4c823d7b014214fda86f6480cc6d145f4c908cc01de37fb102",
  "fileName": "ACME Corp. TCU",
  "fileURL": "http://acme.com/tcu.pdf",
  "authorizedSignees": [ { "commonName": "John Doe", "email": "[email protected]"} ]
}' 'https://api.woleet.localhost/v1/signatureRequest'