Signature workflow customization

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

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

You can brand the default signature page by deploying your custom signature page domain from the Woleet Dashboard (eg. mysignatureapp.acme.com) and by setting customization variables for your signature page domain.

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

Type

Purpose

Comment

Identifier

Signature request to signer

Sent to the signer when the signature request is activated (ie. no state, or state is IN_PROGRESS)

Mandatory: cannot be disabled
Must provide a link to a signature page including the secret identifier of the signer

signatureRequestSigneeEmail

Signature reminder to signer

Sent to the signer 3 days after the signature request if the signer has not signed yet

signatureReminderSigneeEmail

Signature canceled to signer

Sent to the signer when the signature request is canceled. (ie. its state is CANCELED)

signatureCanceledSigneeEmail

Signature closed to signer

Sent to the signer when the signature request is closed. (ie. its stated is CLOSED).

signatureClosedSigneeEmail

Signature confirmation to signer

Sent to the signer right after he signs the document

Should provide a link to the signature verification page

signatureConfirmedSigneeEmail

Signature deadline updated to signer

Sent to the signer if the signature deadline is postponed

signatureDeadlineUpdatedSigneeEmail

Signature proof to signer

Sent to the signer when his signature proof is ready

The signature proof is provided as an attachment

signatureProofConfirmedSigneeEmail

Signature confirmation to requester

Sent to the requester after each signature

Not sent if the requester is also the signer (same email)
Should provide a link to the signature verification page

signatureConfirmedRequesterEmail

Signature feedback to requester

Sent to the requester if a signer reports some feedback about the signature request

Mandatory: cannot be disabled

signatureFeedbackRequesterEmail

Signature attestation to parties

Sent to the requester, the watchers and the signers when the signature request is completed or closed and the signature attestation document is ready

The signature attestation PDF document is provided as an attachment

signatureAttestationEmail

Signature request to watcher

Sent to the watcher when the signature request is activated (ie. no state, or state is IN_PROGRESS)

signatureRequestWatcherEmail

Signature canceled to watcher

Sent to the watcher when the signature request is canceled. (ie. its state is CANCELED)

signatureCanceledWatcherEmail

Signature closed to watcher

Sent to the watcher when the signature request is closed. (ie. its stated is CLOSED).

signatureClosedWatcherEmail

Signature confirmation to watcher

Sent to the watcher right after a signer signs the document

Should provide a link to the signature verification page

signatureConfirmedWatcher#Email

List of predefined template variables

Branding variables

Name

Purpose

brandColor1

Main brand color of the service

brandColor2

Alternate brand color of the service

textColor1

Main text color of the service

textColor2

Alternate text color of the service

serviceName

Name of the service managing the signature request.
This name is used in emails and in the signature attestation document.
It is also used as sender name for all emails and OTPs.

serviceEmail

Email of the service managing the signature request.
This email is used as sender email for all emails.

serviceURL

URL of the service managing the signature request.
This URL is used in emails and in the signature attestation document.

serviceLogoURL

URL of the logo of the service managing the signature request.
This logo is used in emails and in the signature attestation document.

serviceIllustrationURL

URL of the illustration of the service managing the signature request.
This image is used in the signature attestation document.

serviceContactEmail

Contact email of the service managing the signature request.
This email is used in emails: end-users should get support at this address.

serviceDocumentationURL

URL of the documentation of the service managing the signature request.
This URL is used in emails: end-users should get documentation at this address.

serviceAddress

Postal address of the service managing the signature request.
This address is used in the signature attestation document.

Context variables

Name

Purpose

Comment

lang

Language to use in the email (as an ISO639-1 string).

Computed from the signature request's lang properties: currently, since only en or fr are supported by default templates, it is always fallbacks to one of these values, except if overwritten in vars.

requesterName

Name of the signature requester.

Defaults to "{first name} {last name}" of the account creating the signature request.

requesterEmail

Email of the signature requester.

Defaults to the email of the account creating the signature request.

isRequester

true if the email is intended for the requester of the signature.

isSignee

true if the email is intended for a signer of the signature.

signeeName

Name of the signer (eg. John Doe)

Defaults to the commonName property of the signer.

signeeEmail

Email of the signer

signatureRequestURL

URL of the signature request, including the secret identifier of the signer as a request parameter.

This URL is intended to be provided to the signature page, allowing it to authenticate as the signer to retrieve and/or sign the signature request.
Defaults to https://api.woleet.io/v1/signatureRequest/{signatureRequestId}?signeeId={signeeId}.

requiresOTP

true if an SMS OTP is required for the signer to sign.

If true the signature page needs to request the platform to send an OTP to the signer, and needs to provide this OTP to sign.

signingURL

URL of the signature page (without the signatureRequestURL parameter).

As an example, the default signatureRequestSigneeEmail template builds a Sign button redirecting to $signingURL?signatureRequestURL=$tools.urlEncode($signatureRequestURL).

signatureRequestId

Identifier of the signature request.

signatureRequestName

Name of the signature request.

signatureRequestState

State of the signature request.

signatureRequestDeadline

Deadline of the signature request.

signatureRequestSharingURL

URL of the signature request's sharing page.

This page can be used by anybody having the URL to:

  • follow the state of the signature request
  • verify all signatures
  • download the signature proofs
  • download the signature attestation document (if available).

documentName

Name of the document to sign.

Equals to fileName if set, or equals to signatureRequestName

fileName

Name of the file to sign.

If set in the signature request.

fileURL

URL of the data to sign (if set).

If set in the signature request.

isUploaded

true if the file to sign was uploaded.

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>