When the Changes API is enabled, ABRA Flexi records all changes made to the company database in a changelog and allows the list of changes to be retrieved retroactively.
Changes are numbered in ascending order, so the company has a well-defined global version at any given time.
Version numbers do not have to be consecutive — there may be gaps for technical reasons. However, each version number is always unique and increasing. This can be used for automated synchronization of external systems with ABRA Flexi, and it also forms the basis for the instant change notification feature (Web Hooks).
The ABRA Flexi license must have REST API enabled at minimum for reading. All new paid licenses include this by default.
The easiest way to check the status and enable/disable the feature is through the web interface at: /c/{firma}/changes/control
Alternatively, it can be enabled with a PUT request to the address /c/{firma}/changes/enable.xml and disabled with a PUT request to the address /c/{firma}/changes/disable.xml.
In addition to PUT, you can also use POST. If you do not have REST API enabled for reading or writing, the response will be 403 Forbidden.
Example of activation using curl:
curl -k -L -u jmeno:heslo -X PUT https://localhost:5434/c/{firma}/changes/enable.xml -H Content-Length:0
Getting the Current Global Version
The current global version can be added to any XML (or JSON) export obtained via the REST API by appending the ?add-global-version=true parameter. The response will look like this:
<?xml version="1.0"?><winstrom version="1.0" globalVersion="6">
...
</winstrom>
Getting Change Records
The address /c/firma/changes.xml contains a list of all changes since tracking began.
The output looks like this:
<?xml version="1.0"?><winstrom version="1.0" globalVersion="6"> <faktura-vydana in-version="3" operation="create" timestamp="2019-01-01 00:00:00.0"> <id>1</id> </faktura-vydana> <faktura-vydana-polozka in-version="4" operation="create" timestamp="2019-06-07 12:34:56.7"> <id>1</id> </faktura-vydana-polozka> <faktura-vydana in-version="5" operation="update" timestamp="2019-06-07 12:34:56.7"> <id>1</id> <id>code:VF1-0001/2012</id> </faktura-vydana> <next>6</next></winstrom>
Each entry includes the numeric ID of the object (<id>1</id>) and the code (<id>code:KÓD</id>); if the object had any external IDs at the time the operation was performed, those are included as well (<id>ext:...</id>).
The attributes of each element indicate which version the operation occurred in (in-version) and what type of operation it was (operation; possible values are create, update, and delete).
The attribute globalVersion is always present. The last element in the output is always next, which indicates the version number at which this output would continue, or none if there are no further changes.
The output can be adjusted using the following parameters:
| The version from which to start listing (inclusive); defaults to the beginning of tracking. |
| The number of records to return; default is 100, maximum is 1000. |
| The registers for which changes should be listed; can be specified multiple times; if not specified, all registers are included. |
In JSON format, the changes look like this:
{ "winstrom": { "@globalVersion": "8", "changes": [ { "@evidence": "faktura-vydana", "@in-version": "3", "@operation": "create", "@timestamp": "2019-01-01 00:00:00.0", "id": "1", "external-ids": [] }, { "@evidence": "faktura-vydana-polozka", "@in-version": "4", "@operation": "create", "@timestamp": "2019-06-07 12:34:56.7", "id": "1", "external-ids": [] }, { "@evidence": "faktura-vydana", "@in-version": "5", "@operation": "update", "@timestamp": "2019-06-07 12:34:56.7", "id": "1", "external-ids": [ "code:VF1-0001\/2012" ] } ], "next": "6" }}
Checking the Changes API Status
You can check the enabled status via the web interface at /c/{firma}/changes/control. Changes API can also be enabled or disabled from this address.
If you need to check the status programmatically, use GET /c/firma/changes/status.xml. If the response is true, the Changes API is enabled. If the response is false or an error (if REST API is not permitted), the Changes API is disabled.
Synchronizing External Systems with ABRA Flexi
Versioned changes can be easily used for efficient synchronization of external systems with ABRA Flexi (as opposed to using the last modified date). The process is as follows:
Initial Data Load:
Retrieve the current data including its version (
?add-global-version=true)Save the data
Store the version (from the
globalVersionattribute)
Delta Synchronization:
Download changes since the last stored version (
?start=)Download and save the changed data, or delete any removed data
Store the version (from the
nextelement, or from theglobalVersionattribute)GOTO 1
ERROR: could not obtain lock on relation „????»
If you encounter the error ERROR: could not obtain lock on relation "????", don't worry. For performance reasons, the database functions that handle the Changes API are not added at all initially. When the Changes API is activated, they are installed into the system — which requires an exclusive lock on the entire database.
The solution is to log out of ABRA Flexi — both from the web interface and from the client application. After that, the activation will proceed successfully.
Example error:
ERROR: could not obtain lock on relation "drady" Kde: SQL statement "LOCK TABLE drady IN ACCESS EXCLUSIVE MODE NOWAIT"