Changes API

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" 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:

?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",
                "@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 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:

1. Získat aktuální data včetně jejich verze (?add-global-version=true)
2. Uložit data
3. Zapamatovat si verzi (z atributu globalVersion)

Rozdílová synchronizace:

1. Stáhnout změny od poslední zapamatované verze (?start=<verze>)
2. Stáhnout změněná data a uložit je, případně smazat odstraněná data
3. Zapamatovat si verzi (z elementu next, případně z atributu globalVersion)
4. 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"