Retrieve workflow history

Overview

This sample code will show the developer how to retrieve a certain document’s history in XML format from SigningHub.

Sample code

Use Case

Procurement processes can be complicated processes that requires sign off from multiple parties.

In order to analyse their process and discover where bottlenecks are, third-party applications can retrieve a document’s workflow history to analyse the document’s timeline.

Information like when the document was shared for the first time and the time and date when each Signer signed can be found in the workflow history.

Process flow

Retrieve workflow history process.

At a high level, the sample code will perform the following steps:

  1. Prepare the workflow.

  2. Share the document.

  3. Let Signer 1 sign the document.

  4. Retrieve workflow history.

Requests

Retrieve workflow history requests.

The following requests will create a new workflow on SigningHub, let the Signer sign the document through the API and then download the workflow history.

Step 1 – Authenticate owner

Overview

Authenticate to SigningHub.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.

 

Description

Authenticate to SigningHub, to start transacting with SigningHub.

The required parameters will be supplied by LAWtrust.

Contact LAWtrust sales to get access to the testing environment.

 

Parameters

The scope parameter tells the system who the Document Owner is. Use the email address of the Document Owner to identify the owner.

If this parameter is not set, the integration account used to authenticate to SigningHub will be considered to be the Document Owner.

 

Take note of the access_token returned by the server. The access_token will be needed in subsequent requests.

 

 

Step 2 – Add Package

Overview

Create a package to upload documents to.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1020.

 

Description

The first step to creating a workflow on SigningHub is to create a package. This step tells the system what the name of the pack is that you want to create.

 

A package can contain one or more documents.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

Take note of the package_id returned by the server. The package_id will be needed in the subsequent requests.

 

 

Step 3 – Upload document

Overview

Upload a document to the package created in the previous step.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1022.

 

Description

Upload the document that must be digitally signed to the system.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The document_id returned by the server will be needed in requests pertaining to the uploaded document.

 

 

Step 4 – Add Signer 1 to the workflow

Overview

Add a signer to the workflow.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1047.

 

Description

Add the name and email address of the person that must sign the document.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The package_id is obtained during Step 2 – Create Package.

 

Signing_order specifies the Signer’s order to sign. The order number will be required in the following steps. For the first signer, set the value to 1.

 

Set the field email_notification to false. Prevent SigningHub from sending a notification email to the user that they have a document to digitally sign.

 

 

Step 5 – Insert signature block 1

Overview

Draw a signature block for signer 1 on the document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1182.

 

Description

Add the name and email address of the first person that must sign the document.

 

Parameters

This request will draw a signature block on the document where the first signer’s signature must be placed.

 

This request will look for the text specified in the field search_text in the document and place the signature block on the document.

 

The field placement can be used to position the signature block relative to the search_text.

The size of the signature block can be controlled with the dimension field.

 

Order corresponds to the Signer’s order in which he / she must sign. Set the value to 1.

 

Take note of the field field_name returned from the server. The field name will be needed for Step 8 – Sign Signer 1.

 

 

Step 6 – Share document

Overview

Share document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1025.

 

Description

This request notifies SigningHub that the workflow configuration is complete and the signing workflow can start.

 

Parameters

N/A

 

 

Step 7 – Authenticate signer 1

Overview

Authenticate Signer 1 to SigningHub.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.

 

Description

For Signer 1 to sign the document, they must first by authenticated to SigningHub.

 

Parameters

Use the signer’s email address in the username field and the signer’s password in the password field.

 

The access_token will be required during the next step Step 8 - Sign Signer 1.

 

 

Step 8 – Sign Signer 1

Overview

Sign the document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1087.

 

Description

Signer 1 signs the document in the signature block that was drawn on the document during Step 5 – Insert signature block.

 

Parameters

For a full discussion of all the parameters in this call, please see the online documentation.

 

Use the access_token that was created during Step 7 – Authenticate signer 1.

 

Use the value from field_name that was created during Step 5 – Insert signature block.

 

Hand_signature_image: The image passed through in this field will be placed on the document in the field that is specified in the field_name. The image must be a base64 string.

 

User_name: The email address of the Signer.

 

User_password: The password of the Signer.

 

The values for username and password must the same as the ones used during Step 7 – Authenticate signer 1.

 

 

Step 9 – Finish workflow

Overview

Set the workflow status.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1132.

 

Description

This request will tell the system to move the workflow’s status forward. If the last Signer has digitally signed the document, the status will be set to ‘Completed’.

 

Parameters

N/A

 

 

Step 10 – Authenticate Integration Account

Overview

Authenticate the Integration Account so that the Document Owner can retrieve the history.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.

 

Description

Authenticate to SigningHub, to retrieve the workflow history.

Use the Integration Account’s credentials to log in.

 

Parameters

Take note of the access_token returned by the server. The access_token will be needed in subsequent requests.

 

 

Step 11 – Retrieve workflow history

Overview

Retrieve the workflow history details.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1044.

 

Description

The document workflow history details retrieves the workflow’s history.

 

Developers can use this request to periodically retrieve a document’s status.

 

The document status will be ‘Pending’ until all the Signers have digitally signed the document. After calling the document’s status will be ‘Completed’.

 

The action_type field can be used to determined which actions were signing actions and the field date_time can be used to determine when the signing took place.

 

Parameters

N/A