View Source

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.

If you use this method in HTTPs ESA, be sure that HelperApi uses HttpXmlEsaTransport.

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

//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 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: Sync core queries the ESA for the list of parameters it wants the sync core to manage, using the `ExternalSystemAdapter.getParametersMeta()` call. generates a Sync Configuration / ESA parameters screen. The admin enters the parameter values in the screen. saves the values into its database. At a later time, typically from `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()`
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. 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. The polling period defines the time period to wait before reconnect, as set by the 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

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:

trackRecordDeletion

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. 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 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. 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()` `externalSystemID` - External System ID, used to find sync configuration `externalStructure` - structure which the record belongs to `after` - date as passed to the `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()` method
Returns	A set of all synchronized record IDs
Exceptions	None