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

Požadavek set-metadata

Účel a dopady​

Zapíše jen metadata (meta hodnoty) vybraných dokumentů a jejich opakovatelných segmentů, bez nutnosti posílat celý obsah dokumentu jako u save-document. Vedlejší účinky: zápis do databáze v rámci jedné transakce pro celý požadavek (všechny dokumenty i segmenty najednou) a vyčištění mezipaměti dotazů při úspěchu.

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

  • Dostupné každému přihlášenému uživateli; přístup k zápisu konkrétní meta hodnoty je řízen právem zápisu role na dané pole a administrativním filtrem na úrovni segmentu – viz „Chyby a reakce“.
  • 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.
  • Chybová odpověď transakčního přeskočení obálky používá jiný chybový atribut než běžná chybová odpověď tohoto požadavku: status, zatímco běžná odpověď set-metadata používá type – viz „XML odpověď“ a „Chyby a reakce“ (obdobný rozdíl type/status jako u update-files).

XML požadavek (syntax + popis)​

  <request>
   <set-metadata
    opt-roles="{string}"
    >
    <document ... /> *
   </set-metadata>
  </request>

Parametry a pravidla (atributy, potomci)​

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

Potomek: server zpracuje jen přímé potomky doslova pojmenované document; ostatní přeskočí.

Uzel document​

  <document
   type="{string}"
   dkey="{number}"
   opt-roles="{string}"
   >
   <meta ... /> *
   <segment ... /> *
  </document>
  • type - typ dokumentu - Typový název dokumentu definovaného v XDS. (typ: string; nepovinný – neznámý typ vede k chybě 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 chybě této položky)
  • opt-roles - Volitelná role - Přepíše pro tento document roli zděděnou z set-metadata/přihlášení. (typ: string; nepovinný)

Uzel meta​

  <meta
   name="{string}"
   value="{string}"
   />
  • name - Název meta prvku - Musí odpovídat meta prvku definovanému u dokumentu (histarray) dané role; jinak vede k chybě dané položky. (typ: string; nepovinný – chybějící/neznámý název vede k chybě této položky)
  • value - Nová hodnota - Chybí-li value, ale prvek povoluje NULL, zapíše se NULL; chybí-li a prvek má výchozí hodnotu, použije se ta; jinak (žádná z možností) je to chyba. Konverze hodnoty na SQL literál (dle datového typu pole) může selhat a je také chybou dané položky. (typ: string; nepovinný)

Uzel segment​

  <segment
   array="{number}"
   skey="{number}"
   >
   <meta ... /> *
  </segment>
  • array - Identifikátor XDS oblasti - Číselný XDS identifikátor opakovatelné (basic) oblasti dokumentu, ve které leží zapisovaná meta pole. (typ: number; nepovinný – chybějící/nečíselný vede k chybě této položky)
  • skey - Klíč segmentu - Primární klíč konkrétní instance segmentu v dané oblasti. (typ: number; nepovinný – chybějící/nečíselný vede k chybě této položky)

Potomek meta má stejný tvar jako přímý potomek document, jen cílí na pole dané opakovatelné oblasti místo kmene dokumentu. Segmenty lze vnořit jen jednu úroveň pod document; musí jít o přímou basic oblast dokumentu.

Příklady požadavku​

(Zatím bez ověřeného příkladu.)

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

  • Server nejdřív pro každý document sestaví přehled požadovaných změn bez zápisu do databáze – ověří oprávnění role k zápisu na každé zapisované pole i administrativní filtr na úrovni segmentu. Teprve když projdou všechny dokumenty a segmenty v celém požadavku, spustí se jediná transakce a provede všechny změny. Selže-li přípravná fáze pro jakýkoli dokument, segment nebo pole, transakce se vůbec nezahájí a nic se nezapíše.
  • Selže-li v prováděcí fázi zápis konkrétního dotazu do databáze, zbylé již spuštěné/nespuštěné dotazy v dávce se buď označí jako "vráceny z důvodu následné chyby", nebo (pro dotazy před chybou) uspěly, ale celá transakce se přesto vrátí zpět – zápis je tedy typu vše, nebo nic pro celý požadavek najednou (na rozdíl od save-document, kde lze zvolit nezávislé zpracování jednotlivých dokumentů).
  • Prázdný meta/segment blok (žádná skutečná změna pole) vede k prázdnému SQL UPDATE dotazu, který se přeskočí beze změny stavu.
  • Nemá-li role přístup k segmentu (administrativní filtr zamítne), zpracování daného segmentu selže jako chyba.
  • Připojení k databázi se ověřuje jen jednou na začátku celého požadavku; selže-li, žádný dokument se nezpracuje.

