---
title: "ESA HelperAPI Interface"
canonical: "https://help.agiloft.com/space/HELP/43715199/ESA+HelperAPI+Interface"
format: markdown
---
The sync subsystem core provides the ESA with a callback to the HelperApi interface, which might be used to call the sync core. This section describes the methods in this API.

### startSync

| **Signature** | - String **startSync** (String externalSystemID, boolean waitForCompletion)
- String **startSync** (String externalSystemID) |
| --- | --- |
| **Description** | Starts synchronization, whose settings are in the synchronization configuration, identified by External System ID. |
| **Purpose** | Provides a way to externally trigger a synchronization.<br>If you use this method in HTTPs ESA, be sure that HelperApi uses <span style="color: #000000">HttpXmlEsaTransport</span>. |
| **Parameters** | - `externalSystemID` - External System ID, used to find sync configuration
- `waitForCompletion` (optional) - indicates whether control should be returned immediately, or when synchronization finishes. |
| **Returns** | One of SYNC_RUN_ constants. If ended with a SYNC_RUN_ERROR, an error message may follow, separated by space. |
| **Exceptions** | None |
| **Example** | ```java
//starts external-triggered synchronization
HttpXmlEsaTransport hxeTransport = new HttpXmlEsaTransport(new URL(serverHost));
 hxeTransport.connect(externalSystemID, false);
 
 HelperApiTransmitter helperApi = new HelperApiTransmitter(hxeTransport);
 helperApi.startSync(externalSystemID, false); // Asynchronous
 hxeTransport.close();
``` |

### getParameter

| **Signature** | List<EsaParameter>**getParameter**(String externalSystemID, String name) |
| --- | --- |
| **Description ** | Gets an ESA parameter value, stored on the Agiloft server. The value is a list, which may contain any number of real values, depending on the parameter type. |
| **Purpose ** | ESA uses this method to obtain an ESA parameter value. The whole chain of events looks like this:<br>1. Sync core queries the ESA for the list of parameters it wants the sync core to manage, using the `ExternalSystemAdapter.getParametersMeta()` call.
2. Agiloft generates a Sync Configuration / ESA parameters screen.
3. The Agiloft admin enters the parameter values in the screen.
4. Agiloft saves the values into its database.
5. At a later time, typically from [startSync()](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715177/ESA+Interface+Reference#ESAInterfaceReference-startSync), the ESA calls `HelperApi.GetParameter` to get the stored values. |
| **Parameters** | - `externalSystemID` - External System ID, used to find sync configuration
- `name` - Name of ESA parameter, as returned from [getParametersMeta()](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715177/ESA+Interface+Reference#ESAInterfaceReference-getParametersMeta) |
| **Returns ** | Stored parameter value |
| **Exceptions ** | None |

### getPollingPeriod

| **Signature** | Integer **getPollingPeriod**(String externalSystemID) |
| --- | --- |
| **Description** | Provides the Polling Period parameter as set in the General tab of the Sync Configuration wizard. |
| **Purpose** | This method is only of interest for HTTPs ESAs.<br>When an HTTPs ESA finishes a synchronization, or receives a timeout when getting an XML message, it should reconnect to the Sync subsystem core to make itself available for the next synchronization.<br>The polling period defines the time period to wait before reconnect, as set by the Agiloft admin. |
| **Parameters** | `externalSystemID` - External System ID, used to find the sync configuration. |
| **Returns** | Time to wait before reconnect, in seconds, or 0 if the reconnect should occur immediately. |
| **Exceptions** | None |

<span style="color: #000000">Other methods of HelperApi are devoted to tracking deletions. For many systems, this is the most difficult part of creating an ESA because records are simply deleted without a record that they existed. This makes deletion tracking somewhat difficult to implement. In some cases though, the following Helper API can help:</span>

### <span style="color: #01205b">trackRecordDeletion</span>

| **Signature** | void **trackRecordDeletion**(String externalSystemID, String externalStructure, Date time, String id) |
| --- | --- |
| **Description** | Records a record deletion into an internal log, associated with this externalSystemID. |
| **Purpose** | If an ESA, such as HTTPs ESA, receives deletion notifications from the external system, it may forward them to the sync core immediately without the need to maintain an internal list of deleted records.<br>This method does not imply any limitations on the nature of the ID, but requires that ESA receives deletion notifications. Usually this means that the ESA, or a part of it, must always be running. |
| **Parameters** | - `externalSystemID` - External System ID, used to find sync configuration
- `externalStructure` - Structure to which the record belonged
- `time` - Time when a record was deleted
- `id` - ID of the deleted record |
| **Returns** | Nothing |
| **Exceptions** | None |

When it is not possible to subscribe to deletion notifications, it might be possible to find out which records were deleted by comparing a list of all external records ever reported to the Agiloft sync core, that is never synchronized, and the list of records currently existing in the external system. 

### detectDeleted

| **Signature** | Set<String>**detectDeleted**(ExternalSystemAdapter esa, String externalSystemID, String externalStructure, Date after) |
| --- | --- |
| **Description** | Detects which records were deleted, using `countRange()` and binary division approach |
| **Purpose** | If the ID is monotonic and never reused, for example an auto-increment DB key, it is possible to find deleted records by finding gaps in the ID sequence.<br>To do so, the sync core counts the number of external records that it knows and compares them with the `ExternalSystemAdapter.countRange()` call result. If the numbers differ, sync core divides the ID range and count records within each range separately via binary division. The process is repeated until the deleted records, e.g., those with missing IDs, are found. |
| **Parameters** | - `esa` - ESA instance, used to call [countRange()](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715177/ESA+Interface+Reference#ESAInterfaceReference-countRange)
- `externalSystemID` - External System ID, used to find sync configuration
- `externalStructure` - structure which the record belongs to
- `after` - date as passed to the [getDeleted()](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715177/ESA+Interface+Reference#ESAInterfaceReference-getDeleted) method |
| **Returns** | Set of deleted record IDs |
| **Exceptions** | None |


### isKnownID

| **Signature** | Boolean **isKnownID**(String externalSystemID, String externalStructure, String id) |
| --- | --- |
| **Description** | Checks whether a record with this ID was ever reported to the sync core, in other words, if it was ever synchronized. |
| **Purpose** | If the ID nature does not allow using the detectDeleted() method but the ESA can apply another fast algorithm for comparing known and actual lists, the ESA may check whether the sync core is aware of the record using this method. |
| **Parameters** | - `externalSystemID` - External System ID, used to find the sync configuration
- `externalStructure` - Structure which the record belongs to
- `id` - ID of the deleted record |
| **Returns** | True if the record was ever synchronized |
| **Exceptions** | None |

### enumerateKnownIDs

| ** Signature** | Boolean **isKnownID**(String externalSystemID, String externalStructure, String id) |
| --- | --- |
| **Description ** | Returns a list of records known to sync core, in other words, the records that were ever synchronized. |
| **Purpose ** | This is the last hope method – ESA may simply take the list of records which were ever synchronized by sync core and compare them with the actual list of records in the External System.  
While this is the simplest detection method, it can be very slow if there are a lot of records. |
| **Parameters ** | - `externalSystemID` - External System ID, used to find sync configuration
- externalStructure - structure which the record belongs to
- `knownBefore` - date as passed to the [getDeleted()](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715177/ESA+Interface+Reference#ESAInterfaceReference-getDeleted) method |
| **Returns ** | A set of all synchronized record IDs |
| **Exceptions ** | None |


#### Related articles

> Macro (contentbylabel)