...
Section |
---|
The document tagging story You want to save your files and find them again straight away? With DMS tagging you can add metadata so that you can save your documents and envelopes with additional data and thus you can more easily assign and find them. The DMS Tagging integration scenario explains how to integrate a custom tagging page (e.g. aligned with the data structures from your DMS / ECM) into eSignAnyWhere, and how to use this data for later upload (with tagging) to the DMS/ECM solution. This story includes the following:
We recommend to read the story "Retrieving the User API Token via OAuth" before continuing with this story. Application Flow – TaggingYou can define the envelope as usual, with the eSignAnyWhere WebUI envelope creater. After the recipients page and the designer page, the sender will see the summary page of eSignAnyWhere. In the summary page, instead of the “SEND” button, the sender will see a “NEXT” button because a “before-send redirect url” was configured. Following placeholders are available for the “before-send redirect url” :
When the sender clicks the “NEXT” button on the summary page, he/she is redirected to the configured before-send redirect page. This page, for example can allow to modify the envelope before sending. Therefore, the page is collecting the DMS Tagging metadata in a custom HTML form, and will set the data as metaDataXML into the envelope. On the authorization page, the OAuth 2.0 code grant flow is implemented, and therefore the user is asked, if not permissions have been granted for the application so far, to authenticate with username and password (but the username/password check is bypassed when an active eSignAnyWhere session is already open) and then the user is asked to grant permission for the custom web application to access the API. After successful authorization, the user is redirected back to the custom web application . More details about the underlying OAuth2 Code Grand Flow and its implementation are documented in the chapter. for the document tagging. Now the authentication check is passed, and the user gets the DMS Tagging form presented. After he/she enters the data, the form action is calling the custom web application’s back-end with the form data provided. The back-end will update the envelope (draft) data by adding the metadata, and will the send the envelope based on the draft. Afterwards, the user is redirected to the eSignAnyWhere documents inbox. Please see the The next figure which shows a the process flow in more detail: |
Section |
---|
Section |
---|
This flow will be represented to the user in the following screens: Recipients PageIn the recipients page, the sender selects documents to be signed, and defines the recipients and workflow. This is standard eSignAnyWhere functionality. |
Section |
---|
Designer PageIn the designer page, the sender may define or add form fields, signature fields and predefined annotation fields. This is standard eSignAnyWhere functionality. |
Section |
---|
Summary PageIn the summary page, the sender may adjust some envelope settings such as notifications/reminders. |
Section |
---|
Authorization RequestThen the user is redirected to the configured redirect page. Before the tagging page is shown, the user may be asked to login (which is usually skipped because the user’s session is already active), and on first usage the app asks for permissions to grant API access. The authentication page is implemented as part of the eSignAnyWhere product, but the custom page must return with an HTTP Redirect to that authorization page when authorization is unknown or invalid. The names shown in the custom tagging page are part of the configuration of the eSignAnyWhere OAuth Application, so configured centrally per instance in the AdminWeb. Details of this authentication are well described in the story "Retrieving the User API Token via OAuth". |
Section |
---|
Custom Tagging PageThis page is fully implemented in the custom web application for DMS tagging. The fact that it looks like the eSignAnyWhere Web UI is just because it was implemented that in a sample code. This is purely part of the custom DMS tagging sample. In a simple webform, this can look like: |
Section |
---|
Serverside handling of Form Data
After clicking the "Send Envelope" button in the custom tagging page, notify the backend of the tagging page implementation (also called "BeforeSendRedirectPage") and let the backend do the following with the retrieved form data:
Update Metadata in Draft
Set the data collected via the form e.g. in draft metadata section, to make these data available for the later callback processing
This will make the data available for pushing the signed documents to the document management system (DMS)
POST /v6/draft/update
Code Block | ||||
---|---|---|---|---|
| ||||
{
"DraftId": "...",
"MetaData": "..."
} |
Send Envelope
While being on the BeforeSendRedirectPage, we are still working on a draft. There was no envelope sent yet. To send the envelope, we use an API method for the transition from draft to envelope:
POST /v6/draft/send
Code Block | ||||
---|---|---|---|---|
| ||||
{
"DraftId": "..."
} |
Section | ||
---|---|---|
Document InboxAfter the envelope is sent, the custom web app is redirecting should redirect to the eSignAnyWhere document inbox. This is standard eSignAnyWhere functionality; the custom web application just needs to redirect to that page once done.
Application Flow – Callback HandlerAfter the callback for finished envelope was received, the callback handler should check if it was a completed action. The handler has to retrieve the envelope ID from the HTTP GET parameters. Then, the callback handler should note down the envelope ID in a persisted storage for further processing and return with an HTTP 200 (success) to indicate the archiving request was noted down. |
Section |
---|
For more information about server-side post-processing using callback handlers please see this story. |
Section | |
---|---|
Sample Implementation of the OAuth2 Code Grant Flow for the Tagging Scenario | |
Section | |
Please see the following descriptions for the implementation in detail. | |
Number in the figure | Description |
1 | eSignAnyWhere calls your CallbackHandler implementation when the envelope is finished (completed or cancelled). |
2 | Your CallbackHandler stores the envelope ID in a persistent storage (disk, database) and replies with HTTP 200 on the HTTP request (1). |
3 | A service implementation should permanently process the envelopes noted-down for processing. |
4 | A service implementation will detect the noted-down envelope ID and process it as step by step queue processing. |
5 | Some implementations may require a user determination service to identify which user sent an envelope, because only this user can access the envelope in step (6). In combination with the DMS tagging page (which is using OAuth Code Grant flow), the DMS tagging already noted down for each envelope which user (apiToken / Bearer Token) was involved in sending the envelope, so in this combination it is not required to have such a user determination service installed. It is also not part of the product, so we recommend to avoid it. |
6 | It should call the REST API call GET envelope/{envelopeId} to receive details about the envelope, including metaDataXml which was set by the DMS tagging application, and receive document IDs for the relevant documents. |
7 | The documents, which are typically the signed PDFs, the Audit Trail PDFs, and in addition the legal documents (such as the CA22D certificate request form for disposable certificates) should be downloaded form eSignAnyWhere via API. |
8 | After that, the application should upload the documents to the external DMS via the DMS API according to the requirements of the DMS; and use the tagging retrieved from the metadata. |