{"id":31686,"date":"2018-01-09T16:03:16","date_gmt":"2018-01-10T00:03:16","guid":{"rendered":"https:\/\/ephesoft.com\/docs\/2019-1-2\/developers\/external-applications\/"},"modified":"2021-02-18T11:25:49","modified_gmt":"2021-02-18T18:25:49","slug":"external-applications","status":"publish","type":"docs","link":"https:\/\/ephesoft.com\/docs\/products\/transact\/developers\/external-applications\/","title":{"rendered":"External Applications"},"content":{"rendered":"

This page provides information on how to integrate external applications with the Transact Review<\/strong> and Validation<\/strong> modules.<\/p>\n

Important: <\/strong>Before proceeding, read and agree to the Developer Disclaimer<\/a>.<\/p>\n

<\/a>Configuring an External Application<\/h2>\n

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

Transact interacts with external applications by appending the application\u2019s URL with the following two parameters:<\/p>\n

    \n
  1. The path of the batch.xml <\/strong>for the current batch using the parameter \u201cbatch_xml_path\u201d.<\/li>\n
  2. The document identifier, using the parameter \u201cdocument_id\u201d.<\/li>\n<\/ol>\n

    The batch.xml <\/strong>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:<\/p>\n

    {Ext. App URL}&document_id={Document Identifier}&batch_xml_path={Path of batch.xml}&ticket={Security Token}<\/em><\/p>\n

    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.<\/p>\n

    GWT-based applications:<\/strong><\/p>\n

    private native void fireEvent(String operation) \/*-{\r\nwindow.top.postMessage(operation,\u201d*\u201d);\r\n}-*\/;<\/pre>\n
    JavaScript-based applications:<\/strong><\/p>\n
    function fireEvent(var operation) {window.top.postmessage(operation, \"*\");}<\/pre>\n
    The following table describes the actions performed in Transact based on the arguments passed to this method in the external application’s code:<\/p>\n\n\n\n\n\n\n
    Argument Passed by External Application<\/strong><\/td>\nResult in Ephesoft Transact<\/strong><\/td>\n<\/tr>\n
    Save<\/td>\nThe dialog box containing the external application on the Review and Validate screen closes and the changes made in batch.xml<\/strong> are reflected on the screen.<\/td>\n<\/tr>\n
    Cancel<\/td>\nThe dialog box containing the external application on the Review and Validate screen closes, without refreshing the screen.<\/td>\n<\/tr>\n
    Any other string<\/td>\nNo change.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    <\/a>Application Security<\/h3>\n
    A dynamic token is generated each time an external application is called. This token is sent to the external application by appending the \u201cticket\u201d parameter to the URL. Once this token is received, the external application checks the provided URL to determine the authenticity of the token.<\/p>\n
    Example URL:<\/p>\n
    http:\/\/{EphesoftServerIP}:{port}\/dcma\/authenticate?ticket={ticket}<\/p>\n
    Note: <\/strong>If the token is not valid, you will receive a 401 error message. A valid token becomes invalid in the following scenarios:<\/p>\n