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

Požadavek save-document

Účel a dopady​

Uloží (vytvoří nebo změní) jeden nebo více flexideo dokumentů rozkladem XML do SQL databáze; volba mezi vytvořením a změnou je řízena tvarem atributu dkey (viz níže). Vedlejší účinky: zápis nové položky do evidence historie (hist-id) pro každý uložený dokument, dočasné zámky ukládaných (a referenčně souvisejících) dokumentů po dobu zpracování a – ukládá-li se dokument typu users – případná aktualizace přihlašovacího hashe a vynucení nového přihlášení dotčeného online uživatele.

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

  • Požadavek jako celek nevyžaduje žádné zvláštní privilegium (r_admin apod.); přístup se ověřuje samostatně pro každý ukládaný dokument: role musí mít právo zápisu k danému dokumentovému typu a u existujících dokumentů navíc projít administrativním filtrem.
  • Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)​

  <request>
   <save-document
    envelope="{bool}"
    id="{string}"
    transactional="{bool}"
    verbose="{bool}"
    opt-roles="{string}"
    >
    <{fxd-doc-type} ...>...</{fxd-doc-type}> *
   </save-document>
  </request>

Parametry a pravidla (atributy, potomci)​

  • envelope - Obalit odpověď - "true" obalí výsledné <save-result> elementy do kořenového <save-document> (viz „XML odpověď“); jinak (výchozí) se <save-result> elementy vrací přímo jako potomci <response>, bez obalového <save-document>. (typ: bool; nepovinný; výchozí: false)
  • id - Identifikátor korelace - Má význam, jen když envelope="true" – hodnota se beze změny echem přenese do <save-document id="…"> obálky odpovědi; jinak se nikde nepoužije. (typ: string; nepovinný)
  • transactional - Atomicita dávky - "true" vynutí uložení všech potomků v jedné transakci (selhání jednoho dokumentu vrátí zpět i ostatní); "false" vynutí nezávislé uložení každého potomka samostatně (selhání jednoho dokumentu neovlivní zápis ostatních). Nepřítomnost atributu ponechává rozhodnutí na konfiguraci serveru. Jde o vlastní atribut tohoto uzlu, ne o obecnou vlastnost obálky <request>, i když má stejné jméno. (typ: bool; nepovinný; výchozí: dle konfigurace serveru)
  • verbose - Podrobná odpověď - "true" doplní každý úspěšný <save-result> o obsah právě uloženého dokumentu (viz níže v roli volajícího). (typ: bool; nepovinný; výchozí: false)
  • opt-roles - Volitelná role - Jediná role pro celý požadavek (na rozdíl od get-document zde není podpora přepsání role u jednotlivých potomků). (typ: string; nepovinný)

Potomek: libovolný počet kořenových elementů ukládaných dokumentů; jméno každého je název dokumentového typu (fxd-doc-type) definovaného v XDS. Vnitřní strukturu (pole, oblasti/segmenty) určuje XDS – viz segmenty a metadata dokumentů a příklady save-document.

Atributy kořenového elementu ukládaného dokumentu​

  • dkey - Klíč dokumentu - Číselný klíč existující instance (aktualizace), nebo hodnota začínající znakem # pro založení nové instance (libovolný text za # slouží jen jako korelační token, echoem vrácený v orig-dkey). Hodnota, která nezačíná # a nelze ji převést na číslo, vede k chybě dané položky. (typ: string; nepovinný – chybějící se chová jako neplatná hodnota, viz „Chyby a reakce“)
  • custom-flag - Vlastní příznak - Libovolný řetězec beze změny echem vrácený v <save-result custom-flag="…">; server jej jinak nijak nezpracovává. (typ: string; nepovinný)
  • hist-label - Popisek historické verze - Uloží se k historickému záznamu tohoto uložení. (typ: string; nepovinný, omezená délka)
  • hist-key - Historický klíč - Číselná hodnota uložená k historickému záznamu. (typ: number; nepovinný)
  • hist-optionA - Historický příznak A - "true" nastaví příznak A na true. Pozorované chování: hodnota jiná než "true" nenastaví příznak A zpět na false (jak by se čekalo), místo toho nastaví na false příznak B (hist-optionB). (typ: bool; nepovinný)
  • hist-optionB - Historický příznak B - "true"/jiná hodnota nastaví příznak B na true/false. (typ: bool; nepovinný)
  • hist-date - Historické datum - Uloží se k historickému záznamu, jen pokud jde o platný datový/časový formát. (typ: datetime; nepovinný)
  • hist-recurse - Pozorované chování: atribut se sice čte, ale bez ohledu na hodnotu zůstává nastavení false; atribut tedy aktuálně nemá žádný pozorovatelný efekt. (typ: bool; nepovinný; bez efektu)
  • hist-action-register - Historický akční registr - Číselná hodnota uložená k historickému záznamu. (typ: number; nepovinný)
  • hist-action-node - Historický akční uzel - Číselná hodnota uložená k historickému záznamu. (typ: number; nepovinný)

Příklady požadavku​

