Požadavek save-settings

Účel a dopady

Uloží (nebo smaže) blok XML dat pod daným typem nastavení, případně konkrétním tb-id/user, do databáze.

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

• Dostupné každému přihlášenému uživateli pro vlastní nastavení (user neuveden nebo roven vlastnímu ID).
• Je-li uveden cizí user, smí požadavek provést jen uživatel s r_admin nebo r_power.
• Bez ohledu na user vyžadují r_admin nebo r_power i typy nastavení public-root, corporate-root, public-table, corporate-table a jakýkoli typ začínající comex kromě přesně comex.user – tato ochrana chráněných typů v dosavadní dokumentaci chyběla.

XML požadavek (syntax + popis)

  <request>
   <save-settings
    type="{string}"
    tb-id="{number}"
    user="{number}"
    delete="{bool}"
    >
    {libovolný XML obsah}
   </save-settings>
  </request>

Parametry a pravidla (atributy, potomci)

• type - Typ nastavení - Název oblasti nastavení předávaný beze změny uložené proceduře; aplikační vrstva serveru hodnotu nijak neomezuje ani nevaliduje, ale řídí oprávnění (viz výše). (typ: string; nepovinný – chybí-li, předává se prázdný řetězec)
• tb-id - Identifikátor položky - Rozlišuje více položek téhož typu nastavení. (typ: number; nepovinný)
• user - Číslo uživatele - Uloží nastavení pod konkrétního uživatele. (typ: number; nepovinný)
• delete - Výmaz - Je-li "true", jde o požadavek na výmaz existující položky nastavení místo jejího zápisu. (typ: bool; nepovinný; výchozí: false)

Potomek: libovolný vnořený XML obsah uzlu <save-settings> je serverem vzat doslovně (bez validace struktury) a uložen jako obsah nastavení.

Význam prázdné a chybějící hodnoty

Je-li <save-settings> prázdný nebo sebeuzavírající (<save-settings .../>), předává se do databáze SQL NULL jako obsah nastavení – ne prázdný řetězec. Obsahuje-li uzel jakýkoli vnořený text/XML, předává se přesně tento obsah.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Obsahem k uložení je přesně to, co server najde mezi otevírací a uzavírací značkou <save-settings> po serializaci celého uzlu – žádná konkrétní vnitřní struktura (např. document-set) není serverem vyžadována ani kontrolována.
• Volá se uložená procedura pro zápis/výmaz nastavení; výsledný stav (type="ok"/"error") určuje jen návratová hodnota procedury, obsah samotný server jinak neinterpretuje.

XML odpověď (syntax + popis)

  <response>
   <save-settings
    type="ok|error"
    setting-type="{string}"
    tb-id="{number}"
    user="{number}"
    descr="{string}"
    />
  </response>

Příklady odpovědi

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

Chyby a reakce

• type="error" descr="Nemate opravneni ke zmene tohoto nastaveni" – oprávnění nesplněna, viz sekce Dostupnost.
• type="error" descr="Zapis nastaveni se nezdaril" – uložená procedura vrátila neúspěch.
• type="error" descr="Pri provadeni doslo k chybe" – selhání při volání databáze nebo procedury.

Atribut chybové odpovědi je descr (ne detail). Odpověď na rozdíl od get-settings nemá volitelnou obálku (envelope) – tvar <save-settings .../> je vždy stejný, sebeuzavírající, bez vloženého obsahu.

Související požadavky

• get-settings – čtení stejného typu dat.
• sql-query – další způsob práce s daty ve stejné skupině požadavků.