Požadavek do-action

Účel a dopady

Naplánuje spuštění SOAP akce (viz rozhraní soap) jako úlohu cronu – jednorázově nebo opakovaně. Požadavek jen zaeviduje úlohu a vrací se okamžitě; skutečné volání akce proběhne asynchronně při běhu úlohy. To, co do-action umožňuje odloženě, provádí okamžitě požadavek action se stejnou strukturou.

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

• Vyžaduje aktivovanou vlastnost uživatele p_doaction (interně roli r_action) nebo p_admin (r_admin).
• Nastavit repeat/failsafe na cokoli jiného než none/prázdné vyžaduje navíc r_repeat nebo r_admin.
• SOAP volání s debug="true" je aktivní jen tehdy, povoluje-li to konfigurace serveru – jinak se atribut tiše ignoruje.
• Podléhá standardnímu transakčnímu zpracování obálky <request>.

XML požadavek (syntax + popis)

  <request>
   <do-action
    validity="{string}"
    repeat="{string}"
    failsafe="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    name="{string}"
    call-type="{string}"
    action-name="{string}"
    opt-roles="{string}"
    debug="{bool}"
    >
    <{libovolné tělo SOAP volání}> ?
   </do-action>
  </request>

Parametry a pravidla (atributy, potomci)

Plánovací atributy (validity, repeat, failsafe, sched-from-end, when-off, run-as, by-action, db-log) mají stejný význam jako u do-export – viz sdílený typ do-task (v době revize bez run-as/by-action/db-log).

Vlastní atributy:

• name - Název akce/úlohy - Použit i jako job/@name v job-list. (typ: string; povinný – chybí-li, úloha se vůbec nezaloží)
• call-type - Typ volání - service|table|form, viz technický popis akcí. (typ: string; povinný)
• action-name - Název akce v cestě volání - Přepíše name jen pro sestavení cesty /soap/{call-type}/{action-name}; name samo se přitom dál používá jako název úlohy. (typ: string; nepovinný; výchozí: hodnota name) – v dosavadní dokumentaci zcela chyběl.
• opt-roles - Volitelná role pro provedení akce. (typ: string; nepovinný) – v dosavadní dokumentaci chyběl.
• debug - Zapne ladicí výstup SOAP volání - Účinné jen je-li to povoleno konfigurací serveru. (typ: bool; nepovinný; výchozí: false) – v dosavadní dokumentaci chyběl.

Potomek: nepovinné tělo, které se stane tělem POST části SOAP volání (obdoba run-action, viz vnitřní protokol).

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklad do-action.)

Zpracování a vedlejší účinky

• Chybí-li name nebo call-type, nebo se z nich nepodaří sestavit platné SOAP volání, založení úlohy selže – bez rozlišení konkrétní příčiny v odpovědi (viz Chyby a reakce).
• Skutečné volání SOAP akce proběhne až při běhu úlohy (asynchronně), ne v okamžiku přijetí požadavku.

XML odpověď (syntax + popis)

  <response>
   <do-action
    status="ok|error"
    id="{number}"
    next-run="{string}"
    detail="{string}"
    />
  </response>

Kořenový element odpovědi má vždy stejný název jako uzel požadavku (do-action) – popis obsahu viz sdílený typ do-task-result (v době revize bez next-run).

• status - ok, pokud byla úloha úspěšně založena, jinak error. (typ: enum: ok|error)
• id - Číslo přidělené serverem nové úloze. (typ: number; přítomen jen při status="ok")
• next-run - Nejbližší spuštění, formát YYYY-MM-DD HH:MM:SS. (typ: datetime; přítomen jen při status="ok")
• detail - Popis chyby. (typ: string; přítomen jen při status="error")

Příklady odpovědi

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

Chyby a reakce

• status="error" detail="Nemate patricna opravneni" – volající nemá r_action ani r_admin.
• status="error" detail="Systemova chyba pri vkladani pozadavku" – jednotná chyba pro všechny ostatní případy selhání založení úlohy (chybějící name/call-type, neplatné SOAP volání, chyba zápisu do databáze) – na rozdíl od do-export zde není žádné jemnější rozlišení příčiny.
• status="skip" detail="Transakce byla preskocena" / status="error" detail="Transakce byla odvolana" – transakční přeskočení/odvolání obálky.

Související požadavky

• action – okamžité provedení stejné struktury bez odkládání.
• job-list, undo.