Customize signature workflow

Basics

When a signature request is created using the API, the workflow followed by signers can be highly customized, including:

• the branding, the content and the type of emails sent to signers
• the signature page on which the signers are redirected
• the branding of the Signature attestation document

The minimal/simplest signature workflow is the following:

1. An email asking to sign the document is sent to each signer by the Woleet platform. This email includes a link redirecting the signer 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 delegating the signature to the Woleet backend (the signer authentication is done using a secret identifier 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 email and the name of the sender can also be customized.

The default email asking to sign the document redirects signers to a 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.

List of email types

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

Templating engine

Each type of email has a default template. The Woleet platform uses Velocity Engine 2.3 as template engine.
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
• brand the Signature attestation document
• define or overwrite variables used by templates

Templates have access to a set of predefined variables depending on the type of email (eg. requesterName) plus to all variables defined at signature request level using the vars property. Variables defined at signature request level 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,
    "signatureConfirmedSigneeEmailDisabled": true      
  }
}

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

Provide custom templates for some email types

To provide a custom template for a given email type, store the template of the content of the email in the {email type identifier}ContentTemplate string variable, and the template of the subject of the email in the {email type identifier}SubjectTemplate string variable:

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

Customize the Signature attestation document

At the very end of the signature workflow (ie. when the signature request is CLOSED or COMPLETED) the Signature attestation document (a PDF file) is by default sent by email to all signees.
The template used to generate this document cannot be customized yet, but uses variables allowing to "brand" the document by overwriting their default value:

Define or overwrite variables used by templates

Some variable are predefined and can be used in various templates.
To overwrite a predefined variable, simply define a variable with the same name at signature request level:

{
  ...
  "vars": {
    "serviceName": "ACME Sign",
    "requesterName": "ACME Corp."
  }
}

List of 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. legal dept."
• it uses "ACME Corp." and "[email protected]" as the sender 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. legal dept.",
    "signatureConfirmedSigneeEmailDisabled": true,
    "signatureConfirmedRequesterEmailDisabled": true,
    "signatureProofConfirmedSigneeEmailDisabled": true,
    "signatureAttestationEmailDisabled": true,
    "signatureRequestSigneeEmailSubjectTemplate": "Please sign $fileName",
    "signatureRequestSigneeEmailContentTemplate": "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": "https://acme.com/privacy.html",
  "authorizedSignees": [ { "commonName": "John Doe", "email": "[email protected]"} ]
}' 'https://api.woleet.io/v1/signatureRequest'

Customize the signature page

To customize the signature page, you need to host a new signature page on your own, and redirect signers to this page by overwriting the signingURL variable, or by providing a custom template for the Signature request to signer email.

Here is a sample minimal HTML/Javascript code implementing a custom signature page:

<html>

<head>
  <script>

    // Get signature request URL parameter
    var srURL = new URL(window.location.href).searchParams.get("srURL");
    console.log("signature request URL: ", srURL);

    // Get the signer secret identifier
    var signeeId = new URL(srURL).searchParams.get("signeeId");
    console.log("signer secret identifier: ", signeeId);

    // Sign the signature request on behalf of the signer
    function sign() {

      // Build the delegate URL from the signature request URL
      var delegateURL = new URL(srURL);
      delegateURL = delegateURL.origin + delegateURL.pathname + "/delegate";
      console.log("delegate URL: ", delegateURL);

      // Call the delegate URL
      var http = new XMLHttpRequest();
      http.open('POST', delegateURL, true);
      http.setRequestHeader('Content-type', 'application/json');
      http.onreadystatechange = function () {
        if (http.readyState == 4 && http.status == 200) {
          console.log("done");
        }
      }
      http.send(JSON.stringify({ signeeId: signeeId }));
    }

  </script>
</head>

<body>
<button onclick="sign()">Sign</button>
</body>

</html>