1. Home
  2. Transact
  3. Developer Documentation
  4. External Applications

External Applications

Integrating External Applications with Ephesoft Validation

Ephesoft allows its customers to develop external modules or applications and integrate them to work together with Ephesoft. This section 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/Servelt or combination of both.

Integrated application or module will be displayed in the Review Validation screen as Modal Window. The Right Hand shows the image of the documents where as Left Hand shows the integrated application/module.

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. (App 1, App4, App2, App 3 as can be seen in the above UI)

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. On the click of OK button, Ephesoft simply loads the updated batch.xml.

Follow below steps to for module integration:

1. Let’s assume your application is available at http://localhost:8080/dcma/ExternalApp.html.

2. Login to the Ephesoft Admin Module (Batch Class Management).

3. Navigate to Batch Class -> Modules -> Validate Document module -> Validate Document plugin.

4. 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 you can see below:


Closing the external application modal window:

As you 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 goes 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.

Now we have removed the extra click that the user has to do in case of refreshing the screen or closing the pop updialog window.

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. We have provided a handle to the externally integrated applications by means of which they can communicate with the Ephesoft Application.

We have removed the ok and close buttons. External applications need to copy the below mentioned method in their code. They need to invoke this method on the respective button (ok or close) calls which they have 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:

Argument Passed by External applicationResult 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 thescreen(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 stringNo 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 we provide 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. We provide 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:

We are generating 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.


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

We have eliminated the Application URL from the title of External App Window. Title is now configurable through the Admin UI.

Was this article helpful to you? Yes No