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.



<needSyncAgain>
</needSyncAgain>





<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.



<getDeletedPaged>
<structure>
  structure-name
</structure>
<after>
  timestamp-value
</after>
</getDeletedPaged>





<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.



<getModifiedPaged>
<structure>
  structure-name
</structure>
<after>
  timestamp-value
</after>
</getModifiedPaged> 





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 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.



<getCurrentTime>
</getCurrentTime>





<value>timestamp value
</value>



ExternalRecord read(String structure, String id)

Reads a single record.



<read>
<structure>
  structure-name
</structure>
<id>id-value</id>
</read>





 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.



<countRange>
<min-id>
  String-value
</min-id>
<max-id>
  String-value
</max-id>
</countRange>





<value>integer value
</value>



List getParametersMeta(String locale)

Gets localized ESA Parameters meta-data.



<getParametersMeta>
<locale>String-value</locale>
</getParametersMeta>





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, will make use of getDeletedPaged() method. The ESA may decide how to transfer data at runtime depending on the amount. In any case, will call getDeleted() first and only call getDeletedPaged() if "getDeleted()" returns NULL.



<getDeleted>
<structure>
  structure-name
</structure>
<after>
  timestamp-value
</after>
</getDeleted>





<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.



<getFieldList>
<structure>
structure-name
</structure>
<locale>
  lang-value
</locale>
</getFieldList>





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.
If the ESA predicts such traffic, it should return NULL from this method, not an empty set. In this case, will use the getModifiedPaged() method.
 

The ESA may decide how to transfer data at runtime depending on the amount. In any case, will call getModified() first and only call getModifiedPaged() if getModified() returns NULL



<getModified>
<structure>
  structure-name
</structure>
<after>
  timestamp-value
</after>
</getModified> 





 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.



<getRelations>
<structure>
  structure-name
</structure>
<locale>
  lang-value
</locale>
</getRelations>





A number of <relation> snippets.



Set getStructureList()

Gets a list of external data structure names. Structure is a logical data unit, mappable to an table; a table, a folder, a class in OODB or any other type of data grouping.



<getStructureList>
</getStructureList>





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.



<readDataPage>
<cursor-id>
  cursor ID
</cursor-id>
<page-index>
  data page index
</page-index>
</readDataPage>





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"



 <startSync>
  <external-system-id>
    String-value
  </external-system-id>
</startSync>





<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.



 <update>
<structure>
  structure-name
</structure>
<last-seen>
  timestamp-value
</last-seen>
An ExternalRecord snippet (<record>)
</update>





 <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.



<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 and external system requests



<getAllowedRunModes>
</getAllowedRunModes>





<value>
  integer value
</value>



void endSync()String configure(String externalSystemID, boolean force)

Configures the ESA to use with an 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 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 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.



<configure>
<external-system-id>
  String-value
</external-system-id>
<force>
  Boolean-value
</force>
</configure>





<value>
 String-value
</value>



void leaseCursor(Cursor cursor)

Closes the cursor. This call indicates that doesn't need the cursor anymore and guarantees that readDataPage will not be called again for this cursor.



<closeCursor>
<cursor-id>
  cursor ID
</cursor-id>
</closeCursor>



void leaseSession()

Resets session timeout counter (if the ESA has any).



<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 whether it has a known peer for this external ID.



<isKnownID>
<external-system-id>
  String-value
</external-system-id>
<structure>
  structure-name
</structure>
<id>String-value</id>
</isKnownID>





 Boolean-value



Object getParameter(String externalSystemID, String name)

 Gets an ESA parameter value, stored on the Server.



<getParameter>
<external-system-id>
  String-value
</external-system-id>
<name>
  String-value
</name>
</getParameter>





<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.



<detectDeleted>
<external-system-id>
  String-value
</external-system-id>
<after>
  Timestamp-value
</after>
<structure>
  structure-name
</structure>
</detectDeleted>





<id>String-value</id>
...
<id>String-value</id>



Set enumerateKnownIDs(String externalSystemID, String externalStructure, Timestamp knownBefore)

 Asks to enumerate external system IDs, known by at some moment. the ESA can then check whether records with such IDs exist and compose a list of deleted records.



<enumerateKnownIDs>
<external-system-id>
  String-value
</external-system-id>
<known-before>
  Timestamp-value
</known-before>
<structure>
  structure-name
</structure>
</enumerateKnownIDs>





<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.



<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.



<trackRecordDeletion>
<external-system-id>
  String-value
</external-system-id>
<time>
  Timestamp-value
</time>
<structure>
  structure-name
</structure>
</trackRecordDeletion>





Related articles