Versions Compared

Old Version 19

changes.mady.by.user Christoph Bimminger

Saved on

compared with

New Version 20

changes.mady.by.user Manuel Gierlinger

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section

Document Inbox

After the envelope is sent, the custom web app 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.

Info

Note if you want to cancel the settings:

Disable the beforeSendRedirectUrl in Settings-Organization. After all pending envelopes (drafts) have been sent, disable the OAuth Application (prevent log-in via this OAuth App). When disabling the OAuth App, existing drafts still contain the beforeSendRedirectUrl, so the OAuth Application should not be blocked before those drafts have been sent.

Application Flow – Callback Handler

After 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

Image Removed

Once done, the implementation should note down in the list of envelopeIds noted down above, that the processing was completed. Once completed, the callback handler implementation should delete the envelope from eSignAnyWhere.

Alternatively, a data retention job can be configured on the organization to perform an automatic cleanup (but then w/o checking if the documents are already stored in the DMS).For more information about server-side post-processing using callback handlers please see this story.

Section

Please see the following descriptions for the implementation in detail.

Number in the figureDescription
1eSignAnyWhere calls your CallbackHandler implementation when the envelope is finished (completed or cancelled).
2Your CallbackHandler stores the envelope ID in a persistent storage (disk, database) and replies with HTTP 200 on the HTTP request (1).
3A service implementation should permanently process the envelopes noted-down for processing.
4A service implementation will detect the noted-down envelope ID and process it as step by step queue processing.
5Some 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.
6It 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.
7The 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.
8After 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.



Section

Sample Implementation of the OAuth2 Code Grant Flow for the Tagging Scenario

A common situation is that the eSignAnyWhere user is redirected to a custom web application which should deal with the envelope sent before via eSignAnyWhere Web UI. To access the envelope via API, the custom web application must authenticate to the API with a user that has the permission to access the envelope.

While this was difficult in the past and often required to keep records of a mapping of envelopes to the creator, this got much simpler since eSignAnyWhere supports the OAuth2 Code Grant authentication flow. The user of the custom web application is asked to authenticate, via OAuth2, with the eSignAnyWhere user credentials. As a result, a code sharing between eSignAnyWhere and the custom web application is triggered and as a result the custom web application gets API credentials to access the envelope. During authentication, the user may choose the wrong user account on eSignAnyWhere – therefore it is required to check the permissions for the envelope, and redirect to the authentication again if the authentication provided does not have the required permissions.

Sample sequence diagram of a sample application we implemented for DMS tagging:

Note that the invocation of the tagging page cannot contain the "envelopeId" as HTTP GET parameter, as GET parameters are not allowed in the OAuth 2.0 redirect_uri. This is because the OAuth application configuration in eSignAnyWhere AdminWeb must already be whitelist the full URL including all parameters. Therefore, the sample application we implemented is encoding all GET arguments from first call into the “state” parameter of the authentication call. The redirect_uri is invoked with the state parameter, as specified in RFC 6749. So the state is used in that case to transport all the GET parameters.

The callback handler implementation also requires to know the API Token (Bearer Token) of the sender to retrieve signed documents, audit trail etc. – therefore the DMS Tagging Page implementation is already storing a mapping between envelopeId and senderUser and also a bearertoken of the senderUser in its persistent storage.

...