Docusign v1.3

This package provides capabilities that extend the Avoka Transact platform for users wishing to include eSignature services in their forms using the Docusign services. Signing experiences available include:

  1. Embedded Signing

    Signing will occur within the form, before final submission of the form.

  2. Remote Signing

    Signing will occur after the form has been submitted, with signing invitations being sent to signatories via email.

To support signing capability this package provides the following components

  1. Docusign Tab

    A Docusign Tab, supports the placement of docusign related fields anywhere on the form. Current Tab types supported are :

    • Signature
    • Date
    • Initial

  2. Embedded Signing Ceremony

    The embeeded signing ceremony component uses an iframe to create an embedded (in-form) signing experience for users.

Using The Tabs

Placing a signature block is a simple a placing it on the form. The signature block must then be configured with its signers details. At minimum a tab will require a signers :

  • First Name
  • Last Name
  • Email Address

IMPORTANT: All tabs belonging to the same signer MUST contain the same field references, not doing so may create additional signers due to a mismatch in signer details

Positioning Tabs

Positioning the Tab onto the form can be done in one of two ways

  1. Relative

    The docusign tab will be placed onto the pdf receipt where the tab was placed onto the form

  2. Absolute

    The docusign tab will be placed onto the pdf receipt at the pixel location of the page number specified by the parameters "Page Number", "Position X" and "Position Y"

Embedding the signing ceremony

The embedded signing ceremony required minimal configuration, and can simply be placed on the form. The following rules are provided on the form to allow customisation of the signing experience :

  1. On Complete

    Allows the form designer to specify a script to run when the signing ceremony has been completed.

  2. On Failure

    Allows the form designer to specify a script to run if the signing ceremony fails (usually due to a signer opting out or declining to sign)

NOTE : The signing ceremony will begin as soon as the signing ceremony is visible

WARNING : Once the Signing Ceremony has been created it cannot be changed, as changing the contents of the documents would void the signing package.

Delivering the Signed Documents

The Docusign - Delivery Process is provided so completed Docusign Envelopes will be attached to their respective transactions once all signers have completed their signing. The delivery process may be customised by configuring this service to set the delivery channel of the transaction to a new channel once it has finished see the service help documentation for details.

Licensing

Clients must ensure they are appropriately licenses in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with DocuSign directly.

Compatibility

This package has the following compatibility requirements:

ModuleCompatibilityNotes
Transact Manager5.0.2 or above
Transact Maestro5.0.14 or above

Installation Instructions

To install this package please walk through the following procedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
  5. Import each archive found in the libraries folder to Maestro. Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Usage Instructions

To configure Docusign please walk through the following procedure:

  1. Open your form in Maestro and add the Docusign Tab component from the Docusign category in the Palette. This widget supports two modes, relative and absolute. To use the relative mode, place the Docusign Tab at the desired place on the form. To use absolute position, change the position field to absolute, set the PDF page number and X and Y coordinates.

    NOTE : The Docusign Tab component must be placed on a visible page/container, so it can be rendered and sent to Transact Manager and be used to create the Docusign envelope. If you have a page that is shown on receipt, using the "Show on Receipt" rule, the Docusign Tab component must be placed on a visible page, and be configured as absolute position, with the page number to be the page you show only on receipt.

  2. Open the Signer Details section, found on the Properties tab of the Docusign Tab component. And set the field reference of your First Name, Last Name, Email and Mobile fields.

    NOTE : You can add more than one Docusign Tab. Follow the same instructions as before, and change the Tab Type property to signature, initial or date. To prevent duplicate XML binding rename the component from Docusign Tab to Docusign Tab initial for example.

  3. Place on your form the Docusign Signing Ceremony component from the Docusign category in the Palette. This is where the Docusign iframe is displayed.
  4. Open the Configuration section, found on the Properties tab of the Docusign Signing Ceremony component. And set the height of the Docusign iframe.
  5. By default the component Docusign Signing Ceremony is triggered when you enter the page. To trigger it based on some condition, add a Visibility rule.
    For example:
    data.areYouAbleToSignNow === true
  6. Open the Properties tab of the Docusign Signing Ceremony component, and create new rule called On Complete. It allows you to notify the user that the signing ceremony is completed.
  7. Open the Properties tab of the Docusign Signing Ceremony component, and create new rule called On Failure. It allows you to notify the user that the signing ceremony is failed. Or to display the error message returns from this rule.
  8. To configure the Docusign - Delivery Process to attach the signed receipt to the transaction, please walk through the following procedure:
    1. Create new Delivery channel in Transact Manager, found under your organization >> Delivery Channels . Update the Delivery Method field to 'Delivery Process'
      Update the Delivery Process field to 'Docusign - Delivery Process'. Update the Delivery Process Name and Name fields to 'docusign'.
    2. Open your form in Transact Manager and set the Production Delivery channel to 'docusign'.
    3. Create a scheduled job in Transact Manager called 'DocuSign Status Poller'. Found under System >> Scheduled Job. Update the Service Definition to 'Docusign - Envelope Status Poller'. Set the 'trigger type', 'repeat' and' repeat interval' fields as required.

