Setting up and working with e-signatures
Our e-signature application allows users to send out legally binding documents from leads or loans. By making use of third-party providers, we can easily send documents to specific people, track its progress and perform actions based on signing activity. We have made the application as generic as possible, allowing our clients to decide which providers they want to use.
This documentation serves to explain the application’s setup procedure and features.
Contents
Terminology
Provider - The third-party service that provides the legally-binding signing service.
E-sign document - A document template that is configured once and meant to be reused. This contains the actual document file that the signers will sign.
Hidden tags - Markup text that should be copy-pasted onto the .odt files on the e-sign document. The markup text’s foreground should be set to white, meaning the text should be invisible in relation to the document’s background color.
Signature request - A single instance of an e-sign document being used on a Lead/Loan to request that individuals sign it.
Server actions - Functionality defined by a developer, triggered by some event, that can produce a custom outcome.
Connector modules - Applications that connect different applications with each other; enabling functionality to interact between the two. Contact support for more info on this if needed.
Setup e-sign account
Navigate to the E-Signatures application.
Find and click on the E-Sign Accounts menu item.
Click on the create button.
You will be greeted by the following screen. Note that all highlighted fields are required.
Select the appropriate Provider. If they require additional fields, the form view will be populated with them. The screenshot illustrates what Eversign’s form view looks like as an example.
Note that the application requires the appropriate connector modules to be installed for the provider you want to use.
6. Populate the empty fields as indicated by the required highlighting and click Save.
Some providers might require additional steps. Refer to the next section for these instructions.
Additional account setup required
Eversign
The required fields for Eversign can be found on the API dashboard after you’ve registered a new app. The name of the fields on our side match the name of the fields on theirs.
Ensure you’re in the right business by navigating to https://taskflow.eversign.com/select and selecting the appropriate business:
If you are working on a new instance and there is no business for it, please speak to management to create a new one.
Navigate to the developer page by clicking on the dropdown on the business name and selecting “Developer”:
Scroll to the bottom and click on “Register New App”. The following dialogue will open:
Enter the following values:
App Name - Just the name of the client. If you plan on having one account for testing and one for production, mark the app’s name accordingly, ex. Mustang Sandbox
App domain - the TaskFlow/TaskSuite URL of the instance
oAuth Callback URL - {instance URL}/api/eversign/oauth (ex. https://mustang.tasksuite.com/api/eversign/oauth)
Webhook URL - {instance URL}/api/eversign/callback (ex. https://mustang.tasksuite.com/api/eversign/callback)
App owner - regardless of whether or not we’re managing the Xodo Sign account, just select “App Owner (you)”.
Click on Save changes. Copy over these values to the E-sign Account on the TaskFlow/TaskSuite instance:
API Key - “API Access Key” above the Registered Apps section.
Client ID and Secret - the values listed on the new app you’ve just created.
Business ID - Also listed just above “Registered Apps”.
If the account you’re creating is meant for testing only check the “Sandbox Mode” checkbox. Signature Requests generated from this account will not have the option to be sent as anything other than a test request.
After clicking Save, click on the Authenticate button. This will take you to Eversign’s interface for authorizing TaskFlow. Click on “Allow” and you should be greeted by a message telling you “Successfully authenticated with Eversign.”
Creating e-sign documents
1. Navigate to the E-Sign Documents menu item.
2. Click on the Create button.
3. Select a provider account you have set up.
E-sign documents are provider-specific, i.e. you can not use the document configured for one provider on another.
4. Select the model that the document should be applied on. At the moment, you can choose between a Lead or a Loan.
5. Select the report type to link to this document. ODT Template refers to uploading your own .odt file and specifying the fields that are defined within it. This is the option you should generally choose. Pre-defined QWeb Template refers to an existing report template and can be used for testing purposes.
6. If you’ve selected ODT Template, the following section will appear:
Here, you should define the max amount of signers in the Max Signers field. Generally, this is the amount of signers you will need to sign the document. Some providers (such as Eversign) will allow you to submit less signers than indicated by the hidden tags.
If you’ve selected Pre-defined QWeb Template, you will need to select an ir.actions.report pre-configured report. You will not be able to define the hidden fields.
7. (Continued from selecting ODT Template) Click on the Add Field button to start defining fields.
The following options are available:
Signer No - The nth signer who needs to sign this field.
Type - The field type, which is dependent on provider.
Required - Whether or not the signer should be forced to fill in this field.
Field Height & Field Width - The field’s size (in pixels).
When selecting the field type as Text, the following extra fields will become available:
Placeholder - Hint text that will be removed as soon as the user starts typing.
Pre-Filled Value - Text to pre-fill (i.e. the signer will have to delete the text if they want to replace it).
Validation to Apply - Applies letters only, numbers only or email validation to the field, as selected.
Once you’ve finished setting up the field, click on the Create button and it will be added to the list along with its hidden field definition:
If you need to copy the hidden tags into your .odt file, click on the View Tags button to get a view of all of the fields.
8. Upload your file using the Upload ODT File button.
Signer types is a way to identify who signs for what ID, instead of needing to remember what ID signs which fields. Enable it by ticking the box and defining the signer names.
Note that you have to use technical, camel-cased names. Don’t use capital letters and use underscores instead of spaces.
11. Additional configuration options are available:
Communication Configurations - Text that will be displayed to the signers in the email communication they receive.
Requester Name - Name of the origin of the signature request.
Title - Title of the signature request.
Message - A custom message to display to the user along with the link to the provider.
Automation - Automated actions (ir.server) that can be linked to each event on the signature request.
Some events might trigger multiple times. This needs to be accounted for in your server action.
Event Notifications - which of the signature request events should send out a push notification to the TaskFlow web interface.
12. Save your changes by clicking on the Save button. In order to use this document, it must be in an active state first. To do this, simply click on the activate button.
Documents can be in 3 different states:
Draft - Document still in the process of being set up, not available for use.
Active - Document fully configured, available for use in signature requests.
Disabled - Document archived and not meant to be used at all. It can be sent back to draft and activated again.
Submitting signature requests
1. Select the Action dropdown on a Lead or Loan and find the e-signature option.
2. You will be greeted by this form:
Provider - The E-sign account.
Document - A pre-configured, active e-sign document template.
Sandbox Mode (Xodo Sign only) - If the account is configured to only use sandbox mode, you won’t be able to change this. Signature reuqests will not be legally binding and will be watermarked with a yellow “SANDBOX” background.
If the account is not explicitly set to this, you can choose to select it if you want to test a document.
Signers - The individuals who need to sign the document. You can either select a partner or simply type their name and email. The Type field is used to indicate whether or not the signer is required. If you’ve defined signer types for the document, the signer type’s name will be “pretty-ified” and shown on each line.
Recipients - Partners who will receive event notifications and emails whenever events occur. They can be signers as well, but do not need to sign the document by default.
The signature request’s creator will be a recipient by default. They will also receive TaskFlow notifications and emails from the provider when an event has occurred.
Depending on the client’s setup, the signers might auto-populate. Make sure you change the email address to your own if you’re testing!
3. If you want to see what the template looks like with our system fields rendered-in, click on Print Example. Note that this will not show signer fields.
Once you are done configuring the signature request, click on the Send button to submit it. The system will now navigate you to the created signature request instance.
Here, you can view the e-sign document again, go back to the lead, see the signers and recipients and view the events that has occurred on this signature request. Note that all events will be received from the chat application as well as through event popups in the upper right-hand corner. You can click on the colored text on chat messages to go back to the signature request.
You are able to cancel the signature request by clicking on the Cancel Signature Request button. Note that you can only cancel up until someone has signed the document, at which point the button will disappear.
Once everyone has signed the signature request, it will go into the Pending Download stage. From here, an automated server action will download the signed document from the provider after some time. Once it has been downloaded, recipients (and the signature request’s creator) will receive a notification.
Recipients can click on the signature request’s name in the chat application to navigate back to the signature request instance. Once the document has been downloaded, it can be viewed here:
Click on this link to download the completed file to your system:
Signature request events
Created - Signature request successfully created on the provider’s side.
Sent - The signature request has been sent to signers and recipients have been notified.
Viewed - A signer has viewed the document.
Signed - A signer has signed the document.
Pending Download - All signers have signed the document and the final document will be downloaded from the provider.
Done - All signers have signed and the finished document has been downloaded.
Declined - One of the signers has declined signing the document.
Failed - Due to a signer declining, not being reachable or some other reason, signing of the document has failed in its entirety.
Cancelled - Signature request cancelled by requestee.