XML odpověď (syntax + popis)​

  <response>
   <set-metadata
    type="ok|error"
    detail="{string}"
    >
    <document
     dkey="{number}"
     name="{string}"
     type="ok|error"
     detail="{string}"
     >
     <segment
      array="{string}"
      skey="{string}"
      type="ok|error"
      detail="{string}"
      /> *
    </document> *
   </set-metadata>
  </response>

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

  • Kořenový set-metadata nemá atribut dkey (na rozdíl od starší dokumentace) – nese jen type (ok/error za celý požadavek) a při type="error" navíc detail s obecným shrnutím (viz „Chyby a reakce“).
  • Potomek document (jeden za každý document z požadavku, ve stejném pořadí) nese dkey (echo z požadavku), name (echo document/@type z požadavku – pozor, jmenuje se name, ne type, jako jediný výskyt v tomto protokolu), vlastní type (ok/error) a při chybě detail.
  • Potomek segment (uvnitř document, jeden za každý segment z požadavku) nese array/skey (echo z požadavku), vlastní type a při chybě detail.
  • Element meta se v odpovědi vůbec nezobrazuje samostatně – jeho úspěch/neúspěch se promítá jen do type/detail nadřazeného document/segment.
  • Odpověď je vždy buď celá „ok“, nebo celá „error“ (viz „Zpracování“): při úspěchu (type="ok") obsahuje jen document/segment uzly s type="ok"; při neúspěchu (type="error") obsahuje document/segment uzly, kde ty, které samy selhaly, nesou vlastní konkrétní detail, a ty, které byly jen zasaženy neúspěchem jinde v dávce, nesou generický detail (viz „Chyby a reakce“).

Příklady odpovědi​

(Zatím bez ověřeného příkladu.)

Chyby a reakce​

Chyby na úrovni celého požadavku (set-metadata/@type="error"):

  • detail="S databazi se nepodarilo spojit" – sebeuzavírající tvar pro set-metadata samotný, ale vnitřně může obsahovat diagnostiku.
  • detail="Transakce vracena" – aspoň jeden dotaz v dávce selhal, celá transakce se vrátila zpět.
  • detail="Nepodarilo se zahajit transakci" – self-closing.
  • detail="Transakce nezahajena" – přípravná fáze selhala už před pokusem o zahájení transakce (neplatný dokument/pole/segment).

Chyby na úrovni jednoho document (detail texty jsou doslovné):

  • "Neplatne dkey" – dkey nelze převést na číslo.
  • "Neplatna role uzivatele" – optRole mimo rozsah definovaných rolí dokumentu.
  • "Neznamy dokument" – type neodpovídá žádné známé dokumentové třídě.
  • "Pristup k prvku byl odepren" – oprávnění role na dané meta pole nedovoluje zápis.
  • "Upravovany prvek neni meta prvek" – pojmenované pole existuje, ale není meta prvek.
  • "Upravovany meta prvek nebyl nalezen" – neznámé jméno meta/@name.
  • "Hodnota meta prvku neni platna" – hodnota meta/@value se nepodařilo převést na SQL literál dle typu pole.
  • "Nebyla uvedena hodnota meta prvku" – value chybí a pole nemá NULL/výchozí hodnotu.
  • "Operace vracena z duvodu nasledne chyby" / "Operace vracena z duvodu drivejsi chyby" – tento konkrétní zápis samotný uspěl (nebo byl prázdný), ale celá transakce byla vrácena kvůli chybě jinde v dávce.
  • "Pri zapisu do databaze doslo k chybe" – tento konkrétní UPDATE dotaz sám selhal na úrovni databáze.

Chyby na úrovni jednoho segment:

  • "Segment neobsahuje povinna pole" – chybějící/nečíselné array/skey.
  • "Dokument neobsahuje specifikovanou basic oblast" – array neodpovídá basic oblasti dokumentu.
  • "Segment je pro uzivatele nepristupny" – administrativní filtr zamítl přístup (zapisuje se i interní log 1002004).
  • "Operace neprovedena z duvodu nasledne/drivejsi chyby" – placeholder text, který se běžně přepíše jedním z výše uvedených, pokud zpracování segmentu vůbec proběhne.

Chyba transakčního přeskočení obálky:

  • <set-metadata status="error" detail="Transakce byla odvolana"/> / <set-metadata status="skip" detail="Transakce byla preskocena"/>.

Výraz pro identifikaci chyb v odpovědi serveru: set-metadata[@type='error'] pro běžnou chybu, set-metadata[@status='error' or @status='skip'] pro transakční přeskočení.

Související požadavky​