Integrating External Application with Ephesoft Validation


Ephesoft allows its customers to develop external modules or applications and integrate them to work together with Ephesoft. This document gives in depth details on how to integrate external modules with Ephesoft’s Validation module.

External modules/applications are technology independent and can be written in any language HTML/JavaScript or GWT or JSP/Servlet or combination of both.

Review Validation Screen




There are shortcut keys as well as buttons defined to fire an External Application for a batch on the Review Validate UI. (App1, App2, App3, App4 as seen in the above screenshot)

When the shortcut key or the App button is pressed, the integrated application or module will be displayed in the Review Validation screen as Modal Window.

In the image below, the Right Hand side shows the image of the documents whereas the Left Hand side shows the integrated application/module.

External Application




IMPORTANT: batch.xml must be updated by the external application. Ephesoft simply loads the batch.xml.


Please follow the below steps to integrate external application with Ephesoft validation:

  • Let’s assume external application is available at http://localhost:8080/dcma/ExternalApp.html.
  • Login to the Ephesoft Admin Module (Batch Class Management).
  • Navigate to Batch Class -> Modules -> Review/Validate Document module -> Validate Document plugin.
  • Assign URL of the application (http://localhost:8080/dcma/ExternalApp.html) to one of the shortcuts, such as CTRL+8. It is possible to assign multiple applications to multiple shortcuts as shown below:




Closing the external application modal window:

As one can see in the screenshot of the External Application on the review-validate screen, there were two buttons present for closing the external application (earlier).

The OK button provided the functionality of refreshing and displaying refreshed content (on the review-validate screen) for the batch that has been modified through the external application.

The CLOSE button simply got back to the review-validate screen without refreshing the content of the batch, assuming that no changes have been made to the batch.xml by the external application.

The extra clicks that the user used to do in case of refreshing the screen or closing the pop up dialog window have been removed now.

Now both the functionalities (i.e. refreshing the screen after batch.xml updates or closing the pop up window without refreshing the Review Validate Screen) will be the implemented via third party applications. Ephesoft application provides a handle to the externally integrated applications by means of which both applications can communicate.

Ok and cancel buttons have been removed. External applications need to copy the below mentioned method in their code. External applications need to invoke this method on the respective button (ok or close) calls which it has implemented. External applications will signal Ephesoft to perform respective operations by passing the appropriate operation string in the method argument. Accepted operation strings are listed in the table below.

Method code for GWT based applications:
private native void fireEvent(String operation) /*-{,”*”);

Method code for Javascript based applications:
function fireEvent(var operation) {, “*”);

The action performed by us in accordance to the argument passed to this method in the external application’s code:


[table caption=”” width=”800″ colwidth=”20|100|50″ colalign=”left|left|center|left|right”]
Argument Passed by External application,Result on our application
“Save”,The dialog box containing the external application on the review-validate screen closes and the changes made in batch.xml get reflected on the screen(The functionality~~ previously provided by the OK button on the dialog box)
“Cancel”,The dialog box containing the external application on the review-validate screen closes without refreshing the RV screen. (The functionality previously provided by the CLOSE~~ button on the dialog box)
Any other string,No change (Dialog box will not disappear)



How to use the External Application:

It is expected that the external application would play around with the data contents of the documents (i.e. the batch) presently being displayed on the review validate screen. (For which the external app is fired)

Hence Ephesoft Application provides the external application the following two parameters appended in its URL, using which the external app can fetch/modify/delete the contents of the batch:

  • Path of the batch.xml for the current batch: The batch.xml contains the information regarding the batch. Ephesoft application provides the batch.xml path, which the external app can parse and play around with as and when it likes.

The parameter is specified in the URL by: “batch_xml_path”

Encoding of Batch xml path parameter:

The batch xml path is encoded using and UTF-8 encoding.


  • Document Identifier: The identifier of the document in focus is also passed onto the external application. The parameter is specified in the URL by: “document_id”

Sample URL fired for an external app by Ephesoft:

{Ext. App URL}&document_id={Document Identifier}&batch_xml_path={Path of batch.xml}&ticket={Security Token}


{Ext. App URL}?document_id={Document Identifier}&batch_xml_path={Path of batch.xml}&ticket={Security Token}


External Application and Security:

Ephesoft application generates a dynamic token for every External Application window which is opened via Ephesoft Application. This token is sent to the External App by appending another parameter “ticket” in the External App URL. Once this token is received by the External App, it can hit the below provided URL for checking the authenticity of the token. (Note: Please send the token as received by the application)

[ http://{EphesoftServerIP}:{port}/dcma/authenticate?ticket={ticket}]

Ephesoft Server in response will send a status code as to whether this ticket is valid or not:

Status Code 200 – Authorized

401 – Unauthorized

The token is issued as soon as the user opens the external application window. A valid token becomes invalid once:

  • Token has already been sent to the Ephesoft server for authentication.
  • One hour after this token has been issued.

Configuring the Title of External Applications through the admin UI

Ephesoft application has eliminated the Application URL from the title of External App Window. Title is now configurable through the Admin UI.