Changes API (sledování změn)
Je-li zapnuté, FlexiBee 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 FlexiBee a také jde o základ pro funkci okamžitého upozorňování na změny (Web Hooks).
Licence FlexiBee musí mít aktivní REST API minimálně pro čtení. 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:
<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:
<winstrom version="1.0" globalVersion="6"> <faktura-vydana in-version="3" operation="create"> <id>1</id> </faktura-vydana> <faktura-vydana-polozka in-version="4" operation="create"> <id>1</id> </faktura-vydana-polozka> <faktura-vydana in-version="5" operation="update"> <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:
?start=123 |
Od které verze se má vypisovat (včetně); defaultně od počátku sledování. |
---|---|
?limit=500 |
Kolik záznamů se má vypsat; defaultně 100, maximálně 1000. |
?evidence=faktura-vydana |
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", "id":"1", "external-ids":[] }, { "@evidence":"faktura-vydana-polozka", "@in-version":"4", "@operation":"create", "id":"1", "external-ids":[] }, { "@evidence":"faktura-vydana", "@in-version":"5", "@operation":"update", "id":"1", "external-ids":["code:VF1-0001/2012"] } ], "next":"6" } }
Zjištění stavu zapnutí Changes API
Uživatelsky lze sjistit 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 <winstrom><success>true</success></winstrom>
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 FlexiBee
Verzované změny lze snadno využít k efektivní synchronizaci externích systémů s FlexiBee (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=<verze>
) - 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 FlexiBee – 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"