SigningHub allows digital signatures to be easily integrated into any website/app through simple API calls. This is the smart way of adding Advanced Electronic Signatures into a web application that ensures a seamless experience for the end users. 

SigningHub also facilitates multi-tenancy that enables an organisation to define custom signing policies for their external users (i.e. clients, partners, contractors, etc.). The external users are those recipients who are not a part of your enterprise.  They would be either part of another enterprise,  an individual user, or a guest (non-SigningHub registered user), and you require them to sign documents within a tightly integrated app environment. This feature is usually requested by the banks and financial institutions, who appreciate high-trust digital signing with tailor-made configurations to ensure a consistent signature style (appearance, details, etc.) for all users. For more details, visit Ascertia's Partner Portal for Configuration Guide.

You can integrate multiple web applications with your enterprise account. For details, see the Quick Integration guide and visit Ascertia's Partner Portal for API Guide.

With respect to security, and embedded iframes used by SigningHub for tight integration, the Integrations set-up allows you to specify the trusted domains of your business application.  When you supply input variables under "Allowed Domains" SigningHub will create the appropriate Internet headers when the iframe is called by the business application.  These are X-Frame-Options ALLOW-FROM for older browsers and CSP: frame-ancestors Header for the latest versions of Chrome for example. If you do not specify a value it will allow all parent domains to add this integration page in an iFrame.

 


Integrate a (third party) web application 

  1. Login with your enterprise admin credentials.
  2. Click your profile drop down menu (available at the top right corner).
  3. Click the "Enterprise Settings" option. 
  4. Click the "Integrations" option from the left menu.
  5. Click  from the grid header.



  1. A dialog will appear with four tabs to input API details as shown in the following image. Add the API configurations of integrating app in the Application, Settings, Webhooks, and Workflow Completion tabs as required. See the fields description of these tabs in the "Application Integration", "Integration Settings", "Webhooks Settings", and "Workflow Completion Settings" tables below.




 






  1. Click the "Save" button.


Application Integration

Fields

Description

Client ID

Field to specify the client ID (application name) to be integrated, i.e. SalesforseApp.

Call-back URL
  • In case of tight integration, specify the call-back URL where the users could be redirected when they close a document in the iframe. 
  • However for loose integration, specify a dummy URL to generate a Client Secret. As the call-back URL will not be required in the app configuration.

Client Secret

Click the "Generate" link after specifying client ID and call-back URL. This will create a unique client secret (API key) for this integration. By default, the generated client secret is displayed partially masked to comply with the GDPR policy.

  • Click  to view it completely.
  • Click  to copy the client secret to the clipboard.



Integration Settings

Fields

Description

Default Role For External Users

This field is related to multi-tenancy functionality, see visit Ascertia's Partner Portal for Configuration Guide.
Select a default role for all those users who don't belong to this enterprise, to make them use your custom signature settings. 

In this way when your enterprise document is shared with an external user through this integrated app, and they (external user) also sign it through this integrated app, SigningHub will supersede their personal/ enterprise signature settings with the ones defined in this role at the time of signing. 

The user roles can be managed from Enterprise Settings>Roles section.

Allowed Roles For Scope

This field is available if you want to define SigningHub roles, to restrict a Business Application from performing actions on behalf of users, that are members of these roles.

Clicking on this field will display a drop down containing all the configured roles of the enterprise. Select the pre-defined roles that you want to allow, multiple roles can be selected.

Leaving this filed blank will be considered as if no restriction has been applied i.e. The Business Application can perform actions on behalf of all the users of an enterprise.

Application Permissions for Scope

This field is available if you want to define a SigningHub role with specific permissions, enabling Business Applications to perform only the allowed actions on behalf of enterprise users.

Clicking on this field will display a drop down containing all the configured roles of the enterprise. Select the pre-defined role that you want to allow for performing actions. Only a single role can be selected, at a time.

Leaving this filed blank will be considered as if no role has been specified i.e. The Business Application can perform all actions on behalf of the enterprise users.

Hide Documents From Recipients

