Požadavek action

Účel a dopady

Spustí registrovanou transformační/SOAP akci (nastavenou jako služba) přímo v rámci běžného XML požadavku, bez nutnosti volat ji přes samostatné SOAP rozhraní. Konkrétní vedlejší účinky závisí na volané akci samotné (může měnit data, spouštět transformace apod.) – server na této úrovni jen předá volání do interního SOAP dispatcheru.

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

• Dostupné každému přihlášenému uživateli; konkrétní oprávnění k volání dané akce řeší samostatné zpracování SOAP.
• Atribut run-as umožňuje zavolat akci jménem jiného uživatele (systémová autentizace). Smí jej použít jen uživatel s r_admin, nebo s r_impersonate, pokud smí daného uživatele zastupovat; jinak je požadavek zamítnut.
• Je-li aktuální session sama impersonovaná, run-as navíc vůbec nelze použít.
• Atribut debug má efekt jen tehdy, je-li na serveru globálně povolen.
• 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>
   <action
    name="{string}"
    call-type="{string}"
    run-as="{number}"
    opt-roles="{string}"
    debug="{bool}"
    >
    <{soap-envelope} ... > ... </{soap-envelope}> ?
   </action>
  </request>

Parametry a pravidla (atributy, potomci)

• name - Název akce - Musí odpovídat registru akcí; při soap volání je tento název součástí URL volané služby. (typ: string; nepovinný – chybí-li, požadavek skončí chybou Nezname jmeno akce)
• call-type - Typ spuštění akce - Stává se součástí interní URL cesty volané služby (/{call-type}/{name}, nebo //{name}, není-li uveden). Server hodnotu nevaliduje proti konkrétnímu výčtu; konvenční hodnoty (table/form/service) a jejich význam popisuje schéma run-action. (typ: string; nepovinný)
• run-as - Volání jménem jiného uživatele - Číslo uživatele, jehož jménem se má akce zavolat; viz omezení v sekci Dostupnost výše. Je-li rovno ID volajícího, žádné zvláštní zpracování se neuplatní. (typ: number; nepovinný)
• opt-roles - Volitelná role - Přepíše roli použitou při volání SOAP služby. Prázdný řetězec se chová jako neuvedeno. (typ: string; nepovinný; výchozí: role volajícího)
• debug - Ladicí režim volání - Uplatní se jen je-li zároveň povoleno na serveru; přesná hodnota "true" aktivuje ladicí režim SOAP volání. (typ: bool; nepovinný; výchozí: false)

Potomek: libovolný jeden element (nepovinný), typicky SOAP Envelope ze jmenného prostoru http://schemas.xmlsoap.org/soap/envelope/. Server serializuje celý obsah uzlu action mezi jeho otevírací a uzavírací značku a předává jej jako tělo SOAP volání; chybí-li potomek, tělo volání je prázdné.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklad spuštění akce.)

Zpracování a vedlejší účinky

• Sestaví se interní URL /{call-type}/{name} (nebo //{name}) a volání se předá službě SOAP.
• Je-li zadán run-as odlišný od volajícího, provede se nejprve systémová autentizace cílového uživatele; při neúspěchu nebo nedostatečném oprávnění se požadavek ukončí chybou dřív, než dojde na volání akce samotné.
• Otevírací značka odpovědi (<action type="ok">, nebo <action type="error" detail="Pri provadeni doslo k chybe">) se vytváří až po volání služby SOAP; podle jeho výsledku server rozhodne, zda jde o „ok“, nebo „error“. Obsah odpovědi SOAP (typicky Envelope/Body/Fault) je vždy vložen mezi tuto otevírací a uzavírací značku </action>, bez ohledu na výsledek.

XML odpověď (syntax + popis)

  <response>
   <action
    type="ok|error"
    detail="{string}"
    >
    <{soap-envelope} ... > ... </{soap-envelope}> ?
   </action>
  </response>

Příklady odpovědi

(Zatím bez ověřeného příkladu; viz příklad spuštění akce.)

Chyby a reakce

Čtyři chyby vznikají ještě před voláním SOAP dispatche a jsou vždy sebeuzavírající (bez potomků):

• type="error" detail="Nemate opravneni volat sluzbu jmenem uzivatele '{run-as}'." – run-as bez potřebného oprávnění zastupovat cílového uživatele.
• type="error" detail="Neplatny uzivatel '{run-as}'." – autentizace cílového uživatele z run-as selhala.
• type="error" detail="Impersonate uzivatel nemuze volat jmenem jineho uzivatele." – volající je sám impersonovaný a zároveň použil run-as.
• type="error" detail="Nezname jmeno akce" – chybí atribut name.

Dvě další chyby vznikají už při/po volání SOAP dispatche:

• type="error" detail="Neznamy zpusob volani." – služba SOAP nerozpoznala cíl volání; odpověď je sebeuzavírající.
• type="error" detail="Pri provadeni doslo k chybe" – volání SOAP skončilo neúspěchem; uzel není sebeuzavírající – obsahuje cokoli, co služba SOAP do odpovědi stihla zapsat (ne standardní vnořený uzel error).

Výraz pro identifikaci chyb: action[@type='error'].

Související požadavky

• do-action – totéž volání odloženě nebo opakovaně.
• run-action – popis vnitřního protokolu volaných akcí (obsah předávaný jako tělo SOAP volání).