Page tree
Skip to end of metadata
Go to start of metadata

ESA HelperAPI Interface

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

ExceptionsNone
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 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:

  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(), 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

SignatureInteger getPollingPeriod(String externalSystemID)
DescriptionProvides 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 Agiloft admin.
ParametersexternalSystemID - External System ID, used to find the sync configuration.
ReturnsTime to wait before reconnect, in seconds, or 0 if the reconnect should occur immediately.
ExceptionsNone

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

Signaturevoid trackRecordDeletion(String externalSystemID, String externalStructure, Date time, String id)
DescriptionRecords 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
ReturnsNothing
ExceptionsNone

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

SignatureSet<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
ReturnsSet of deleted record IDs
ExceptionsNone

 

isKnownID

Signature

Boolean isKnownID(String externalSystemID, String externalStructure, String id)

DescriptionChecks whether a record with this ID was ever reported to the sync core, in other words, if it was ever synchronized.
PurposeIf 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
ReturnsTrue if the record was ever synchronized
ExceptionsNone

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 

CONTENTS