Transact

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

External Applications

This page provides information on how to integrate external applications with the Transact Review and Validation modules.

Important: Before proceeding, read and agree to the Developer Disclaimer.

Configuring an External Application

External applications are technology-independent and can be written in any language, such as HTML, JavaScript, GWT, JSP, Servlet, or a combination thereof.

Transact interacts with external applications by appending the application’s URL with the following two parameters:

  1. The path of the batch.xml for the current batch using the parameter “batch_xml_path”.
  2. The document identifier, using the parameter “document_id”.

The batch.xml path is encoded using java.net.URLEncoder and UTF-8 encoding. The following is a sample URL for an external application, as fired by Transact:

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

External applications need to include the following 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 Transact to perform a specified operation by passing the appropriate operation string in the method argument.

GWT-based applications:

private native void fireEvent(String operation) /*-{
window.top.postMessage(operation,”*”);
}-*/;

JavaScript-based applications:

function fireEvent(var operation) {window.top.postmessage(operation, "*");}

The following table describes the actions performed in Transact based on the arguments passed to this method in the external application’s code:

Argument Passed by External Application Result in Ephesoft Transact
Save The dialog box containing the external application on the Review and Validate screen closes and the changes made in batch.xml are reflected on the screen.
Cancel The dialog box containing the external application on the Review and Validate screen closes, without refreshing the screen.
Any other string No change.

Application Security

A dynamic token is generated each time an external application is called. This token is sent to the external application by appending the “ticket” parameter to the URL. Once this token is received, the external application checks the provided URL to determine the authenticity of the token.

Example URL:

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

Note: If the token is not valid, you will receive a 401 error message. A valid token becomes invalid in the following scenarios:

  • Once the token has already been sent to the Ephesoft server for authentication.
  • After an hour has passed since the token was issued.

Adding an External Application

Note: These steps describe how to add the application to the Validate module, but the same can be applied to the Review module if needed.

Perform the following steps to integrate your external application:

  1. From the Batch Class Management screen, select your batch class and click Open.
  2. Go to Modules > Validate Document > VALIDATE_DOCUMENT.
  3. Set the External Application Switch to ON.


Figure 1. External Application Switch

  1. Assign the URL of the application to one of the shortcuts, and add a title. This will be the shortcut used to access the application during validation. The available shortcuts are:
    • Ctrl + 4
    • Ctrl + 7
    • Ctrl + 8
    • Ctrl + 9


Figure 2. Shortcut and Title

Accessing the Application

From the Review or Validate screens, use your configured shortcut to call the external application. You can also call the application manually by clicking More > External Application and selecting your application from the list.


Figure 3. Open the Application

Your application will open in a dialog window.


Figure 4. External Application

Articles