If the Changes API is enabled, ABRA Flexi logs all changes made in the company database to a changelog and allows you to retrieve the list of changes retroactively.
Changes are numbered in ascending order, so at any given moment the company has a well-defined global version. Version numbers do not necessarily follow one another directly — for technical reasons, there may be gaps in the sequence — but the version number is always unique and increasing. This can be used for automated synchronization of external systems with ABRA Flexi, and it is also the basis for the instant change-notification feature, i.e. Web Hooks.
⚠️ The ABRA Flexi license must have an active REST API, at least for reading. All new paid licenses already have this by default. Without an active REST API for reading or writing, the call returns 403 Forbidden.
Enabling and disabling
The easiest way to check the status and enable or disable the Changes API is via the web interface at /c/{firma}/changes/control. Programmatically, there are two addresses for this, called using the PUT or POST method:
PUT https://demo.flexibee.eu/c/demo/changes/enable.xml
PUT https://demo.flexibee.eu/c/demo/changes/disable.xml
The request has no body, so add the Content-Length: 0 header to it.
🚨 Both enabling and disabling the Changes API changes the database structure, and therefore requires an exclusive lock — see the session lock error below. Do not perform these actions while someone is working in the company.
Checking the enabled status
If you need to check the status programmatically, use:
GET https://demo.flexibee.eu/c/demo/changes/status.xml
If the Changes API is enabled, the response contains success with the value true:
<?xml version="1.0" ?>
<winstrom version="1.0">
<success>true</success>
<message>Changelog is enabled.</message>
</winstrom>
If the response is false or an error — which happens if the REST API is not enabled — the Changes API is disabled.
Getting the current global version
You can include the current global version in any XML or JSON export obtained via the REST API by adding the ?add-global-version=true parameter. The response then looks like this:
<?xml version="1.0"?>
<winstrom version="1.0" globalVersion="6">
...
</winstrom>
Retrieving change records
At the address /c/{firma}/changes.xml you will find a list of all changes since tracking began:
GET https://demo.flexibee.eu/c/demo/changes.xml
<?xml version="1.0"?>
<winstrom 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>
The numeric object ID (<id>1</id>) and code (<id>code:KÓD</id>) are always listed; if the object also had any external IDs at the time the operation was performed, those are listed as well (<id>ext:...</id>).
The attributes of each element indicate the version in which the operation occurred (in-version) and what type of operation it was (operation; possible values are create, update, and delete). The globalVersion attribute is always present. The last element in the listing is always next, which indicates the version number this listing would continue from, or none if there are no further changes.
The listing can be adjusted using the following parameters:
| From which version to list (inclusive); by default from the start of tracking. |
| How many records to list; 100 by default, 1000 maximum. |
| Which agendas to list changes for; can be specified multiple times — if not specified, changes for all agendas are listed. |
⚠️ A limit value higher than 1000 will be silently reduced to 1000, and an unknown agenda name in the ?evidence= parameter is silently ignored — the listing will then return changes for all agendas. Please verify the names in the tables below.
In JSON format, 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"
}
}
Synchronizing external systems with ABRA Flexi
Versioned changes can be easily used for efficient synchronization of external systems with ABRA Flexi — unlike using the last modified date. The procedure is as follows.
Initial data upload
Get the current data including its version (
?add-global-version=true).Save the data.
Remember the version from the
globalVersionattribute.
Differential synchronization
Download changes since the last remembered version (
?start=).Download the changed data and save it, or delete data that has been removed.
Remember the version from the
nextelement, or from theglobalVersionattribute.Repeat from step 1.
The "could not obtain lock on relation" error
If you see the ERROR: could not obtain lock on relation "????" error when enabling or disabling the Changes API, don't worry. For performance reasons, the functions that handle the Changes API are not added to the database at all — we add them to the system only when it is activated, which is why the entire database needs to be exclusively locked.
The solution is to log out of ABRA Flexi, both from the web interface and from the client application. The operation will then go through.
Example of the error:
ERROR: could not obtain lock on relation "drady"
Kde: SQL statement "LOCK TABLE drady IN ACCESS EXCLUSIVE MODE NOWAIT"
Endpoints logged in the Changes API
Address book and contacts
Agenda | Endpoint |
Address book |
|
Bank account (address book) |
|
Contact |
|
Destination |
|
Postal code |
|
Company group |
|
Financial institution |
|
Country |
|
Activity type |
|
Expense type |
|
Price list and goods
Agenda | Endpoint |
Attribute |
|
Price level |
|
Price list |
|
Supplier |
|
Bill of materials |
|
Unit of measure |
|
Customer |
|
Similar goods |
|
Fee |
|
Accessories |
|
Sets and bundles |
|
Price list group |
|
Goods group |
|
Attribute type |
|
Attribute group |
|
Price list status |
|
Documents — invoices and receivables
Agenda | Endpoint |
Received invoice |
|
Received invoice — item |
|
Issued invoice |
|
Issued invoice — item |
|
Sales receipt * |
|
Sales receipt — item * |
|
Receivable |
|
Receivable — item |
|
Payable |
|
Payable — item |
|
Received invoice type |
|
Issued invoice type |
|
Sales receipt type * |
|
Receivable type |
|
Payable type |
|
Documents — bank, cash register, internal documents
Agenda | Endpoint |
Bank * |
|
Bank — item |
|
Mutual offset * |
|
Bank type * |
|
Mutual offset type * |
|
Cash register transaction |
|
Cash register transaction — item |
|
Cash register transaction type |
|
Internal document |
|
Internal document — item |
|
Internal document type |
|
Documents — sales
Agenda | Endpoint |
Received quotation |
|
Received quotation — item |
|
Issued quotation |
|
Issued quotation — item |
|
Received order |
|
Received order — item |
|
Issued order |
|
Issued order — item |
|
Received inquiry |
|
Received inquiry — item |
|
Issued inquiry |
|
Issued inquiry — item |
|
Received quotation type |
|
Issued quotation type |
|
Received order type |
|
Issued order type |
|
Received inquiry type |
|
Issued inquiry type |
|
Sales document status |
|
Shipping method |
|
Payment method |
|
Sales receipt payment |
|
Payment method — posting |
|
Documents — warehouse
Agenda | Endpoint |
Stock movement |
|
Stock movement — item |
|
Stock movement type |
|
Stock card |
|
Stock take |
|
Stock take — item |
|
Reservation |
|
Warehouse mapping |
|
Warehouse location — room * |
|
Warehouse location — rack * |
|
Warehouse location — shelf * |
|
Serial number |
|
Documents — contracts
Agenda | Endpoint |
Contract * |
|
Supplier contract * |
|
Contract — item |
|
Contract type * |
|
Supplier contract type * |
|
Contract status |
|
Payment orders and payment code lists
Agenda | Endpoint |
Payment order |
|
Bank account |
|
Cash register |
|
Warehouse |
|
Package number |
|
Constant symbol |
|
Electronic banking format |
|
Accounting
Agenda | Endpoint |
Chart of accounts |
|
Account |
|
Accounting period |
|
Turnover |
|
VAT return line |
|
VAT rate |
|
VAT classification |
|
VAT reverse charge |
|
Activity |
|
Cost center |
|
Order/Project |
|
Order/Project type |
|
Order/Project status |
|
Order/Project rating |
|
Posting template |
|
Organization type |
|
Exchange rates
Agenda | Endpoint |
Exchange rate (general) * |
|
Exchange rate for pricing * |
|
Intrastat — exchange rate * |
|
Currency |
|
Intrastat
Agenda | Endpoint |
Intrastat — delivery terms |
|
Intrastat — mode of transport |
|
Intrastat — unit of measure |
|
Intrastat — region of destination |
|
Intrastat — nomenclature code |
|
Intrastat — nature of transaction |
|
Intrastat — special movement |
|
Document number series
Agenda | Endpoint |
Series |
|
Series — bank |
|
Series — received invoices |
|
Series — issued invoices |
|
Series — internal document |
|
Series — received quotations |
|
Series — issued quotations |
|
Series — received orders |
|
Series — issued orders |
|
Series — receivables |
|
Series — cash register transaction |
|
Series — received inquiries |
|
Series — issued inquiries |
|
Series — stock movement |
|
Series — payables |
|
Annual series |
|
Settings and system
Agenda | Endpoint |
Settings |
|
Parameter |
|
Attachment |
|
Report |
|
Role |
|
Text |
|
User |
|
Substitution |
|
Journal |
|
Filter |
|
Custom query |
|
Custom query — parameter |
|
Custom query — property |
|
Custom relation |
|
Custom relation type |
|
Visibility right |
|
Certification authority |
|
Label group |
|
Label |
|
Tree (root) |
|
Tree |
|
Tree — price list |
|
Relation |
|