Přejít na obsah
Flexideo
Skip to main content

Požadavek get-history

Účel a dopady​

Čte informace z evidence historie fxd dokumentů: buď seznam všech historických změn dané instance dokumentu (list), nebo kompletní obsah jedné konkrétní historické verze (document). Požadavek nic nemění, jen čte.

Dostupnost, kontext, oprávnění apod.​

  • Dostupné každému přihlášenému uživateli. Viditelnost je řízena samostatně pro každou položku:
    • Seznam historie (list) vyžaduje, aby role volajícího (případně přepsaná opt-roles) měla u daného dokumentového typu oprávnění k historii; bez něj server tiše vrátí prázdný seznam, ne chybu.
    • Obě položky (list i document) navíc podléhají administrativnímu filtru (vazba na akční registr či uzel dokumentu); zamítnutí je opět tiché.
  • Na rozdíl od get-document/get-pseudo-document se toto tiché zamítnutí nepromítne ani do list/document vůbec neúčastí na rozdíl transakčního přeskočení obálky – požadavek se provede vždy, i kdyby v témže požadavku dříve selhal jiný transakční požadavek.

XML požadavek (syntax + popis)​

  <request>
   <get-history
    opt-roles="{string}"
    >
    <list ... /> *
    <document ... /> *
   </get-history>
  </request>

Parametry a pravidla (atributy, potomci)​

  • opt-roles - Volitelná role - Výchozí volitelná role pro všechny vnořené list/document, které ji sami nepřepíšou. (typ: string; nepovinný)

Potomci list a document se zpracují v pořadí, v jakém jsou uvedeny, každý vygeneruje vlastní odpovídající element přímo v <response> (viz „XML odpověď“); potomek s jiným jménem se přeskočí beze stopy.

Uzel list​

  <list
   type="{string}"
   dkey="{number}"
   opt-roles="{string}"
   />
  • type - typ dokumentu - Typový název dokumentu definovaného v XDS. (typ: string; nepovinný – chybí-li nebo je neznámý, vede to k chybové odpovědi této položky)
  • dkey - PDK dokumentu - Primární klíč instance typu dokumentu dle databáze. (typ: number; nepovinný – nelze-li převést na číslo, vede to k chybové odpovědi této položky)
  • opt-roles - Volitelná role - Přepíše pro tento list roli zděděnou z get-history/přihlášení. (typ: string; nepovinný)

Uzel nemá potomky.

Uzel document​

  <document
   type="{string}"
   dkey="{number}"
   id="{number}"
   opt-roles="{string}"
   />
  • type - typ dokumentu - Typový název dokumentu definovaného v XDS. (typ: string; nepovinný – chybí-li nebo je neznámý, výsledkem je prázdný <history-doc></history-doc> bez chyby)
  • dkey - PDK dokumentu - Primární klíč instance typu dokumentu dle databáze. (typ: number; nepovinný – nelze-li převést na číslo, výsledkem je prázdný <history-doc></history-doc> bez chyby)
  • id - Identifikátor historické verze - Klíč konkrétního záznamu evidence historie (ne číslo uživatele); odpovídá atributu id z odpovědi na list. (typ: number; nepovinný – nelze-li převést na číslo, výsledkem je prázdný <history-doc></history-doc> bez chyby)
  • opt-roles - Volitelná role - Přepíše pro tento document roli zděděnou z get-history/přihlášení. (typ: string; nepovinný)

Uzel nemá potomky.

Příklady požadavku​

(Zatím bez ověřeného příkladu; viz příklady historie dokumentů.)

Zpracování a vedlejší účinky​

  • Pro list: server ověří historické privilegium role a projde administrativní filtr; při úspěchu vrátí kompletní seznam historických záznamů dané instance, včetně těch bez privilegia/filtru tiše vrátí prázdný seznam.
  • Pro document: načte se konkrétní historická verze podle parametru id (historické histid), ne aktuální stav; platí stejný tichý vzor vynechání při chybějícím pohledu role nebo zamítnutí administrativním filtrem jako u get-document.
  • Neznámý typ/dkey (u list) nebo neznámý typ/dkey/id (u document) nezpůsobí chybu celého požadavku – jen se pro danou položku vygeneruje chybový, resp. prázdný element (viz „XML odpověď“ a „Chyby a reakce“).

XML odpověď (syntax + popis)​

