---
title: "Calls To and From the ESA"
canonical: "https://help.agiloft.com/space/HELP/43715201/Calls+To+and+From+the+ESA"
format: markdown
---
This topic describes all of the calls made between the ESA and the Helper API. 

# Calls to ESA from Sync

> Macro (anchor)

The following list describes all calls made by sync to an ESA, with the expected results - not including exceptions.

### <span style="color: #000000"> </span>boolean needSyncAgain()

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <needSyncAgain>
> ℹ️ </needSyncAgain>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>boolean value
> ℹ️ </value>     
> ℹ️ ``` |

### Cursor getDeletedPaged(String structure, Timestamp after) 

|  |
| --- |
| <span style="color: #000000">Gets deleted records in a paged manner. See </span>`getDeleted()`<span style="color: #000000"> description. This method is only called if </span>`getDeleted()`<span style="color: #000000"> call returned NULL The Cursor object returned contains information about the number of data pages, data page size and so on.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getDeletedPaged>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <after>
> ℹ️   timestamp-value
> ℹ️ </after>
> ℹ️ </getDeletedPaged>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <cursor> snippet
> ℹ️ ``` |

### Cursor getModifiedPaged(String structure, Timestamp after)

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getModifiedPaged>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <after>
> ℹ️   timestamp-value
> ℹ️ </after>
> ℹ️ </getModifiedPaged> 
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ A number of ExternalRecord snippets - <record> tags
> ℹ️ ``` |

### Date getCurrentTime()

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getCurrentTime>
> ℹ️ </getCurrentTime>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>timestamp value
> ℹ️ </value>  
> ℹ️ ``` |

### ExternalRecord read(String structure, String id)

|  |
| --- |
| <span style="color: #000000">Reads a single record.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <read>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <id>id-value</id>
> ℹ️ </read>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  ExternalRecord snippet
> ℹ️ ``` |

### int countRange(String idMin, String idMax)

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <countRange>
> ℹ️ <min-id>
> ℹ️   String-value
> ℹ️ </min-id>
> ℹ️ <max-id>
> ℹ️   String-value
> ℹ️ </max-id>
> ℹ️ </countRange>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>integer value
> ℹ️ </value>      
> ℹ️ ``` |

### List getParametersMeta(String locale)

|  |
| --- |
| <span style="color: #000000">Gets localized ESA Parameters meta-data.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getParametersMeta>
> ℹ️ <locale>String-value</locale>
> ℹ️ </getParametersMeta>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ A number of <esa-parameter> tags.
> ℹ️ ``` |

### Set getDeleted(String structure, Timestamp after)

|  |
| --- |
| <span style="color: #000000">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, </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> will make use of </span>`getDeletedPaged()`<span style="color: #000000"> method. The ESA may decide how to transfer data at runtime depending on the amount. In any case, </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> will call </span>`getDeleted()`<span style="color: #000000"> first and only call </span>`getDeletedPaged()`<span style="color: #000000"> if "getDeleted()" returns NULL.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getDeleted>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <after>
> ℹ️   timestamp-value
> ℹ️ </after>
> ℹ️ </getDeleted>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <id>id-value</id>
> ℹ️ ...
> ℹ️ <id>id-value</id>
> ℹ️ ```
> ℹ️ 
> ℹ️ Or
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <nullValue>true</nullValue>
> ℹ️ ``` |

### Set getFieldList(String structureOrCollection, String locale)

|  |
| --- |
| <span style="color: #000000">Gets a list of fields, for a given structure. ID and </span>`ModifiedAt`<span style="color: #000000"> fields should not be included.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getFieldList>
> ℹ️ <structure>
> ℹ️ structure-name
> ℹ️ </structure>
> ℹ️ <locale>
> ℹ️   lang-value
> ℹ️ </locale>
> ℹ️ </getFieldList>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ A number of ExternalFields snippets - <field> tags
> ℹ️ ``` |

### Set getModified(String structure, Timestamp after)

