Calls To and From the ESA
This topic describes all of the calls made between the ESA and the Helper API.
Calls to ESA from Sync
The following list describes all calls made by sync to an ESA, with the expected results - not including exceptions.
boolean needSyncAgain()
| Sometimes, the ESA may decide there is a necessity to re-run synchronization immediately after sync finish. An example is if update actually updates more than 1 record, so data are changed in a broader scope than the Sync subsystem expects. In this case, the ESA should return true from this method. |
Input XML Example <needSyncAgain> </needSyncAgain> |
Output XML Example <value>boolean value </value> |
Cursor getDeletedPaged(String structure, Timestamp after)
Gets deleted records in a paged manner. See getDeleted() description. This method is only called if getDeleted() call returned NULL The Cursor object returned contains information about the number of data pages, data page size and so on. |
Input XML Example <getDeletedPaged> <structure> structure-name </structure> <after> timestamp-value </after> </getDeletedPaged> |
Output XML Example <cursor> snippet |
Cursor getModifiedPaged(String structure, Timestamp after)
| Gets modified records in a paged manner. See "getModified()" description. This method is only called if "getModified()" call returned NULL The Cursor object returned contains information about the number of data pages, data page size and so on. |
Input XML Example <getModifiedPaged> <structure> structure-name </structure> <after> timestamp-value </after> </getModifiedPaged> |
Output XML Example A number of ExternalRecord snippets - <record> tags |
Date getCurrentTime()
| Gets current UTC time of a remote system, if available. Sync uses this method to compute the time shift between Agiloft server and the external system. The shift is taken into account for all datetime control values, passed to the ESA - getModified(), record.modifiedAt, lastSeen timestamps, etc. Note: This shift is not applied when converting record date. Datetime or time fields. |
Input XML Example <getCurrentTime> </getCurrentTime> |
Output XML Example <value>timestamp value </value> |
ExternalRecord read(String structure, String id)
| Reads a single record. |
Input XML Example <read> <structure> structure-name </structure> <id>id-value</id> </read> |
Output XML Example ExternalRecord snippet |
int countRange(String idMin, String idMax)
| Returns a number of external system records, whose external ID is in the given range numerically or alphabetically, whichever is applicable. You should only implement this method if your ESA calls "detectDeleted" HelperApi method. |
Input XML Example <countRange> <min-id> String-value </min-id> <max-id> String-value </max-id> </countRange> |
Output XML Example <value>integer value </value> |
List getParametersMeta(String locale)
| Gets localized ESA Parameters meta-data. |
Input XML Example <getParametersMeta> <locale>String-value</locale> </getParametersMeta> |
Output XML Example A number of <esa-parameter> tags. |
Set getDeleted(String structure, Timestamp after)
Gets IDs of records, deleted in external system after given timestamp For some systems, this may result in a large amount of data to be transferred. If the ESA predicts such traffic, it should return NULL from this method, not an empty set. In this case,
Agiloft will make use of getDeletedPaged() method. The ESA may decide how to transfer data at runtime depending on the amount. In any case,
Agiloft will call getDeleted() first and only call getDeletedPaged() if "getDeleted()" returns NULL. |
Input XML Example <getDeleted> <structure> structure-name </structure> <after> timestamp-value </after> </getDeleted> |
Output XML Example <id>id-value</id> ... <id>id-value</id> Or <nullValue>true</nullValue> |
Set getFieldList(String structureOrCollection, String locale)
Gets a list of fields, for a given structure. ID and ModifiedAt fields should not be included. |
Input XML Example <getFieldList> <structure> structure-name </structure> <locale> lang-value </locale> </getFieldList> |
Output XML Example A number of ExternalFields snippets - <field> tags |
Set getModified(String structure, Timestamp after)
For some systems, this may result in a great amount of data to be transferred, especially for the initial sync. The ESA may decide how to transfer data at runtime depending on the amount. In any case,
Agiloft will call |
Input XML Example <getModified> <structure> structure-name </structure> <after> timestamp-value </after> </getModified> |
Output XML Example A number of ExternalRecord snippets - <record> tags Or <nullValue>true</nullValue> |
Set getRelations(String structureOrCollection, String locale)
| Gets a list of relations from the given structure. This should only include relations, navigable from this object. A Locale argument can be used to localize relation screen names. |
Input XML Example <getRelations> <structure> structure-name </structure> <locale> lang-value </locale> </getRelations> |
Output XML Example A number of <relation> snippets. |
Set getStructureList()
Gets a list of external data structure names. Structure is a logical data unit, mappable to an
Agiloft table; a table, a folder, a class in OODB or any other type of data grouping. |
Input XML Example <getStructureList> </getStructureList> |
Output XML Example External Structure snippet |
Set readDataPage(Cursor cursor, int pageIndex)
| Gets data from a cursor. This method is used to actually access the data in the cursor. |
Input XML Example <readDataPage> <cursor-id> cursor ID </cursor-id> <page-index> data page index </page-index> </readDataPage> |
Output XML Example A number of ExternalRecord snippets - <record> tags - OR <id>id-value</id>, depending on the cursor type |
String startSync(String externalSystemID)
| Starts a synchronization. This is the very first method, called during Sync. Return value is the Sync protocol version, supported by the ESA. Currently it must be "1.0" |
Input XML Example <startSync>
<external-system-id>
String-value
</external-system-id>
</startSync>
|
Output XML Example <value>1.0</value> |
Timestamp update(String structure, Timestamp lastSeen, ExternalRecord values)
Updates the record in external system, returns update timestamp. Only does the update if the record is not modified since lastSeen timestamp. If the record is modified, throws exception - see below. |
Input XML Example <update> <structure> structure-name </structure> <last-seen> timestamp-value </last-seen> An ExternalRecord snippet (<record>) </update> |
Output XML Example <value>timestamp-value</value> |
void delete(String structure, Timestamp lastSeen, String pk)
Deletes the record in external system, returns true. Only does the deletion if the record is not modified since lastSeen timestamp. If the record is modified, throws exception - see below. |
Input XML Example <delete> <structure> structure-name </structure> <last-seen> timestamp-value </last-seen> <id>id-value</id> </delete> |
void endSync()
| Returns Bit-ORed constants, restricting synchronization run modes: 1 - Run Manually allowed 2 - Run by Sync Actions allowed 4 - Run by external system request allowed. For example, 6 - 2 bit-OR 4 - would designate that the ESA supports non-interactive synchronizations by both Agiloft and external system requests |
Input XML Example <getAllowedRunModes> </getAllowedRunModes> |
Output XML Example <value> integer value </value> |
void endSync()String configure(String externalSystemID, boolean force)
| Configures the ESA to use with an Agiloft instance. This method is called on the ESA when a Sync configuration is created. This also allows a check on ESA availability. The implementation of this method depends on the ESA. Simple ESAs, which don't need to communicate Agiloft back; i.e. neither use Helper API outside of syncn cycle nor initiate Sync by external system requests; may simply ignore this call and return the passed externalSystemID. More complex ESAs should retain these values somewhere and use them to call Agiloft and to authenticate themselves by externalSystemID. If such an ESA is already configured - already has an associated ExternalSystemID - it must return the stored value and only replace it by the new parameters if parameter "force" is true. |
Input XML Example <configure> <external-system-id> String-value </external-system-id> <force> Boolean-value </force> </configure> |
Output XML Example <value> String-value </value> |
void leaseCursor(Cursor cursor)
Closes the cursor. This call indicates that
Agiloft doesn't need the cursor anymore and guarantees that readDataPage will not be called again for this cursor. |
Input XML Example <closeCursor> <cursor-id> cursor ID </cursor-id> </closeCursor> |
void leaseSession()
| Resets session timeout counter (if the ESA has any). |
Input XML Example <leaseSession> </leaseSession> |
Calls from ESA to Helper API
The following list describes all calls made to sync by an ESA, with the expected results - not including exceptions.
boolean isKnownID(String externalSystemID, String externalStructure, String id)
| Asks Agiloft whether it has a known peer for this external ID. |
Input XML Example <isKnownID> <external-system-id> String-value </external-system-id> <structure> structure-name </structure> <id>String-value</id> </isKnownID> |
Output XML Example Boolean-value |
Object getParameter(String externalSystemID, String name)
| Gets an ESA parameter value, stored on the Agiloft Server. |
Input XML Example <getParameter> <external-system-id> String-value </external-system-id> <name> String-value </name> </getParameter> |
Output XML Example <value> Value. The type depends on the ESA parameter type. </value> ... There can be several <value> tags within result |
Set detectDeleted(String externalSystemID, String externalStructure, Timestamp after)
This is a helper method for deletion detection over auto-incremented IDs. The ESA interface must support an optional countRange method in this case. |
Input XML Example <detectDeleted> <external-system-id> String-value </external-system-id> <after> Timestamp-value </after> <structure> structure-name </structure> </detectDeleted> |
Output XML Example <id>String-value</id> ... <id>String-value</id> |
Set enumerateKnownIDs(String externalSystemID, String externalStructure, Timestamp knownBefore)
| Asks Agiloft to enumerate external system IDs, known by Agiloft at some moment. the ESA can then check whether records with such IDs exist and compose a list of deleted records. |
Input XML Example <enumerateKnownIDs> <external-system-id> String-value </external-system-id> <known-before> Timestamp-value </known-before> <structure> structure-name </structure> </enumerateKnownIDs> |
Output XML Example <id>String-value</id> ... <id>String-value</id> |
void startSync(String externalSystemID)
| This method triggers Sync with an external system, identified by externalSystemID. The method can be used by ESA or any other application, if using HTTPs transport to send a message to Helper Api to start synchronization, based on some event in the external system. |
Input XML Example <startSync> <external-system-id> String-value </external-system-id> </startSync> |
void trackRecordDeletion(String externalSystemID, String externalStructure, Timestamp time, String id)
| Places a record deletion entry in the internal log associated with this externalSystemID. A timestamp argument can be useful if the ESA chooses to batch reports of record deletions. However, if some deletion reports are delayed, the ESA should flush them as soon as it receives any call on the ESA interface, prior to actually processing the call. |
Input XML Example <trackRecordDeletion> <external-system-id> String-value </external-system-id> <time> Timestamp-value </time> <structure> structure-name </structure> </trackRecordDeletion> |