Release Notes

Version 1.3 Nov 16, 2022

  • Implement OAuth authentication. DocuSign APIs will require OAuth authentication to funcation by March, 2023.

Version 1.2 Aug 08, 2017

  • Error handling, data validation and usage instructions.
  • Keep TM session alive as long as the embedded DocuSign signing session is active. A ping request from DocuSign is executed against TM every 5 minutes.

Version 1.1 Jun 28, 2017

  • Added support for Maestro 5.1 language translation features.

Version 1.0 Feb 23, 2017

  • Baseline release.

Maestro Assets

Docusign Signing Ceremony Library: exchange.docusign Category: Docusign

A widget for embedding the docusign signing ceremony inside the form

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Complete : A script to run when all signers have completed their signing
  • On Failure : A script to run when the signing ceremony has failed and cannot be complete

Properties

Property Category Description Type Default
Height Configuration

The height of the iFrame the ceremony will appear in

integer 300
Progress Message Configuration

The message to display while the agreement is being generated for signing

text Please wait while we prepare your agreement
Docusign Tab Library: exchange.docusign Category: Docusign

A component for placing docusign tabs onto the form

Properties

Property Category Description Type Default
Tab Type Tab

Select the Tab type

Options:

  • SIGNATURE : Signature
  • INITIAL : Initial
  • DATE : Date
 option SIGNATURE
First Name Field Signer Details

Form element that contains the signer's first name

fieldRef
Last Name Field Signer Details

Form element that contains the signer's last name

fieldRef
Email Field Signer Details

Form element that contains the signer's email address

fieldRef
Mobile Field (Optional) Signer Details

Form element that contains the signer's mobile number (optional)

fieldRef
Authentication Type (Optional) Signer Details

Select your static authentication preference EMAIL or SMS. Alternatively you can use the 'Authentication Type Ref Field' property to attach a field you created with values EMAIL and SMS. This field can be offered to the user to select from, based on his preferences.

Options:

  • :
  • EMAIL : EMAIL
  • SMS : SMS
 option
Authentication Type Ref Field (Optional) Signer Details

Set a reference to a form element that contains the signer's authentication preference, valid values are EMAIL|SMS

fieldRef
Position Position

How the signature block will be placed on the form

Options:

  • RELATIVE : Relative
  • ABSOLUTE : Absolute
 option RELATIVE
Page Number (Absolute) Position

The receipt page number to place the signature

integer
Position X (Absolute) Position

Absolute X position of the signature (pixels)

integer
Position Y (Absolute) Position

Absolute Y position of the signature (pixels)

integer

Services

Docusign - Create Envelope v1
A dynamic data service design for use when creating an embedded DocuSign signing experience

Service Connection

Compatibility

Module Compatibility
Manager 5.0.2

