Two communication styles are currently supported between third-party External System Adapters (ESA) and sync core subsystems for exchanging XML messages:

• HTTPS
• 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  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  when needed, you don't need to write a continually-running  polling service. The application is quite straightforward in that case: receive the call from the  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	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 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  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. 

HTTPS ESA

An HTTPS ESA is a separate application which runs independently of 's control; either remotely or co-located on the  server. It continually polls the  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:

The communication cycle is basically a sequence composed of

• connect
• get-post
• get-post...
• get-post
• disconnect

HTTPS ESAs are usually remote, though this is not a requirement, and their lifecycles are fully independent of the  server. They are just considered to be running externally and to be polling the  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  server until a message is ready for the ESA or a timeout occurs. 

HTTPS Parameters

An HTTPS ESA needs two parameters before connecting to the  sync subsystem:

• The server name to connect to
• The external system ID identifying a particular data set - the  knowledgebase and its particular sync configuration - to be synchronized with

Because these parameters are required before connecting to the  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.

URLs

There are 3 URLs used for HTTP transport. If the  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.

Cycle

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.pollperiod parameter 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  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  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:

//CL console
anatoly@anatoly my-esa>./Start_ESA
<sync>
<esa-call call-id="1">
<getCurrentTime/>
</esa-call>
</sync>

//ESA application response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sync
xsi:noNamespaceSchemaLocation="sync.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<result response-to="1">
<value>2012-09-14T15:36:40.774Z</value>
</result>
</sync>

//CL console
<sync>
<esa-call call-id="2">
<release/>
</esa-call>
</sync>

//ESA application response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sync xsi:noNamespaceSchemaLocation="sync.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<result response-to="2">
<value></value>
</result>
</sync>

//CL console
anatoly@anatoly my-esa>

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. 

Line breaks

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.

Cycle

The typical ESA cycle using STDIO transport is

• Read message, using standard input:
  • Read line. This must always be the XML declaration - <?xml...?>
  • Read line. This must always be <sync>
  • Read and accumulate all lines before getting </sync> line.
  • Parse what was read as XML message
• 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.
• Terminate.

For ESA's using STDIO, Sync is responsible for starting the ESA application when necessary.

Remote Proxy

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,  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  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  sync subsystem. 

To run the Remote Proxy on an external system host, you should:

1. 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.
2. Fill in the command line field in the Sync configuration GUI.
3. Download "esa.jar" by clicking the "Download ESA Remote Proxy" button in the Sync Configuration wizard.
4. 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: 

java -jar <path>\esa.jar 

For example: 

java -jar c:\ewsync\esa.jar 

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:

<p style="page-break-after:always;"></p>

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. 

c:\syncHome>java -jar esa.jar
Agiloft ESA Remote Proxy running.
Connecting to https://sync.agiloft.com (external system ID is 1386095731639@Demo) to get sync
parameters...
Success. Running ESA THIRD_PARTY_COMMAND_LINE
Use Ctrl-C to stop this app. 

When it receives messages, it will run the CL ESA and pass the messages to it. The following illustration depicts a configuration of the  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.