Odpověď je posloupnost elementů history-list (jeden za každý list z požadavku) a history-doc (jeden za každý document z požadavku), v pořadí odpovídajícím pořadí potomků v požadavku, přímo jako potomci <response> – bez společné obálky.

  <response>
   <history-list
    type="error"
    detail="{string}"
    >
    <{fxd-doc-type}
     dkey="{number}"
     id="{number}"
     date="{string}"
     time="{string}"
     author="{number}"
     impersonate="{number}"
     version="{string}"
     hist-label="{string}"
     hist-date="{string}"
     hist-time="{string}"
     hist-optionA="{bool}"
     hist-optionB="{bool}"
     hist-key="{number}"
     hist-action-register="{number}"
     hist-action-node="{number}"
     /> *
   </history-list> *
   <history-doc>
    <{fxd-doc-type} dkey="{key}">...</{fxd-doc-type}> ?
    <error ... /> *
   </history-doc> *
  </response>

Parametry a pravidla (atributy, potomci) – odpověď​

Uzel history-list​

  • Úspěch (typ/dkey platné, privilegium i filtr prošly): <history-list> bez atributu type, obsahuje 0 a více potomků – jeden element za každou historickou verzi, jehož jméno je název dokumentového typu (fxd-doc-type), ne obecné history-list/item.
  • Bez privilegia/zamítnuto filtrem: <history-list></history-list> – prázdné, bez atributu type, tiše (ne chyba).
  • Neplatný typ/dkey: <history-list type="error" detail="Neplatny typ dokumentu nebo dkey"/> (self-closing).
  • Databázová chyba: <history-list type="error" detail="Pri provadeni doslo k chybe"> s možným vnořeným error a uzavírající </history-list>.

Atributy jednotlivého historického elementu ({fxd-doc-type}) – všechny kromě prvních pěti jsou přítomny jen, pokud byla odpovídající historická hodnota při uložení vyplněna:

  • dkey - PDK dokumentu. (typ: number)
  • id - Identifikátor historické verze - Klíč záznamu evidence historie. (typ: number)
  • date / time - Datum a čas historické změny (lokální čas). (typ: string)
  • author - Číslo uživatele, autora změny. (typ: number)
  • impersonate - Číslo uživatele, za kterého byla změna provedena (impersonace) - jen pokud byla uložena. (typ: number; nepovinný)
  • version - Verze dokumentu v době uložení. (typ: string)
  • hist-label, hist-date, hist-time, hist-optionA, hist-optionB, hist-key, hist-action-register, hist-action-node - Volitelné doplňkové údaje uložené k dané historické verzi požadavkem save-document (atributy hist-* na ukládaném dokumentu) - přítomny jen, byly-li při uložení vyplněny. (typy: string/string+string/bool/bool/number/number/number)

Uzel history-doc​

  • Vždy dvojice otevírací/uzavírací značka, nikdy self-closing a nikdy nenese vlastní atributy (ani type).
  • Neplatný typ/dkey/id: <history-doc></history-doc> – prázdné, tiše (ne chyba).
  • Databázová chyba při načítání: <history-doc> s vnořeným error a </history-doc>.
  • Bez pohledu role/zamítnuto filtrem: <history-doc></history-doc> – prázdné, tiše (stejný vzor jako get-document).
  • Úspěch: <history-doc><{fxd-doc-type} dkey="…">…</{fxd-doc-type}></history-doc> – obsah historické verze dokumentu vepsaný přímo jako svůj vlastní kmenový element.

Příklady odpovědi​

(Zatím bez ověřeného příkladu; viz příklady historie dokumentů.)

Chyby a reakce​

  • history-list[@type='error'] – detail="Neplatny typ dokumentu nebo dkey" (neplatný vstup) nebo detail="Pri provadeni doslo k chybe" (databázová chyba, s možným vnořeným error).
  • history-doc nemá vlastní chybový atribut; neúspěch se projeví buď tichým prázdným elementem, nebo vnořenými diagnostickými uzly error.
  • Výraz pro identifikaci diagnostické chyby v odpovědi: history-list[@type='error'] a history-doc[error].

Související požadavky​

  • get-document – čtení aktuální (nehistorické) verze dokumentu, sdílí mechanismus čtení s document potomkem tohoto požadavku.
  • get-pseudo-document – obdobné čtení pro pseudo-dokumenty.
  • save-document – uložení dokumentu, zdroj atributů hist-* zobrazovaných v historii.