This field is related to multi-tenancy functionality and is used to hide your shared documents from the external users, visit Ascertia's Partner Portal for Configuration Guide. 
You can select any of the three options, i.e.:

  • None - this option will not hide documents from any recipient in a workflow. The external users will be able to view your enterprise documents that have been shared with them in their personal documents listing.
  • First - this option will hide documents from only the first recipient in a workflow. When a document is shared with the external users, SigningHub will not send any notification email to the first user (recipient). They can see and sign the shared document only by following the respective tight-integration link, as provided by the document owner. The shared documents will not be displayed even in the personal documents listing of the first user. 
  • All - this option will hide documents from all the recipients in a workflow. In this way, when a document is shared with the external users, SigningHub will not send any notification email to them. They can see and sign the shared document only by following the respective tight-integration links, as provided by their document owners. The shared documents will not be displayed even in the personal documents listings of external users. 

Allowed Domains 

Specify the domain(s) that are allowed to embed the Document Viewer within the iframe. Only the specified domains would be able to embed the Document Viewer within the iframe. 
Leaving this filed blank will allow all the domains to embed the Document Viewer.

Collapse document viewer's recipient and document panels by default

Check this checkbox to open the Document Viewer inside the tight integration screen with collapsed left and right (i.e. Documents and Recipients) panels. However, users can still open these panels by clicking their respective icons.

Keep this checkbox unchecked if there is no such requirement. The Document Viewer will open with the left and right panels intact.

Automatically redirect to call-back URL after task completion

Check this checkbox to automatically redirect a user to the call-back URL after they have performed signatures or In-person signatures. By default, this checkbox will be unchecked. 

Keep this checkbox unchecked if you do not want to have a user automatically redirected to the call-back URL. After the user has performed their task, they will stay on the document viewer screen and will not be redirected unless they press the "Close" button.
  1. This checkbox will only redirect users to the call-back URL, automatically, if the "Automatically proceed with workflow upon completion of mandatory actions by signer" checkbox is checked, under "Enterprise Settings>Roles>Document Settings".



Webhooks Settings

Fields

Description

Webhooks

Specify a callback URL where SigningHub could send the HTTP POST update of each workflow of the integrated application. This is useful in those cases where all the configured recipients don't necessarily need to process a document package to complete their workflow.
The workflow completion can be controlled by an external business application that could decide on need basis, whether to mark a document as complete or not after every major processing activity performed on it. 
When a URL is provided, this POST request provides the information of each workflow like:

  • Document Package
  • Document
  • Recipient
  • Action performed by the recipient on a document. 
  • State of the Workflow
  • Next signatories
  • Type of Workflow
  • State of the document 
  • Errors (Signing)
    SigningHub publishes an error webhook at the specified server URL for Go>Sign performed using the ADSS Server. These include:
    • The error that occurred when RUT is not configured.
    • The errors that occurred in Go>Sign Service and Go>Sign JS.



Check the below checkboxes for when you want the system to send a document processing report (XML) of the integrated application to the provided server address.

  • For document actions, when:
    • Shared
    • Signed
    • Declined
    • Reviewed
    • Meeting Host
    • Edited
    • Sent a Copy
    • Reminded
    • Recalled
    • Completed
    • Evidence Report is generated
    • Enterprise document is deleted


  • For user actions, when:
    • Registered
    • Updated
    • Deleted


  • For errors, when:
    • Signing


The business application can then use the respective SigningHub API call to inform SigningHub that a workflow is complete and hence no need to send this document to the remaining recipients.
Also while marking a workflow as complete, if any recipient of it has got this document in the "Pending" state, then SigningHub will delete the document from their inbox.
  1. Irrespective of the enterprise settings or the integration settings, the document processing report (XML) will only be sent if the "Send the document processing report (XML)" option is allowed, in post processing. By default, the "Send the document processing report (XML)" option will be allowed for all new workflows.


Workflow Completion Settings

Fields

Description

Workflow Completion

This area allows you to configure report routing of the integrated application upon workflow completion.

Send workflow completion report
Select to automatically post the workflow reports of the integrated application (in XML format) to the configured address when the workflow completes. This applies to all users within your integrated application. When enabled, the "Server URL" and "Add completed document in report" fields are displayed as shown in the image below.
  1. The availability of "Workflow completion report" feature is subject to your subscribed service plan. If you cannot find this option in your account, upgrade your service plan. 



