Požadavek do-manage

Účel a dopady

Naplánuje na serveru údržbovou úlohu (obnovení pokusů o optimalizaci nedostupných souborů, výmaz logu běhu úloh, výmaz logu API požadavků, výmaz konceptů, výmaz zpráv, výmaz registrů, výmaz souborů, výkonnostní test a/nebo výmaz výkonnostního logu) – nejde o okamžité provedení, požadavek jen vytvoří novou položku v plánovači serveru (cron), která se spustí podle pravidel plánování (validity/repeat). Vedlejší efekt: úspěšné vytvoření zapisuje novou úlohu do databáze plánovače.

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

• Uzel patří do rodiny uzlů s prefixem do-, které server plánuje jako úlohy cron; sdílí společný dispatch s do-import, do-export, do-scan-files, do-optimize-files aj..
• Smí použít uživatel s r_admin nebo r_manage (na rozdíl od dosavadní dokumentace, která u příbuzných požadavků zmiňovala jen administrátorské oprávnění) – jinak je požadavek zamítnut.
• 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>
   <do-manage
    validity="{string}"
    repeat="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    failsafe="{string}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    revive-optimization="{bool}"
    perf="{bool}"
    perf-threshold="{number}"
    del-job-log="{bool}"
    del-api-log="{bool}"
    del-drafts="{bool}"
    del-perf-log="{bool}"
    del-messages="{bool}"
    del-registers="{bool}"
    del-files="{bool}"
    reload-identities="{bool}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

Atributy validity, repeat, sched-from-end, when-off, failsafe mají stejný význam a syntaxi jako u sdíleného typu do-task. Server u téhož uzlu navíc čte i tři obecné plánovací atributy, které sdílený typ do-task v současné podobě nepopisuje: run-as (typ: number; nepovinný; spustí úlohu jménem jiného uživatele – vyžaduje r_impersonate/r_admin a projde stejnou kontrolou zastupování jako přihlášení), by-action (typ: bool; nepovinný) a db-log (typ: bool; nepovinný; zapíná zápis logu běhu úlohy do databáze).

Vlastní atributy uzlu do-manage:

• revive-optimization - Obnovit optimalizaci - Obnoví pokusy o optimalizaci souborů, ke kterým se při dřívější optimalizaci nepodařilo získat přístup. (typ: bool; nepovinný)
• perf - Výkonnostní test - Provede výkonnostní test a uloží jeho výsledek do databáze. (typ: bool; nepovinný)
• perf-threshold - Stáří výkonnostního logu - Použije se jen společně s del-perf-log; záznamy starší než tato hodnota (v sekundách) se smažou. Pozor, jméno atributu je perf-threshold, ne perf-log-threshold jako v dosavadní dokumentaci. (typ: number; nepovinný; výchozí: 2592000 = 30 dní)
• del-job-log - Výmaz logu úloh - Smaže záznamy v logu běhu naplánovaných úloh. (typ: bool; nepovinný)
• del-api-log - Výmaz API logu - Smaže záznamy v logu API požadavků. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: bool; nepovinný)
• del-drafts - Výmaz konceptů - Smaže uložené koncepty dokumentů. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: bool; nepovinný)
• del-perf-log - Výmaz výkonnostního logu - Smaže záznamy výkonnostních testů starší než perf-threshold. (typ: bool; nepovinný)
• del-messages - Výmaz zpráv - Smaže uživatelské zprávy. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: bool; nepovinný)
• del-registers - Výmaz registrů - Smaže záznamy registrů. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: bool; nepovinný)
• del-files - Výmaz souborů - Smaže soubory. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: bool; nepovinný)
• reload-identities - Přenačtení autovalues - Pozorované chování (vypadá jako chyba serveru): atribut reload-identities="true" fakticky jen znovu spouští výmaz výkonnostního logu a nemá vlastní pozorovatelný efekt. Je zde popsán bez opravy. (typ: bool; nepovinný)

Atribut job-log-threshold z dosavadní dokumentace není podporován – výmaz logu úloh (del-job-log) nemá žádný parametr stáří čtený z tohoto uzlu.

Závislosti

• Musí být nastaven aspoň jeden z akčních příznaků (revive-optimization, perf, del-job-log, del-api-log, del-drafts, del-perf-log, del-messages, del-registers, del-files, reload-identities) na "true"; nejsou-li nastaveny žádné, server úlohu odmítne vytvořit jako neznámou a vrátí generickou chybu vkládání (viz „Chyby a reakce“).

Příklady požadavku

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

Zpracování a vedlejší účinky

• Server nejprve ověří oprávnění (r_admin nebo r_manage); bez něj se žádná úloha nevytvoří.
• Server poté vytvoří úlohu z uzlu požadavku. Selže-li rozpoznání validity/repeat/failsafe/perf-threshold (neplatná syntaxe či hodnota) nebo nejsou nastaveny žádné akční příznaky, úloha se nevytvoří.
• Uspěje-li vytvoření, úloha se zapíše do databáze plánovače a zařadí do fronty serveru. Samotné akce (výmazy, výkonnostní test) proběhnou až později, v čase daném plánováním (validity/repeat), ne synchronně v rámci tohoto požadavku – odpověď proto nenese výsledek provedení, jen potvrzení naplánování.
• del-job-log/del-api-log/del-drafts navíc při vlastním spuštění úlohy respektují globální konfigurační přepínače serveru. Je-li příslušný přepínač vypnutý, k výmazu při běhu úlohy nedojde, ačkoli byla úloha úspěšně naplánována.

XML odpověď (syntax + popis)

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

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

• status - Výsledek - "ok" při úspěšném naplánování, jinak "error" (nebo "skip" při přeskočené transakci). (typ: enum; povolené hodnoty: ok, error, skip)
• id - Id úlohy - Identifikátor nově vytvořené úlohy v plánovači, přítomen jen při status="ok". (typ: number)
• next-run - Čas dalšího spuštění - Datum a čas (YYYY-MM-DD HH:MM:SS) příštího plánovaného spuštění, přítomen jen při status="ok". Tento atribut dosavadní dokumentace vůbec nezmiňovala. (typ: datetime)
• detail - Popis chyby - Přítomen jen při status="error"/"skip". (typ: string; nepovinný)

Příklady odpovědi

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

Chyby a reakce

• <do-manage status="ok" id="…" next-run="…"/> – úloha byla úspěšně naplánována.
• <do-manage status="error" detail="Systemova chyba pri vkladani pozadavku"/> – vytvoření úlohy selhalo (neplatná syntaxe validity/repeat/failsafe/perf-threshold, nebo nebyl nastaven žádný akční příznak).
• <do-manage status="error" detail="Nemate patricna opravneni"/> – volající nemá r_admin ani r_manage.
• <do-manage status="error" detail="Transakce byla odvolana"/> / <do-manage status="skip" detail="Transakce byla preskocena"/> – požadavek byl vyřazen standardním transakčním zpracováním obálky.
• Odpověď typu do-task-result z dosavadní dokumentace (bez next-run) neodpovídá přesně tomu, co server vrací – sdílený typ do-task-result next-run v současné podobě nepopisuje. Výraz pro identifikaci chyb v odpovědi serveru: do-manage[@status='error'].

Související požadavky

• do-optimize-files, do-scan-files – další úlohy plánované stejným mechanismem do-.
• service – přímé (neplánované) ovládání běhu interních služeb serveru.
• undo – zrušení naplánované/opakující se úlohy podle id vráceného touto odpovědí.