|  |
| --- |
| <span style="color: #000000">For some systems, this may result in a great amount of data to be transferred, especially for the initial sync.</span>  
<span style="color: #000000">If the ESA predicts such traffic, it should return NULL from this method, not an empty set. In this case, </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> will use the </span>`getModifiedPaged()`<span style="color: #000000"> method.</span>  
<span style="color: #000000"> </span><br><span style="color: #000000">The ESA may decide how to transfer data at runtime depending on the amount. In any case, </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> will call </span>`getModified()`<span style="color: #000000"> first and only call </span>`getModifiedPaged()`<span style="color: #000000"> if </span>`getModified()`<span style="color: #000000"> returns NULL</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getModified>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <after>
> ℹ️   timestamp-value
> ℹ️ </after>
> ℹ️ </getModified> 
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  A number of ExternalRecord snippets - <record> tags
> ℹ️ ```
> ℹ️ 
> ℹ️ Or
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <nullValue>true</nullValue>
> ℹ️ ``` |

### Set getRelations(String structureOrCollection, String locale)

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getRelations>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <locale>
> ℹ️   lang-value
> ℹ️ </locale>
> ℹ️ </getRelations>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ A number of <relation> snippets.    
> ℹ️ ``` |

### Set getStructureList()

|  |
| --- |
| <span style="color: #000000">Gets a list of external data structure names. </span>`Structure`<span style="color: #000000"> is a logical data unit, mappable to an </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> table; a table, a folder, a class in OODB or any other type of data grouping.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getStructureList>
> ℹ️ </getStructureList>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ External Structure snippet      
> ℹ️ ``` |

### Set readDataPage(Cursor cursor, int pageIndex)

|  |
| --- |
| <span style="color: #000000">Gets data from a cursor. This method is used to actually access the data in the cursor.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <readDataPage>
> ℹ️ <cursor-id>
> ℹ️   cursor ID
> ℹ️ </cursor-id>
> ℹ️ <page-index>
> ℹ️   data page index
> ℹ️ </page-index>
> ℹ️ </readDataPage>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ A number of ExternalRecord snippets - <record> tags -
> ℹ️ OR <id>id-value</id>, depending on the cursor type
> ℹ️ ``` |

### String startSync(String externalSystemID)

|  |
| --- |
| <span style="color: #000000">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"</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  <startSync>
> ℹ️   <external-system-id>
> ℹ️     String-value
> ℹ️   </external-system-id>
> ℹ️ </startSync>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>1.0</value>
> ℹ️ ``` |

### Timestamp update(String structure, Timestamp lastSeen, ExternalRecord values)

|  |
| --- |
| <span style="color: #000000">Updates the record in external system, returns update timestamp. Only does the update if the record is not modified since </span>`lastSeen`<span style="color: #000000"> timestamp. If the record is modified, throws exception - see below.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  <update>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <last-seen>
> ℹ️   timestamp-value
> ℹ️ </last-seen>
> ℹ️ An ExternalRecord snippet (<record>)
> ℹ️ </update>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  <value>timestamp-value</value>
> ℹ️ ``` |

### void delete(String structure, Timestamp lastSeen, String pk)

|  |
| --- |
| <span style="color: #000000">Deletes the record in external system, returns true. Only does the deletion if the record is not modified since </span>`lastSeen`<span style="color: #000000"> timestamp. If the record is modified, throws exception - see below.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <delete>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <last-seen>
> ℹ️   timestamp-value
> ℹ️ </last-seen>
> ℹ️ <id>id-value</id>
> ℹ️ </delete>
> ℹ️ ``` |

### void endSync()