Server URL
Select to specify the web server URL where the workflow completion reports of the integrated application are required to send. 

SigningHub gives you an option to publish Workflow Completion Reports along with the completed documents to a specific web server/URL. This configuration is at the integration level. The metadata and signed documents allow third party business applications to closely integrate with SigningHub and prevent the need to poll to check for complete status. For further details refer to "Publish Workflow Completion Report".
  1. ​In case the specified URL is invalid or inaccessible, SigningHub will send an email to the document owner upon workflow completion.


Add completed document
Check the "Add completed document" checkbox to receive the completed document along with the workflow completion report.
  1. If the document package contains a single document, its document type will be PDF in the workflow completion report (XML).
  2. If the document package contains multiple documents, their document type will be ZIP in the workflow completion report (XML).
  3. If both, the "Workflow completion report" and the "Add workflow evidence report (WER) in the report" checkboxes have been checked, their document type will be ZIP in the workflow completion report (XML).


Add workflow evidence report (WER)
Check the "Add workflow evidence report (WER)" checkbox to receive the workflow evidence report along with the workflow completion report; else, leave empty.
  1. The  "Add workflow evidence report (WER)" checkbox will only appear if the "Detailed with Workflow Evidence Report" option has been selected against "Workflow Evidence Recording" in the user's service plan.
  2. If only the "Add workflow evidence report (WER)", checkbox is checked, its document type will be PDF in the workflow completion report (XML).
  3. If both, the "Workflow completion report" and the "Add workflow evidence report (WER)" checkboxes have been checked, their document type will be ZIP in the workflow completion report (XML).




  1. The system will only send the webhooks and the workflow completion report, if both the document owner and the recipient belong to the same enterprise.
  2. The publishing behaviour of the system with respect to whether the webhooks and the workflow completion report have been configured in the document owner's enterprise settings, and in the integration settings of the recipient's enterprise, is as below:

Webhooks and the Workflow Completion Report are configured in the document owner's enterprise settings

Webhooks and the Workflow Completion Report are configured in the integration settings of the recipient's enterprise

System Behaviour Publishing Webhooks and the Workflow Completion Report

Configured

Configured
  • The integration settings of the recipient's enterprise will be followed.
  • The enterprise settings of the document owner's enterprise will be followed.

Configured

Not Configured
  • The enterprise settings of the document owner's enterprise will be followed.

Not Configured

Configured
  • The integration settings of the recipient's enterprise will be followed.

Not Configured

Not Configured
  • The system will not publish the Webhooks and the Workflow Completion Report.



Edit an integration instance

  1. Login with your enterprise admin credentials.
  2. Click your profile drop down menu (available at the top right corner).
  3. Click the "Enterprise Settings" option. 
  4. Click the "Integrations" option from the left menu. The instances of already integrated apps will be listed.
  5. Search/ move to the instance to edit and click  adjacent to it. The "Edit Application Details" dialog will appear.



  1. Edit the required content (i.e. Application Name, Call-back URL, or Default Authentication Method).
  2. Click the "Save" button.


Delete an integration instance 

  1. Login with your enterprise admin credentials.
  2. Click your profile drop down menu (available at the top right corner).
  3. Click the "Enterprise Settings" option. 
  4. Click the "Integrations" option from the left menu. The instances of already integrated apps will be listed.
  5. Select the instance(s) to delete and click  from the grid header.



The selected integration(s) will be deleted.
  1. In order to use the Single sign-on (SSO) facility in SigningHub, the "Default Authentication Method" must either be Microsoft Active Directory, Microsoft ADFS, SalesForce, or Microsoft Office 365.
  2. The external users are those document recipients who are not a part of your enterprise. They would either be part of another enterprise, an individual user, or guest non-SigningHub registered users, and you require them to sign documents within a tightly integrated app environment. 
  3. The availability of "Integrations" feature is subject to your subscribed service plan. If you cannot find this option in your account, upgrade your service plan.
  4. ClientID cannot be set as 'MobileSDK' or 'MSOfficeApp', since it has been preoccupied by the SigningHub application for it's Mobile version and MS Office App.


See Also