Je-li changes API zapnuté, ABRA Flexi zaznamenává všechny změny provedené v databázi firmy do changelogu a umožňuje seznam změn zpětně získat.
Změny jsou vzestupně číslované, takže firma má v každém okamžiku dobře definovanou globální verzi.
Čísla verzí nemusí následovat těsně po sobě, v řadě mohou být z technických důvodů mezery. Vždy je však číslo verze unikátní a rostoucí. Toho lze využít k automatizované synchronizaci externích systémů s ABRA Flexi a také jde o základ pro funkci okamžitého upozorňování na změny (Web Hooks).
Licence ABRA Flexi musí mít aktivní REST API minimálně pro čtení. To mají všechny nové placené licence již standardně.
Zjištění stavu a zapnutí / vypnutí lze provést nejsnáze ve webovém rozhraní na adrese: /c/{firma}/changes/control
Případně lze zapnout PUT requestem na adresu /c/{firma}/changes/enable.xml a vypnout taktéž PUT requestem na adresu /c/{firma}/changes/disable.xml.
Kromě PUT lze použít také POST. Pokud nemáte aktivní REST API pro čtení nebo pro zápis, odpověď je 403 Forbidden.
Ukázka aktivace pomocí programu curl:
curl -k -L -u jmeno:heslo -X PUT https://localhost:5434/c/{firma}/changes/enable.xml -H Content-Length:0
Získání aktuální globální verze
Do jakéhokoliv XML (resp. JSON) exportu získaného přes REST API lze doplnit aktuální globání verzi přidáním parametru ?add-global-version=true. Odpověď bude vypadat takto:
<?xml version="1.0"?> <winstrom version="1.0" globalVersion="6">
...
</winstrom>
Získání záznamů o změnách
Na adrese /c/firma/changes.xml se nachází seznam všech změn od začátku jejich sledování.
Výpis vypadá takto:
<?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>
Uvedeno je vždy číselné ID objektu (<id>1</id>) a kód (<id>code:KÓD</id>); pokud měl objekt v době provádění operace i nějaká externí ID, pak jsou uvedena i ta (<id>ext:...</id>).
V atributech každého elementu je uvedeno, v jaké verzi k operaci došlo (in-version) a o jakou operaci šlo (operation; možné hodnoty jsou create, update a delete).
Vždy je přítomen atribut globalVersion. Posledním elementem ve výpisu je vždy next, který udává číslo verze, kterou by tento výpis pokračoval, případně none, pokud žádné další změny nejsou.
Výpis lze upravit následujícími parametry:
| Od které verze se má vypisovat (včetně); defaultně od počátku sledování. |
| Kolik záznamů se má vypsat; defaultně 100, maximálně 1000. |
| Pro které evidence se mají změny vypisovat; lze uvést vícekrát, není-li uvedeno, vypisují se všechny. |
Ve formátu JSON vypadají změny takto:
{
"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"
}
}
Zjištění stavu zapnutí Changes API
Uživatelsky lze zjistit stav zapnutí na adrese /c/{firma}/changes/control. Zde je také možné Changes API zapínat nebo vypínat.
Pokud potřebujete zjistit stav programově, tak použijte GET /c/firma/changes/status.xml. V případě odpovědi true je Changes API zapnuté. Pokud je odpovědí false nebo chyba (pokud není povolené REST API) je Changes API vypnuté.
Synchronizace externích systémů s ABRA Flexi
Verzované změny lze snadno využít k efektivní synchronizaci externích systémů s ABRA Flexi (na rozdíl od data poslední změny). Postup je následující:
Počáteční nahrání dat:
Získat aktuální data včetně jejich verze (
?add-global-version=true)Uložit data
Zapamatovat si verzi (z atributu
globalVersion)
Rozdílová synchronizace:
Stáhnout změny od poslední zapamatované verze (
?start=)Stáhnout změněná data a uložit je, případně smazat odstraněná data
Zapamatovat si verzi (z elementu
next, případně z atributuglobalVersion)GOTO 1
ERROR: could not obtain lock on relation „????“
Pokud se vám zobrazí chyba ERROR: could not obtain lock on relation "????", nezoufejte. Kvůli výkonnosti nejsou v databázi funkce, které obsluhují Changes API vůbec přidané. V případě aktivace Changes API je do systému zaneseme. Proto je potřeba exkluzivně zamknout celou databázi.
Řešením tedy je se odhlásit z ABRA Flexi – jak z webového rozhraní tak klientské aplikace. Pak už to projde.
Ukázka chyby:
ERROR: could not obtain lock on relation "drady" Kde: SQL statement "LOCK TABLE drady IN ACCESS EXCLUSIVE MODE NOWAIT"