(Zatím bez ověřeného příkladu; viz příklady save-document a segmenty a metadata dokumentů.)

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

  • Server nejprve pro každý potomek ověří: rozpoznání dokumentového typu podle jména elementu, právo zápisu role k danému typu, formát dkey (existující číslo, nebo nová instance přes #), a u existujících dokumentů jejich existenci a průchod administrativním filtrem. Selže-li cokoli z toho pro některý dokument, všechny další dosud nezpracované dokumenty v téže dávce se označí jako „Neprovaden z duvodu vraceni transakce“ a k žádnému zápisu nedojde.
  • Projdou-li všechny dokumenty přípravnou fází, server je seřadí podle vzájemných závislostí (referencí), zamkne je (s opakovanými pokusy a krátkým čekáním při dočasné kolizi zámků) a nechá projít validaci na úrovni dokumentové třídy (analyzeRequest), teprve pak fyzicky zapíše do databáze – jde o netriviální, na zámcích a pořadí závislý mechanismus, jehož každý dílčí krok má vlastní chybový text (viz „Chyby a reakce“).
  • transactional="true" / "false" na <save-document> řídí, zda je tento vícekrokový mechanismus spuštěn jednou pro celou dávku (atomicky), nebo samostatně pro každý dokument – při nezávislém zpracování může část dokumentů v odpovědi uspět a část selhat.
  • Při úspěšném zápisu dokumentu server přidělí hist-id (číslo záznamu evidence historie); je-li verbose="true", do úspěšného <save-result> se navíc vloží obsah právě uloženého dokumentu v rozsahu dostupném roli volajícího.
  • Selže-li připojení k databázi (nebo k archivní databázi) před zpracováním, generuje se pro každý potomek <save-result type="error" doc-type="…" dkey="…" orig-dkey="…" detail="Chyba spojeni s databazi">, případně detail="Transakce byla preskocena/odvolana", je-li to způsobeno transakčním přeskočením obálky.

XML odpověď (syntax + popis)​

Bez envelope (výchozí stav):

  <response>
   <save-result
    type="ok|error"
    doc-type="{string}"
    dkey="{string}"
    orig-dkey="{string}"
    custom-flag="{string}"
    hist-id="{number}"
    detail="{string}"
    >
    <error ... /> ?
   </save-result> *
  </response>

S envelope="true":

  <response>
   <save-document
    id="{string}"
    >
    <save-result ... /> *
   </save-document>
  </response>

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

  • type - Výsledek - ok/error za daný dokument. (typ: enum; povolené hodnoty: ok, error)
  • doc-type - typ dokumentu - Název dokumentové třídy (malými písmeny). (typ: string)
  • dkey - PDK dokumentu - U úspěšně založeného nového dokumentu nově přidělené číslo; jinak echo požadovaného dkey. (typ: string)
  • orig-dkey - Původní klíč - Doslovný text dkey z požadavku (užitečné zejména u nových instancí se znakem #). (typ: string)
  • custom-flag - Vlastní příznak - Echo document/@custom-flag z požadavku; přítomen, jen pokud byl v požadavku uveden. (typ: string; nepovinný)
  • hist-id - Číslo historického záznamu - Přítomno jen při úspěchu (type="ok"). (typ: number; nepovinný)
  • detail - Popis chyby - Přítomen jen při type="error". (typ: string; nepovinný)

Potomek error (sdílený typ error) se objevuje u chybových větví, které vznikají při skutečném volání databáze; čistě validační chyby (neznámý typ, neplatné dkey, chybějící oprávnění) jsou sebeuzavírající bez vnořeného error.

Příklady odpovědi​

(Zatím bez ověřeného příkladu; viz příklady save-document a identifikace chyb při ukládání dokumentů.)

Chyby a reakce​

Texty atributu detail skutečně generované tímto požadavkem:

  • "Neplatny typ dokumentu" – jméno kořenového elementu neodpovídá žádné známé dokumentové třídě.
  • "Uzivatel nema opravneni k pristupu k dokumentu" – role nemá právo zápisu k dokumentovému typu.
  • "Nepodarilo se rozpoznat dkey" – dkey nezačíná # a nelze jej převést na číslo.
  • "Dokument neexistuje" – dokument s daným dkey nebyl nalezen.
  • "Pri nacitani doslo k chybe" – databázová chyba při načítání existujícího dokumentu (s vnořeným error).
  • "Pri overovani admin filtru doslo k chybe" – databázová chyba při ověřování administrativního filtru (s vnořeným error).
  • "K dokumentu nemate pristup" – administrativní filtr zamítl přístup k existujícímu dokumentu.
  • "Dokument nelze zalozit" – založení nové instance selhalo.
  • "Neprovaden z duvodu vraceni transakce" – dokument nebyl vůbec zpracován, protože jiný dokument ve stejné dávce selhal dřív (placeholder, přepisuje se konečným výsledkem, pokud k jeho zpracování přesto dojde).
  • "Ulozeni dokumentu bylo odvolano z duvodu vraceni transakce" – dokument byl úspěšně připraven k zápisu, ale celá transakce byla nakonec vrácena kvůli chybě jinde v dávce.
  • "Pri ukladani doslo k chybe" – finální databázový zápis dokumentu selhal (s vnořeným error).
  • "Chyba spojeni s databazi" – nepodařilo se připojit k databázi/archivní databázi před zpracováním.
  • "Transakce byla preskocena" / "Transakce byla odvolana" – požadavek byl vyřazen standardním transakčním zpracováním obálky.

Výraz pro identifikaci chyb v odpovědi serveru: save-result[@type='error'].

Související požadavky​