Tracking changes through the API

When using an API system it is important to understand the principle of tracking changes. The services IEntityChangesService and IEntityHeadService are used for tracking changes and data exchange between the ELMA server and external applications.

The exchange consists of the following steps:

1. Generate a permanent EQL query
2. Perform initial synchronization
3. Periodically request changes from the server
   When getting changes from the server, confirm for synchronization
   If an error occurs - sync again

Further, we describe these steps in details

Generate a permanent EQL query 

The client generates and stores EQL queries to a particular type. For example, to get a list of current user tasks, the query to the ITaskBase type is used.

EQL query to retrieve a list of incoming tasks 

Executor = CurrentUser() AND Status IN (Enum(’NewOrder’), Enum(’Read’), Enum(’InProgress’), Enum(’RefuseApprovalExecutor’), Enum(’OnApprovalExecutor’))

To generate a query read Complex filters. EQL language

Perform initial synchronization

When calling the first time (in there was no sync previously), the headers of the data list are requested through the IEntityHeadService.Query method. In this case, it is necessary to hold a primary synchronization of the client cache and the server using the method IEntityChangesService.Sync.

Periodically request changes from the server

Periodically, you can make a request to IEntityChangesService.Changes method.

Once the changes are received through the method IEntityChangesService.Changes, the client must apply them locally:

• remove all objects contained in the array Deleted from the list
• update\add to the list all the objects from the array Updated

After applying local data, to confirm the synchronization cache, the client sends the Id identifier (received earlier) to the server, to the method IEntityChangesService.ChangesCommit. 

By applying the data locally, we understand storing the lists in the persistent local repository on the client. Once saved,  the entity data can be applied in the background mode.

If an error occurs in the IEntityChangesService.ChangesCommit method, when confirming synchronization, or if the method returns False, the cache must be synchronized again (see. Above).