Basics

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

• the set of email types sent to parties can be modified
• the subject and content of emails sent to parties can be branded or fully customized
• the signature page to which the signers are redirected can be branded or fully customized
• the signature attestation document sent to parties can be branded or fully customized

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 the signature page.
2. The signer reads the email, clicks on the link and is redirected to the signature page.
3. The signature page eventually signs the document by delegating the signature to the Woleet platform (the signer's email address is authenticated using a secret identifier included in the link, and optionally using an OTP sent using a text message).

The default signature workflow sends more email types. Anyway, all additional email types can be disabled, branded or fully 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 the default signature page hosted by the Woleet platform. This default signature page can be branded and aliased using a custom signature page domain (eg. mysignatureapp.acme.com). If branding the page is not sufficient (eg. if the signature must be performed from within an enterprise application) the redirection link can be customized to redirect to a custom signature page hosted on premise. Implementing a custom signature page is straightforward (see example below).

The default signature attestation document sent to all parties at the end of the signature workflow can also be branded or fully customized. In all cases, the proof bundle (a JSON file containing all technical proofs required to verify the signatures) will be attached to this PDF document, so that it can be used as a proof when verifying signatures (eg. on Woleet Auditor).

About the template engine

The Woleet platform uses Velocity Engine 2.3 as template engine.

Each email type has a default template for its subject and its content.
The signature attestation document also has a default template for its content.
Default templates can be overwritten by providing custom templates.
Templates must be HTML files using Velocity Template Language annotations.

How to customize the signature workflow

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

Templates have access to a set of predefined variables (eg. $requesterName) plus to all variables defined at signature request level: variables defined at signature request level overwrite predefined ones.

These variables can be used to:

• Disable some email types
• Brand all email types and the signature attestation document
• Provide custom templates for some email types
• Provide a custom template for the signature attestation document
• Define new variables to be used by custom templates

Disable some email types

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

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

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

Brand all email types and the signature attestation document

Default templates used to generate the signature workflow emails emails and the signature attestation document use predefined branding variables dedicated to "branding" their content (ie. change the logo, the set of default colors, the service information, etc.):

{
  ...
  "vars": {
    "brandColor1": "#f00",
    "brandColor2": "#a00",
    "textColor1": "#999",
    "textColor2": "#888",
    "serviceName": "ACME Corp.",
    "serviceEmail": "[email protected]",
    "serviceURL": "https://acme.com",
    "serviceLogoURL": "...",
    "serviceIllustrationURL": "...",
    "serviceContactEmail": "[email protected]",
    "serviceDocumentationURL": "https://doc.acme.com",
    "serviceAddress": "ACME Corp. postal address", 
  }
}

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>"
  }
}

Provide a custom template for the signature attestation document

To provide a custom template for the signature attestation document, store the template of signature attestation document in the signatureAttestationTemplate string variable:

{
  ...
  "vars": {
    "signatureAttestationTemplate": "<html><body><div>Is there anybody out there? - Pink Floyd</div></body></html>"
  }
}

Define new variables to be used by custom templates

Custom templates can use all predefined template variables plus all custom variables defined at signature request level:

{
  ...
  "vars": {
    "lyrics": "Is there anybody out there?",
    "author": "Pink Floyd",
    "signatureAttestationTemplate": "<html><body><div>$lyrics - $author</div></body></html>"
  }
}

Example of customized signature workflow

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

• it disables most optional emails
• it provides a custom template for signature request emails 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 (see example below)
• 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.",
    "signatureReminderSigneeEmailDisabled": true,
    "signatureCanceledSigneeEmailDisabled": true,
    "signatureClosedSigneeEmailDisabled": true,
    "signatureConfirmedSigneeEmailDisabled": true,
    "signatureProofConfirmedSigneeEmailDisabled": true,
    "signatureConfirmedRequesterEmailDisabled": 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'

How to customize the signature page

Woleet's default signature page can be customized to your organization's graphic identity and made available on a domain of your choice (eg. https://signature.acme.com).

You can do this by defining your organization's signature page domain using Woleet Dashboard -> 'My organization' -> 'Signature page'.

Once defined, you can overwrite a set of variables used to define the graphic identity of your organization (eg. logo URL, main and secondary colors, etc.). Most of these variables are documented on Woleet Dashboard.

If branding the default page is not sufficient (eg. if the signature must be performed within an enterprise application) you have to host a custom 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.

Example of customized signature page

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>

List of email types

Here is the list of all types of email sent by the Woleet platform during the default signature workflow with their respective identifier:

List of predefined template variables

Branding variables

Context variables

Template 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>