EngageOne™

 View Only

EngageOne® Compose Interactive Editor integration

  • 1.  EngageOne® Compose Interactive Editor integration

    Posted 04-02-2020 07:19
    Edited by Dariusz Prochownik 04-15-2020 10:10

    If you came here to learn how to integrate with the EngageOne® Compose Interactive Editor, you are on your way. However, before you start reading this article, it is worth reading my previous entry where I explained the architecture of the modules on which this solution is based. You can find it here.

    In this post I will focus on integration with web-based applications, which has been delivered as a new feature of EngageOne® Compose 4.4.9. The latest version 4.4.10 retains the architecture, so everything you've read about it is still true, but there have been some breakthroughs inside the communication protocol. Therefore, I encourage you to upgrade to the latest version of EngeageOne® Compose if you want to use the application for interactive editing.

    The sample application which demonstrates the below integration and more you can find in the distribution file: <EngageOne_Server_v4.4.x.zip>/samples/deliver-document.
    The official documentation on integration can be found here: https://www.pitneybowes.com/content/dam/support/software/product-documentation/public/engageone-server/v4-4-10/en-us/engageone-server-v4-4-10-editor-custom-integration-guide.pdf

    Pre-requirements

    Data source

    As you probably remember from my previous post, our new tool requires to work a Data Source Service which provides a RESTful web service. It is used by the editor as a source of a template data and all of its resources. This part of our system strictly depends on the structure of your system wich is about to integrate with us. That's why you have to implement this RESTful service yourself.

    If you have integrated with our previous ActiveX Editor component, which can be used as part of a website (Internet Explorer only) as well as part of a standalone Windows application, then you can use the current Data Source Service again without any modification.  

    However, if you need to implement the whole service from scratch, you can find helpful documentation: here (section: "2 - Integrating with EngageOne SOAP"/"Sample application"), and samples mentioned on the beginning of this post.

    Interactive Editor application

    The editor itself is a standalone window application to be installed on the end user's computer. The installation file is located in the distribution file: <EngageOne_Server_v4.4.x.zip>/utilities/InteractiveEditor/setup-engageone-interactive-editor-app.exe.

    Relay Service

    This is a service that is used by the Interactive Editor application and your system to communicate with each other. It is now built into the EngageOne server. If you already have the server installed and configured, you do not need to take any additional actions to start using Relay Service.

    Client library

    The Interactive Editor application and your system will communicate via a relay service using WebSocket. For this purpose, we have implemented our communication frames, whose description is not yet publicly available. For the time being, we are providing a TypeScript/JavaScript client library that you can use for communication.

    You can use a RequireJs compatible version from the sample application mentioned before, or you can compile it by yourself using the source code located in: <EngageOne_Server_v4.4.x.zip>/utilities/IeaClientSourceCode.

    To compile it from the source code you should:

    • Install NodeJs on your machine

    • Install the grunt library globally be executing commands:
      npm install -g grunt-cli
      npm install -g grunt
    • Download all the required libraries by executing command:
      npm install​

    • Modify the tsconfig.json and gruntfile.js files to the compiler "module" flag to one of the values:
      • AMD: to make the output compatible with the RequireJs library
      • System:to make the output compatible with the SystemJs library

    • Compile the source code using command: 
      grunt build​

    Client library initialization

    First, you need to load the JavaScript client library somewhere on your website. The way of loading depends on the library you have chosen before (RequireJs vs SystemJs).
    Next, you should create an instance of it and configure it. This is an example how you can do it using RequireJs library:
    requirejs(['iea/iea-service', 'iea/utils/iea-cookies'], function (ieaLib, ieaCookiesUtil) {
      var cookieUtil = new ieaCookiesUtil.IeaCookies()
      iea = new ieaLib.IeaService({
          webSocketAddress: 'wss://yourdomain.com:8080/relay-service/iea',					
          sessionId: generateUniqueSessionId(),
          cookies: cookieUtil.getEOAuthCookies(['securityCookieName', 'loadBalanceCookie']),
          keepAlive: 15,
          minIeaVersion: '4.4.10',
          windowTitle: 'IEA sample demo',      
          template: 'Some outstanding template',
          community: 'Sample',
          user: 'admin',
        }, 'en');
      ...	
    });


    As you can see on the above sample, you have to provide several parameters:

    • webSocketAddress (mandatory parameter)
      Relay Service address which you are about to use. If your EngageOne® Compose server is available at a URL: https://yourdomain.com:8080, the relay service address is: wss://yourdomain.com:8080/relay-service/iea.
      Please note that the WebSocket address prefix: "wss://", "ws://" depends on the SSL protection used on your server. If you access the server using the protocol "https://", use the prefix "wss://" in the relay service address. On the other hand, if you are using the simple "http://" protocol, you should use the "ws://" prefix.

    • sessionId (mandatory parameter)
      A string of characters which will be used to identify individual instances of the Interactive Editor Application and the Client Library during communication via the Relay Service.
      You have to make sure that it will be unique among all calls through the relay service. If not, you may cause a number of difficult to find errors caused by mixing messages sent between different instances of client libraries and editor applications.
    • cookies (optional parameter)
      A string of characters with all the cookies required by the Editor Application to connect to the Data Sources Service and download the required resources. If you've used the ActiveX Editor component in the past, you didn't have to worry about cookies, because ActiveX technology allowed the editor to access all sources of the website on which it was embedded.
      EngageOne® Compose Interactive Editor is a standalone application and has no access to website resources. Therefore, you must provide it with all the information required to authenticate to the Data Source Service or to maintain communication with the same Relay Service instance when using the load balancing mechanisms on the EngageOne® Compose Server.
      We created an additional library called "iea-cookies" which you can use to get a properly formatted string for the specified cookie names. We did use it in the above example.


    • keepAlive (optional parameter)
      When using a regular website and sending an HTTP request, the server is aware of the end user's activity, so it can maintain the current session. Similarly, when a user takes any action on a website, such as clicking on a button, the website is also aware of their activity and can take some action to keep the session alive. Unfortunately, while the user edits the template with an interactive editor, the website is not aware of this and the session may end. To prevent this from happening, the Interactive Editor Application, while the user is currently editing the template, sends a message to the website informing that the user is still active and the session should remain active. The KeepAlive parameter is the number of minutes that tells the Editor Application how often it should send such a message back to the website.


    • minIeaVersion (optional parameter)
      Since the Interactive Editor is being installed on the end user's computer and the website is stored on the server side, it is possible that the version of the editor on the user's machine will be outdated. To prevent that you can set a minimum supported version as a parameter. Each time the Interactive Editor is launched, it sends a handshake message to the website, which contains its version. If the integration library detects that the version is too low, it will close the Interactive Editor application and report an appropriate error.

    • connectionOpenTimeout (optional parameter)
      The number of seconds after which the Client Library should inform the end-user about the impossibility of establishing a connection with the Relay Service. This does not mean that the Client Library will not attempt to connect after such a time. It will do this, and when the connection is established, the connection error will be revoked. The idea of events implemented in the Relay Service will be discussed later.

    • ieaResponseTimeout (optional parameter)
      The number of seconds after which the Client Library should inform the end-user about the situation when it sent a message to the Relay Service and did not receive a reply. If the response arrives after this time, the error message will be revoked.

    • windowTitle (optional parameter)
      The window title to be displayed in the Editor window header

    • template (optional parameter)
      The template name to be displayed in the Editor window header

    • community (optional parameter)
      The community name to be displayed in the Editor window header

    • username (optional parameter)
      The user name to be displayed in the Editor window header

    Client library functions

    The JavaScript client library that we provide can broadcast several types of events. The basic idea is to use a stream of events, which can be subscribed or unsubscribed multiple times, instead of a singular Event Handler. 

    You can subscribe to event streams related to a specific action, such as loading a template into the Interactive Editor Application, or general event streams available at the client library level, such as the currently edited template status change.

    Loading a template

    In this example I will load a custom template in the Interactive Editor Application.

    requirejs(["iea/iea-service", "iea/utils/iea-cookies"], function (ieaLib, ieaCookiesUtil) {
      var iea = new ieaLib.IeaService({ ... }, 'en');
      ...
      var loadXmlData = '...';
      var subscription = iea
                           .sendExecuteLoadTemplateMessage(loadXmlData)
                           .subscribe(function (subscription, ieaLibInstance, status) {
        if (status.isSuccessful) {
          logMessage("The template has been loaded by the Editor application");
        } else {
          logError("The template has not been loaded");
        }
      });
    
      ...
    
      //if for any reason you would like to stop waiting till the template is being loaded
      subscription.unsubscribe()
    };
    As you can see, I didn't put the loadXmlData variable initialization here. It stores data in XML format used by the Editor to determine which template should be loaded etc. Its structure is the same as the XML that was passed to the ActiveX Editor control. You can read more about this in our documentation: here (section: Integrating the ActiveX editor in a custom application)

    Saving a template

    requirejs(["iea/iea-service", "iea/utils/iea-cookies"], function (ieaLib, ieaCookiesUtil) {
      var iea = new ieaLib.IeaService({ ... }, 'en');
      ...
      var saveXmlData = '...';
      var subscription = iea
                           .sendExecuteSaveTemplateMessage(saveXmlData)
                           .subscribe(function (subscription, ieaLibInstance, status) {
        if (status.isSuccessful) {
          logMessage("The template has been loaded by the Editor application");
        } else {
          logError("The template has not been loaded");
        }
      });
    
      ...
    
      //if for any reason you would like to stop waiting till the template is being saved
      subscription.unsubscribe()
    };

    As before, the structure of the saveXmlData variable value can be found in our documentation: here (section: Integrating the ActiveX editor in a custom application)

    Reaction on the template status change

    In the below example I do enable and disable a compose button whenever the template is loaded and has filled all of its mandatory fields (which means that it's completed) 
    requirejs(["iea/iea-service", "iea/utils/iea-cookies"], function (ieaLib, ieaCookiesUtil) {
      var iea = new ieaLib.IeaService({ ... }, 'en');
      ...
      var subscription = iea.onStatusChanged.subscribe(function (subscription, iea, isComplete, isModified) {
      logMessage("Edit status has been changed: isComplete == " + isComplete + ", isModified == " + isModified);
          var composeButton = document.getElementById("composeDocmentButton");
          if(isComplete) {						 
            composeButton.removeAttribute("disabled");
          } else {
            composeButton.setAttribute("disabled", "true");
          }
        }.bind(this));
    
      ...
    
      //if for any reason you would like to stop this subscription
      subscription.unsubscribe()
    });

    Handling an errors

    Before I show you an example of dealing with errors, you should be aware that there are two types of errors in our library. The first one is the errors that can simply happen, and the only thing we can do is to log it somewhere and display a message on the screen. The second one is errors that can be reported, but after a few seconds they can be revoked and you should hide it from the screen.

    For example: if the Client Library has problems with establishing a connection to the relay service, it will report this as a revokable error. If the connection is established after some time, it cancels the previous error because it is no longer relevant.

    requirejs(["iea/iea-service", "iea/utils/iea-cookies"], function (ieaLib, ieaCookiesUtil) {
      var iea = new ieaLib.IeaService({ ... }, 'en');
      ...
      var subscription = iea.onError.subscribe(function(subscription, iea, error) {
        if(error.isRevokable) {
          logError("Revokable error. Error code = " + error.code + ", message = '" + error.message + "'");
        } else if(error.revoke) {
          logError("The revokable error has been revoked. Revoked error code = " + error.code);
        } else {
          logError("Regular error. Error code = " + error.code + ", message = '" + error.message + "'");
        }
      }.bind(this));
    
      ...
    
      //if for any reason you would like to stop this subscription
      subscription.unsubscribe()
    });

    Final words

    I hope that the above description provides you with sufficient information to allow you to integrate your web browser base application with our EngageOne® Compose Interactive Editor.

    If you would like to see a working sample application you can find in the distribution file: <EngageOne_Server_v4.4.x.zip>/samples/deliver-document. It contains a demonstration of integration with the EngageOne® Compose Interactive Editor as well as an integration with the EngageOne® Compose ActiveX Editor component. If you are not interested in the ActiveX control than you can find most of the above samples in file: web/FileListIea.xhtml.

    If you would have any problems trying to implement some of the above example then you should read my next post. I will discuss most of the most common mistakes made during the integration process. A link to this will be available in one of my comments under this article.



    ------------------------------
    Dariusz Prochownik
    Knowledge Community Shared Account
    Shelton CT
    ------------------------------