How can I setup a workflow to use the Validated ID Signature Service?
Please follow the instructions below to setup your DocuWare system to use the Validated ID Signature service.
Step 1: Register organization with the Validated ID Signature Service:
To register for a production token, use this web page. We will be asked to log into Validated ID and should use the credentials for the Validated ID account that we would like to have enabled with our signature service to connect to Validated ID on their behalf.
Once we have successfully logged into Validated ID, we will be redirected to the registration page, as seen below. Here, enter your organization, DocuWare URL and provide a DocuWare user name and password. Additionally, we must provide a valid email address where the token will be emailed to. You will see some information about your Validated ID account, including the subscription type and the ID of the user they logged in as in the previous step.
If all information is correct, the registration will be completed and we will shortly receive an email with the token issued for your organization.
Step 2: Add DocuWare Signature Service as Web Service:
Before configuring a workflow with Validated ID, we need to add Validated ID to the available web services in DocuWare Configuration:
Step 3: Configuring the signature workflow
The following procedure describes how the document in the workflow is sent to Validated ID for signing and retrieved back:
- Trigger condition happens on a document
- The DocuWare Signature Service only supports PDFs – the document is converted as needed.
- Document is sent to the Validated ID web application
- The user opens an email and hits a button that sends them to Validated ID, where they can review the document
- The user may need to meet certain authentication requirements (Access Code, Phone, SMS or Knowledge Based Authentication). Then, they can sign the document
- The Validated ID application calls our service and notifies DocuWare that the document was signed.
- DocuWare retrieves the document that has been updated with a signature, both in the metadata and by placing an image of the signature in a specific location of the document.
- The signed version of the document can either replace the original document or be clipped to the original document. In addition, an index field is updated with a specific value. This value can be a trigger condition for another workflow, for example.
The specifics of the workflow will depend on the use case we are fulfilling. Applying a signature to a workflow document requires two workflow activities: "Assign data" and "Web service".
First step is applying the workflow activity “Assign data”. The purpose of this step is to create global variables for all the parameters, then assign pieces of data to them for use in calling the web service. It’s recommended to name the global variables the same as the parameter they are intended to represent.
For details and parameters see the following;
This is based on the AddNewDocumentRemote method:
- FileCabinetId (string) – GUID of the file cabinet with the document
- DocId (string) - ID of the document to be signed
- Token (string) – token received in the registration step that identifies the customer organization and provides user credentials
- SignerName – name of the person signing the document
- SignerEmail – email address of the signer of the document
- SectionNumber (int) – index of the section within the document to be signed
-1 indicates the last section found.
0 or 1 will be the first section.
An error will occur if a section is specified that doesn’t exist.
- AnchorText (string) – This is the piece of text the service can look for on the document. If specified and not found, an error will occur. If not specified, then the subsequent location information will be absolute, rather than relative to finding a piece of text.
- AnchorTextOccurrence – Which occurrence of the anchor text should be used to be the starting location for placing the signature
-1 is the last occurrence.
0 or 1 is the first.
Any other number is a specific occurrence.
- PageNumber (int) – page number within the file to start looking for the anchor text. -1 indicates to look on the last page. If no anchor text is specified, it is the absolute page number.
- SizeX (int) – size in millimeters of the width of the signature image
- SizeY (int) – size in millimeters of the height of the signature image
- PositionX (int) – Relative to the left side of the anchor text, this is the horizontal location of the signature image to be placed on the document (millimeters again). Positive numbers are to the right. Negative numbers are to the left.
- PositionY (int) – Relative to the top of the anchor text, this is the vertical location of the signature image to be placed on the document (millimeters again). Positive numbers are down. Negative numbers are up.
- SuccessStatusField (string) – This identifies a file cabinet field on the document that will be updated when a document is signed or rejected by the user in Validated ID.
- SuccessStatusValue (string) – This provides the value to be set in the above field when a document is signed.
- FailureStatusValue (string) – This provides a value to be set in the above field when a document is rejected by the user in Validated ID
- DateSignedFieldName (string) – This is an optional parameter that may be used to provide the name of a file cabinet field to hold the date the document was signed. When signed, we will update this field with the date it was signed by the user in Validated ID.
- PostSigningAction (string) – this specifies what is to be done with the signed document after the user signs it in Validated ID. The choices are “ClipBefore”, “ClipAfter” and “Replace”.
- IssuerName (string) – Display name used for the sender of the email and in the contents of the email message. If this value is left empty, it will default to the organization name.
- EmailSubject (string) – subject of the email
- EmailMessage (string) – text that is displayed in the contents of the email
- EmailLanguage (string) - Language that the email will be displayed in as well as the page where the signing process occurs. If this value is left empty, it will set default to en (English). Valid values are: ca, en, es, de, fr. These values correspond to Catalan, English, Spanish, German, and French respectively.
- DaysBeforeExpiration (int) - if the value provided is greater than 0, there will be a time limit of this number of days before the document expires. If the time limit is passed, the document will be considered declined. It will be deleted from the VidSigner service and the signer will no longer be able to sign it.
- SendSignedDocument (boolean) - if this parameter is set to true, the signer will receive a copy of the PDF they signed after they complete
- SignerID (string) - This parameter is required when using the centralized signature product from VIDSigner. In most cases, it will be a passport number. When using this parameter for Biometric or Remote Signature, it is optional
These three pieces of signer information determine who is being asked to sign the document in VIDsigner. If these pieces of information are incorrect, the user will not be able to review and sign the document in VIDsigner.
- IncludeReport (boolean) - this parameter is optional but if provided must have a value of ‘true’ or ‘false’. Setting it to true will append a second PDF to the document after the signed document. This PDF has information regarding the signer and the digital certificate that was added to the document.
- RejectionReasonFieldName (string) - Optional. This parameter will specify an index field on the document that must be a character field. When the user declines to sign the document, the VidSigner application will ask them to provide a reason. If they decline to sign and enter a reason, the text they enter will be placed in this field.
- ReminderFrequencyHours (int) - a reminder can be sent to the signer to sign the document if it remains unsigned. This value will determine how often the reminder will be sent.
- ReminderMaxRetries (int) - this value determines how many times a signer will be reminded if a document remains unsigned.
- RecipientAuthenticationType (string) – This allows the workflow to specify what type of Validated ID authentication is required to allow a signer to sign a document. Valid values are “None”, “AccessCode”, ”Phone”, ”SMS”, ”KBA”
- SignerPhoneNumber (string) – phone number used for two-factor authentication (use international phone number format, ex. +18455639045) during the signing process. Required for SMS authentication.
- RecipientMayProvideNumber (Boolean) – Only for Phone authentication. If set to true, it ignores any value the user sets in the phone number. Then, at the time of signing the signer can provide the number to be called to receive the code by entering it in the Validated ID application.
In a Web Service activity, select the web service configured for Validated ID. If you don’t see the signature service, configure it there and return to this step. Then, select the proper service method you wish to implement.
Now, in "Parameters", select the global variables we created for each parameter.
We may also choose to use the result parameters. These can be set to global variables and are used to decide the next step in your workflow. For example, if the “Success” result of the web service (found in the success Boolean) is false, we may want to take a different path than if the result is true.
Once these changes have been made, please proceed to save and publish the workflow, then you'll be set to use the Validated ID Signature Service.
KBA applicable for both Cloud and On-premise Organizations