HTTPS and Command Line ESA Types
Two communication styles are currently supported between third-party ESAs and sync core subsystems for exchanging XML messages:
- Command-line (CL) standard input/output (STDIO)
In both cases, the same XML messages are passed back and forth, and the ESA operation semantics are identical. However, the ESA implementations themselves could be quite different.
Note: The ESA Remote Proxy bundled with the Agiloft application converts the command-line ESA into an HTTPS ESA, thus allowing the command-line ESA to run remotely over HTTPS.
Both the CL and HTTPS approaches are quite versatile and both allow for implementations of the ESA in any language using any technique. There are two implementation styles because external systems can be very different and, depending on particulars, one ESA might be easier to implement than the other. For example, if your system is a Windows application and you need to call its Common Object Model (COM) interfaces, a CL ESA would be easier to implement. Since the ESA application is automatically launched by Agiloft when needed, you don't need to write a continually-running Agiloft polling service. The application is quite straightforward in that case: receive the call from the Agiloft sync core, and then do the necessary calls on the COM interfaces. By contrast, if your system is of a client-server type, such as a J2EE server, it might be more natural to implement an HTTPS ESA. This could run on the server side, where you can directly access your back end.
XML message syntax and semantics are the same for both CL and HTTPS ESA types.
This table illustrates some differences between HTTPS and CL ESA:
|HTTPS ESA||CL ESA|
|Life cycle is not under the control of the Agiloft||Automatically launched when needed|
|Actively polls for messages||Just reads messages from its standard input|
|Usually an internal part of your system||A separate executable which usually connects to your system|
|Often remote||Needs a special Remote Proxy application that is shipped with Agiloft in order to be remote|
If you plan on implementing an ESA using Java, you can make use of the support library bundled with the ESA example which handles all communication details like parsing, generating XML, exchanging XML messages with the
Agiloft sync subsystem and so on. All you need to do is provide a single Java interface
ExternalSystemAdapter and modify the main
JavaExecutableEsa class provided in the example. This will result in a ready-to-go CL ESA application. If you are implementing an HTTPS ESA, see Java ESA Development for more information on the methods that will be called.
An HTTPS ESA is a separate application which runs independently of Agiloft's control; either remotely or co-located on the Agiloft server. It continually polls the Agiloft sync subsystem core for new messages and will stay in a pending state until a synchronization is to be run. The HTTPS ESA exchanges XML messages in a REST-like manner as shown in this table:
|GET https://<ewserver:port>/gui2/sync/connect?extsysid=<external system id>&acceptssync=true|
Connects to Agiloft sync subsystem, ready to perform synchronizations defined by the sync configuration with <external system id> external system ID.Response contains the connection ID
|GET https://<ewserver:port>/gui2/sync/message?connid=<connection id>|
Gets next message to the ESA
Response contains the XML message to be processed by the ESA
Posts messages to the Agiloft sync subsystemThis is used to post replies back to the sync core or to call sync core functions
|GET https://<ewserver:port>/gui2/sync/disconnect?connid=<connection id>||Disconnects from sync subsystem|
The communication cycle is basically a sequence composed of
HTTPS ESAs are usually remote, though this is not a requirement, and their lifecycles are fully independent of the Agiloft server. They are just considered to be running externally and to be polling the Agiloft sync subsystem for new messages at prescribed intervals. If a synchronization is started, it will stay pending until the HTTPS ESA connects and receives sync messages.
If you write server-side software, an HTTPS ESA would generally be the best option. It uses a blocking poll approach, which means that GET requests are blocked on the Agiloft server until a message is ready for the ESA or a timeout occurs.
An HTTPS ESA needs two parameters before connecting to the Agiloft sync subsystem:
- The Agiloftserver name to connect to
- The external system ID identifying a particular data set - the Agiloft knowledgebase and its particular sync configuration - to be synchronized with
Because these parameters are required before connecting to the Agiloft sync subsystem, the ESA parameters mechanism is not applicable and the parameters should be provided beforehand for the ESA separately. Usually, they are identifiable within the settings of your system.
HTTPS URLs and Transport Types
This type of message transport does not require the ESA to be an application executable by command, and is adapted for Internet communication.
There are 3 URLs used for HTTP transport. If the Agiloft GUI runs at https://www.example.com/gui2, these URLs will be: https://www.example.com/gui2/sync/connect, https://www.example.com/gui2/sync/disconnect, https://www.example.com/gui2/sync/message.
Every request to any URL must contain an extsysid=<externalSystemID> parameter, where <externalSystemID> matches the external system ID field in the Sync Configuration.
Important: A third-party ESA, using HTTP transport must be aware of its externalSystemID.
HTTP response codes should always be examined to check whether transportation was successful. All parameters – GET and POST – should always be URL-encoded. Character encoding is UTF-8.
Connect and disconnect URLs should be accessed when the ESA is about to start/stop receiving messages. These requests don't have any other parameters. The HTTP response to connect will be an externalSystemID value passed in the HTTP request. The ESA may check this in addition to the HTTP response code to ensure it has connected successfully.
The message URL can be accessed via a GET HTTP request to get the next message or via a POST HTTPs request to send a message. When GETting message, the XML message is returned as a HTTPs response. When POSTing, the message should be passed as the message HTTPs form parameter.
The typical ESA cycle for using HTTPs transport is:
- GET /sync/connect
- GET /sync/message
- Process the message.
- POST /sync/message
- If the message was not Release, goto 2
- GET /sync/disconnect
- Wait for some period of time. The Sync Configuration setting Polling Period is accessible as the
config.pollperiodparameter which you may request from within sync cycle 1-6. Goto 1
HTTPs transport does not limit the way the ESA is actually implemented. It can be a command-line application, a service, a component within an application server, etc.
Starting and stopping this application and the exact mechanism by which the ESA obtains the external system ID value are outside the scope of this spec, but typically the application is installed just like any other piece of software and reads the ID from a command line parameter or configuration file.
Command Line STDIO
A Command Line ESA (CL ESA) is a command line application, which reads incoming messages from standard input and prints response messages on the standard output. The Command Line ESA application is automatically launched by Agiloft when necessary.
This type of third-party ESA uses standard input and output streams, stdio. In this case, the ESA developer provides his ESA as an executable, command-line application. It need not be a compiled native application; it could even be a script. The two requirements are:
- It must be runnable always using the same command-line
- It will not print anything except XML Sync messages to the standard output
A CL ESA is often easier to write because it doesn't require an always-running server. A CL ESA uses a standard IO (STDIO) interface to exchange XML messages with the Agiloft sync subsystem. XML messages from sync are written to the ESA application Standard Input (STDIN) and responses are read from the application's Standard Output (STDOUT).
The following example demonstrates how a manual CL ESA could look, including the console text and the sample ESA application response:
For more information, see ESA XML message schema.
There is a parser and a serializer provided with the Java support library, so you should only need the raw scheme if you are developing an ESA without them.
Although the XML standard says little about line breaks, standard console I/O is line-based. To handle this difference, every <sync> and </sync> tag which delimit all XML syncn messages must be placed on a line of its own.
The typical ESA cycle using STDIO transport is
- Read message, using standard input:
- Read line. This must always be the XML declaration -
- Read line. This must always be <sync>
- Read and accumulate all lines before getting </sync> line.
- Parse what was read as XML message
- Read line. This must always be the XML declaration -
- Process message.
- Write response using standard output
- Write XML declaration
- Write <sync> line.
- Write XML message body - a <call> or <result> element.
- Write </sync> line.
- If the message was NOT release, goto 1.
For ESA's using STDIO, Sync is responsible for starting the ESA application when necessary.
A CL ESA is usually easier to write, but it is often desirable to run an ESA remotely. Since this is not directly possible with CL applications,
Agiloft supplies a small application called the Remote Proxy which converts a CL ESA into an HTTPS ESA. The Remote Proxy is a Java Jar file which can be downloaded by clicking the Download ESA Remote Proxy button from the Sync Configuration screen. The downloaded
esa.jar file will contain both the Remote Proxy code and a settings file which references the sync configuration, namely the
Agiloft server name and external system ID of the configuration which were created via the sync GUI. It should then be run in standard Java on the machine of your choice to start polling the
Agiloft sync subsystem.
To run the Remote Proxy on an external system host, you should:
- Download and install the latest Java version, e.g. JRE 1.6, from www.java.com to the external system host, if it isn't already installed.
- Fill in the command line field in the Sync configuration GUI.
- Download "esa.jar" by clicking the "Download ESA Remote Proxy" button in the Sync Configuration wizard.
- Start the ESA Remote Proxy application by running the "java -jar esa.jar" command on the external system host.
If you are running a third-party command-line ESA remotely, please make sure the ESA command-line executable can be launched by the ESA Remote Proxy application. In particular, check "execute" permissions and PATH. The ESA Remote Proxy should then launch the ESA application via the command, specified in the Sync Configuration.
ESA Remote Proxy doesn't change the current directory. If you need the current directory to be different from the one containing the esa.jar file, use a path to it within the start up command:
When you download esa.jar from the Sync Configuration GUI, it will have the necessary configuration parameters such as ESA type, External System ID and polling period predefined within the jar file. Those parameters can also be changed using command-line arguments in the java -jar command:
Host and port where Agiloft is run. This parameter is useful if a server "outer" name differs from its "intranet" name
External System ID, see below
Polling period, seconds
ESA Name. Valid names are "EXCHANGE" "FILE" "THIRD_PARTY_COMMAND_LINE"
The Remote Proxy should normally always be running on the external machine similar to a daemon. The Remote Proxy will launch and stop a CL ESA at the request of the sync subsystem.
- The Java archive file is named
esa.jarbecause it also contains some inbuilt ESAs shipped with the sync subsystem, and is used in exactly the same way and does not contain any of your code. Normally it will connect to the Agiloft server it was downloaded from and start polling it for messages:
- In the External Sync setup, you must click Next to save the sync configuration before running the remote proxy.
- You may specify an IP address from which the system can only receive connections. If you are using NAT, you should specify the external IP address as "seen" by Agiloft, rather than the internal address.
When it receives messages, it will run the CL ESA and pass the messages to it. The following illustration depicts a configuration of the Agiloft sync server, a Remote Proxy and a CL ESA. The Remote Proxy and the CL ESA reside in the external machine.
Note: the command to run a CL ESA is always Start_ESA.bat on Windows or Start_ESA.sh on Linux.
For maximum security, it is strongly advised that you run your Remote Proxy under a separate account, which is only allowed to run your CL ESA application and does not have permission to do anything else. UNIX users may use a sticky bit to give more rights to the CL application.