View Only

EngageOne® Compose Interactive Editor architecture

  • 1.  EngageOne® Compose Interactive Editor architecture

    Posted 04-02-2020 06:53
    Edited by Dariusz Prochownik 04-02-2020 07:23

    In my previous post about the EngageOne® Compose Interactive Editor, which you can find here, I told you a little bit what it is and why we did create it. Now I'm going to put some flesh on it and explain how does this solution works.

    I will focus on integration with web-based applications, but if you want to use our editor with any other type of system, you will still find a lot of useful information here.

    Architecture elements

    The whole solution is made of elements:

    • Interactive Editor Application:
      It is a standalone windows application, installed on the end user's machine. You can think about it as a WYSIWYG editor (what you see is what you get) that allows users to fill in all available template fields in a user-friendly way. It shares its code base with the ActiveX Interactive Editor component, which we also share with our customers. This way both of them contains the same functionalities.

    • Template data source:
      REST service that provides template files and other necessary resources. If you already did an integration with the ActiveX Interactive Editor control, you will not need to do anything to make it compatible with the new EngageOne® Compose Interactive Editor, as both applications share their code base.

    • Integrated Application:
      Custom application integrated with our solution. We have a TypeScript/JavaScript library that you can use for easy integration with any web browser application.

    • Relay-Service:
      Service located on server side to provide an encrypted communication between EngageOne® Compose Interactive Editor and any integrated with it system. It is now built into the EngageOne® Compose Core bundle to simplify deployment, but has been designed as a self-contained module and can be separated as a standalone service in the future.


    Looking at the graph above, you probably thought: "why didn't they implement a simple straight communication between the editor and a custom integrated application, omitting the relay service".
    You were right, it would be much simpler but unfortunately, this is not possible due to SSL restrictions in web browsers and potential security problems.

    The explanation for the inquisitive:

    One of our requirements was to integrate a web browser-based application with our new editor. Such an application can potentially be secured by an SSL certificate. Some modern web browsers block any communication (HTTP, WebSockets, etc.) with services that do not provide SSL secure communication every time you open an SSL secured website.
    In this way, the web browser protects its users against the leakage of confidential data from secure websites by communicating with unsecured third party services.

    Providing such communication between the editor and a web page is still possible, but it would require making the editor an SSL server and storing the SSL private key on the end user's computer. In terms of our security policy, we cannot do this because we do not treat the end user's machine as a safe environment. If someone could steal a private key to an SSL certificate from it, they could launch a Men In The Middle attack against such a machine.

    By introducing the relay service we can provide a secure way of communication between the WYSIWG editor and any web browser, even when SSL protection is required. Please note that the relay service is located on the server-side, which is treated as a secure area, so we can make it an SSL server and install any SSL private key there if necessary.

    So how does it really works?

    When an application want's to use EngageOne® Compose Interactive Editor to fill in a template data, it has to:
    • generate a unique communication identifier (it will be explained later),
    • run the Editor and pass to it the above identifier.

    To run a standalone Windows application from a web browser, we use the Custom Protocol Handler mechanism, which is built into the Windows operating system and available on all modern web browsers. In short, when our new editor is installed on the end user's computer, we also register a custom protocol called "pbiea" in the background and connect the editor's application to it. Whenever a web browser is redirected to a URL starting with "pbiea://...", it starts the application associated with the "pbiea" protocol and passes all parameters from the URL to it. This way we can run the editor app and pass to it the unique identifier.

    Then both the editor and the application integrated with it (in our case the website) must connect to the relay service using the WebSocket protocol. Please note that these connections are like fish in the ocean of thousands of possible other connections processed by the relay service. We have to somehow inform the relay service that these two particular instances has to communicate to each other. This is what the unique identifier, generated in the first step and shared between the editor and the web page is being used for.

    Now the relay service can mediate communication between the website and the editor, who can inform each other about the need to open a given template, about the fact that it has been completed or about the need to finish the editor, etc. This communication is stateful, which means that if you connect to a specific relay service server, you must continue sending messages to the same server instance. This is particularly important if you are using load balancing mechanisms on the EngageOne® Compose Server.

    We did choose the WebSocket protocol over the HTTP, because it provides us an information whenever the connection is alive or has been broken. This way we can react on a situation when the web browser process has been terminated by the user or by some kind of its internal exception. For example, when the web browser has crashed, the relay service can detect this and inform the editing application that it should close because no one can consume its work.​

    Now that you understand how our system is built, we can go further and show you how to integrate your application with the EngageOne® Compose Interactive Editor. I will discuss the details of this process in my next article which you can find here.


    Dariusz Prochownik
    Knowledge Community Shared Account
    Shelton CT