Service Parameters

Name Description Required Default
Docusign Email Subject Template The subject for email delivery from docusign No Docusign documents for $formName
Docusign Email Blurb The blurb for email delivery from docusign No
Docusign Passcode Email From Address The email address that the passcode email will appear from No
Docusign Passcode Email Subject Template The subject line for passcode emails Yes Your passcode for signing documents for ${formName}
Docusign Passcode Email Body Template The subject line for passcode emails Yes

To ${name}

Your passcode for signing your document is : ${passcode}

Outputs

Name Description
envelopeId The unique ID of the created envelope
signers A list of [signer] objects that were created for this envelope
[signer].clientUserId A unique id created for this signer that will be used to retrieve their signing ceremony
[signer].email The email address of the signer
[signer].firstName The first name of the signer
[signer].lastName The last name of the signer
status The status of the created envelope (will only ever be 'sent')
statusDateTime The timestamp of the last status update
uri The uri location for access this envelope and operations related to it
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
Docusign - Delivery Process v1
A delivery service for delivery of transactions with attached docusign envelope details

Service Connection

Compatibility

Module Compatibility
Manager 5.0.2

Service Parameters

Name Description Required Default
Docusign Email Subject The email subject to display for Docusign email delivery No Docusign $formName
Docusign Email Blurb The email blurb to display for Docusign email delivery No
Final Delivery Channel The delivery channel to perform final delivery on No
Docusign - Envelope Status Poller v1
A scheduled service for polling DocuSign services to check the status of docusign envelopes related to pending transactions

Service Connection

Compatibility

Module Compatibility
Manager 5.0.2
Docusign - Get Signing URL v1
A dynamic data service used to retrieve the signing URL for a user as part of an embedded signing ceremony

Service Connection

Compatibility

Module Compatibility
Manager 5.0.2

Inputs

Name Description Required
envelopId the envelope Id to retrieve the signing ceremony for Yes
firstName the first name of the signer to retrieve the signing ceremony for Yes
lastName the last name of the signer to retrieve the signing ceremony for Yes
email the email of the signer to retrieve the signing ceremony for Yes
clientUserId the client user ID of the signer to retrieve the signing ceremony for Yes
authenticationMethod the method used to authenticate the signer before calling this method Yes

Outputs

Name Description
url the url of the signing ceremony.
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
Docusign - Signing Ceremony Callback v1
A dynamic data service used to provided a callback endpoint for docusign when a signer has completed signing as part of an embedded signing ceremony. No configuration of this service is required

Compatibility

Module Compatibility
Manager 5.0.2

Service Parameters

Name Description Required Default
responseContentType The content type this service returned by the callback (will always be text/html) Yes text/html
Page Template The template of the callback page Yes null

Service Connections

The following service connections are used by this package.

Docusign OAuth
Property Name Description Required
Type HTTP Endpoint Yes
Type DocuSign OAuth Yes
DocuSign Server Hostname Should be host name of Docusign API server
  • Demo: account-d.docusign.com
  • Production: account.docusign.com
 Yes
Docusign API User Id Should contain the Id of your DocuSign OAuth API user Yes
Docusign Integrator Key Should contain your DocuSign Integrator Key Yes
Private Key File Name Should contain the generated private key file from the DocuSign admin console

Upload it by clicking the Choose File button

 Yes
Docusign - pre 22.10
Property Name Description Required
Type HTTP Endpoint Yes
Type DocuSign Yes
DocuSign Server URL Should be host name of Docusign API server
  • Demo: account-d.docusign.com
  • Production: account.docusign.com
 Yes
DocuSign Username Not required for this release No
DocuSign Password Not required for this release No
DocuSign Account Id Should contain the Id of your DocuSign OAuth API user Yes
DocuSign Integrator Key Should contain your DocuSign Integrator Key Yes
Data File Name Should contain the generated private key file from the DocuSign admin console

Upload it by clicking the Choose File button

 Yes