|  |
| --- |
| <span style="color: #000000">Returns Bit-ORed constants, restricting synchronization run modes:</span>  
<span style="color: #000000">1 - Run Manually allowed</span>  
<span style="color: #000000">2 - Run by Sync Actions allowed</span>  
<span style="color: #000000">4 - Run by external system request allowed.</span>  
<span style="color: #000000">For example, 6 - 2 bit-OR 4 - would designate that the ESA supports non-interactive synchronizations by both </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> and external system requests</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getAllowedRunModes>
> ℹ️ </getAllowedRunModes>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>
> ℹ️   integer value
> ℹ️ </value>
> ℹ️ ``` |

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

|  |
| --- |
| <span style="color: #000000">Configures the ESA to use with an </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> 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 </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> 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 </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> 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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <configure>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <force>
> ℹ️   Boolean-value
> ℹ️ </force>
> ℹ️ </configure>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <value>
> ℹ️  String-value
> ℹ️ </value>
> ℹ️ ``` |

### void leaseCursor(Cursor cursor)

|  |
| --- |
| <span style="color: #000000">Closes the cursor. This call indicates that </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> doesn't need the cursor anymore and guarantees that </span>`readDataPage`<span style="color: #000000"> will not be called again for this cursor.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <closeCursor>
> ℹ️ <cursor-id>
> ℹ️   cursor ID
> ℹ️ </cursor-id>
> ℹ️ </closeCursor>
> ℹ️ ``` |

### void leaseSession()

|  |
| --- |
| <span style="color: #000000">Resets session timeout counter (if the ESA has any).</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <leaseSession>
> ℹ️ </leaseSession>
> ℹ️ ``` |

# Calls from ESA to Helper API

<span style="color: #000000">The following list describes all calls made to sync by an ESA, with the expected results - not including exceptions.</span>

### boolean isKnownID(String externalSystemID, String externalStructure, String id)

|  |
| --- |
| <span style="color: #000000">Asks </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> whether it has a known peer for this external ID.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <isKnownID>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ <id>String-value</id>
> ℹ️ </isKnownID>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️  Boolean-value
> ℹ️ ``` |

### Object getParameter(String externalSystemID, String name)

|  |
| --- |
| <span style="color: #000000">Gets an ESA parameter value, stored on the </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> Server.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <getParameter>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <name>
> ℹ️   String-value
> ℹ️ </name>
> ℹ️ </getParameter>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <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)

|  |
| --- |
| <span style="color: #000000">This is a helper method for deletion detection over auto-incremented IDs. The ESA interface must support an optional </span>`countRange`<span style="color: #000000"> method in this case.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <detectDeleted>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <after>
> ℹ️   Timestamp-value
> ℹ️ </after>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ </detectDeleted>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <id>String-value</id>
> ℹ️ ...
> ℹ️ <id>String-value</id>
> ℹ️ ``` |

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

|  |
| --- |
| <span style="color: #000000">Asks </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> to enumerate external system IDs, known by </span><span style="color: #000000">Agiloft</span><span style="color: #000000"> at some moment. the ESA can then check whether records with such IDs exist and compose a list of deleted records.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <enumerateKnownIDs>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <known-before>
> ℹ️   Timestamp-value
> ℹ️ </known-before>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ </enumerateKnownIDs>
> ℹ️ ``` |
| > ℹ️ **Output XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <id>String-value</id>
> ℹ️ ...
> ℹ️ <id>String-value</id>
> ℹ️ ``` |

### void startSync(String externalSystemID)

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <startSync>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ </startSync>
> ℹ️ ``` |

### void trackRecordDeletion(String externalSystemID, String externalStructure, Timestamp time, String id)

|  |
| --- |
| <span style="color: #000000">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.</span> |
| > ℹ️ **Input XML Example**
> ℹ️ 
> ℹ️ ```xml
> ℹ️ <trackRecordDeletion>
> ℹ️ <external-system-id>
> ℹ️   String-value
> ℹ️ </external-system-id>
> ℹ️ <time>
> ℹ️   Timestamp-value
> ℹ️ </time>
> ℹ️ <structure>
> ℹ️   structure-name
> ℹ️ </structure>
> ℹ️ </trackRecordDeletion>
> ℹ️ ``` |


> Macro (hide-if)
> 
> #### Related articles
> 
> > Macro (contentbylabel)