Požadavek do-import

Účel a dopady

Naplánuje importní úlohu, která podle typu dokumentu doc-type načte data (ze souborů v importní složce, nebo z dat přiložených přímo v požadavku) a uloží je do databáze. Požadavek samotný jen zaeviduje úlohu do plánovače (cronu) a vrací se okamžitě – skutečný import proběhne asynchronně v jiném vlákně, případně opakovaně dle repeat. Vedlejší účinky: založení záznamu naplánované úlohy (typicky perzistovaného v databázi), později (při běhu úlohy) zápis importovaných dokumentů a log průběhu.

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

• Vyžaduje aktivovanou vlastnost uživatele p_import (interně roli r_import) nebo p_admin (r_admin).
• Nastavit repeat nebo failsafe na jinou hodnotu než none/prázdnou vyžaduje navíc p_repeat (r_repeat) nebo r_admin.
• Atribut run-as (naplánování úlohy ke spuštění pod jiným uživatelem) vyžaduje r_admin, nebo r_impersonate u volajícího a úspěšné ověření vůči cílovému uživateli.
• Server oprávnění ověřuje znovu při každém skutečném spuštění úlohy (i při opakování) – pokud je uživatel mezitím ztratí nebo je smazán, běh selže bez dalšího zásahu klienta.
• Podléhá standardnímu transakčnímu zpracování obálky <request> (přeskočení/odvolání transakce) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <do-import
    validity="{string}"
    repeat="{string}"
    failsafe="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    doc-type="{string}"
    rel-folder="{string}"
    file-mask="{string}"
    file-type="{string}"
    tran="{number}"
    attached-data="{bool}"
    >
    <column
     xds-id="{number}"
     /> +
    <data
     >
     <row ... /> *
    </data> ?
   </do-import>
  </request>

Parametry a pravidla (atributy, potomci)

Plánovací atributy sdílené s ostatními do-* požadavky

Základní tvar odpovídá sdílenému typu do-task; ten ale v době revize neuvádí run-as, by-action ani db-log (viz poznámka na konci této stránky). Skutečné chování:

• validity - Platnost úlohy - Řídí první spuštění. Rozpoznává once, today, still a výrazy s from-{#YYYY-MM-DD HH:MM:SS}/to-{#...} (podřetězcové hledání from-/to-, nikoli přesná shoda celé hodnoty). (typ: string; nepovinný; chybí-li, chová se jako okamžité jednorázové spuštění)
• repeat - Opakování - Syntaxe hourly|daily|weekly|monthly|yearly|from-...;to-...;each-nn-jednotka[-xx...];at-hh:mm; podrobná syntaxe viz Nastavení plánovače úloh. Nastavení na cokoliv jiného než none/prázdné vyžaduje r_repeat nebo r_admin, jinak je úloha odmítnuta jako neplatná. (typ: string; nepovinný; výchozí: bez opakování)
• failsafe - Opakování při chybě - Syntaxe stejné rodiny jako repeat (bez to- části); stejná privilegovaná podmínka jako repeat. (typ: string; nepovinný)
• sched-from-end - Plánování od konce běhu - Interval opakování se počítá od ukončení předchozího běhu, ne od jeho plánovaného startu. (typ: bool; nepovinný; výchozí: false)
• when-off - Doběhnutí po výpadku - Připadne-li plánovaný běh na dobu, kdy byl server vypnutý, spustí se po jeho obnovení. (typ: bool; nepovinný; výchozí: false)
• run-as - Zastoupení uživatele - Číslo uživatele, pod jehož identitou se má úloha spustit. Vyžaduje r_admin, nebo r_impersonate a úspěšný test zastoupení. Neplatná hodnota nebo nedostatečné oprávnění => úloha se vůbec nezaloží. (typ: number; nepovinný)
• by-action - Založeno akcí - Příznak, že úlohu založila jiná (řetězená) akce; promítá se do atributu job/@by-action v job-list. Přesný dopad na plánování mimo tento příznak není v této revizi upřesněn. (typ: bool; nepovinný; výchozí: false)
• db-log - Log úlohy do databáze - Zapíná průběžné ukládání dílčích log zpráv úlohy do databáze nad rámec standardního záznamu při dokončení/selhání. (typ: bool; nepovinný; výchozí: false)

Vlastní atributy do-import

• doc-type - Typ dokumentu - Název typu dokumentu definovaného v XDS (malá/velká písmena se nerozlišují); musí odpovídat existujícímu typu, jinak se úloha vůbec nezaloží. (typ: string; nepovinný syntakticky, prakticky nutný)
• rel-folder - Podsložka importní složky - Volitelná podsložka importní složky dle nastavení serveru. (typ: string; nepovinný)
• file-mask - Souborová maska - Např. *.csv; podle masky se v importní složce/podsložce hledají soubory k importu. Zároveň se tato hodnota stává názvem úlohy (atribut job/@name v job-list). (typ: string; nepovinný)
• file-type - Typ importu - Jediná rozpoznávaná hodnota je "csv" (case-insensitive); jakákoli jiná hodnota, včetně chybějící, znamená import XML. (typ: string; nepovinný; výchozí: xml; povolené hodnoty: xml, csv)
• tran - Transakčnost - 1 (řádek, bez transakčnosti), 2 (soubor = transakce), 3 (všechny soubory = jedna transakce). Je-li atribut uveden a hodnota není 1, 2 ani 3, úloha se vůbec nezaloží. (typ: number; nepovinný; výchozí: 2)
• attached-data - Data v požadavku - true znamená import z přiložených dat (row-import) místo ze souboru; v tom případě je potomek data povinný. (typ: bool; nepovinný; výchozí: false)

Uzel column

• Popisuje sloupec, který má být importován, v pořadí odpovídajícím pořadí sloupců v datech. Alespoň jeden column je vyžadován – bez něj se úloha vůbec nezaloží.
• xds-id - Identifikátor segmentu - Musí odpovídat existujícímu poli struktury doc-type; pole nesmí být typu soubor/obrázek ani vybrané interní referenční pole (ref) doplňkových/systémových tabulek – jinak se úloha vůbec nezaloží. (typ: number; povinný)

Uzel data a row

• data se čte pouze je-li attached-data="true"; je-li v tomto případě chybí, nebo obsah nelze rozparsovat (u CSV navíc musí počet sloupců odpovídat počtu column), úloha se vůbec nezaloží.
• row - jeden řádek importovaných dat; přesné pravidlo mapování atributů uzlu row na jednotlivé column (podle pořadí, podle názvu apod.) není v tomto rozsahu dokumentováno – otevřený bod.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz ukázky importu.)

Zpracování a vedlejší účinky

• Založení úlohy vyžaduje, aby server měl synchronizovanou strukturu dat; jinak se úloha vůbec nezaloží.
• Vlastní čtení souborů/importních dat probíhá až při skutečném běhu úlohy (asynchronně, případně opakovaně), ne v okamžiku přijetí požadavku – odpověď proto potvrzuje jen zaevidování úlohy, ne výsledek importu.
• Text požadavku (celý uzel do-import včetně potomků) se serializuje a ukládá k naplánované úloze v databázi, pokud jde o novou (nikoli znovunačtenou) úlohu.

XML odpověď (syntax + popis)

  <response>
   <do-import
    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-import), ne do-task-result – ten je jen typový popis tvaru atributů, viz sdílený typ do-task-result (pozor: tento typ v době revize neuvádí next-run, viz poznámka na konci stránky).

• status - Výsledek zaevidování - ok, pokud byla úloha úspěšně založena, jinak error. (typ: enum; povolené hodnoty: ok, error)
• id - Id úlohy - Číslo přidělené serverem nové úloze. Přítomno jen při status="ok". (typ: number)
• next-run - Nejbližší spuštění - Čas prvního/nejbližšího běhu ve formátu YYYY-MM-DD HH:MM:SS (místní čas serveru). Přítomno jen při status="ok". (typ: datetime)
• detail - Popis chyby - Přítomno jen při status="error". (typ: string)

Příklady odpovědi

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

Chyby a reakce

Odpověď je vždy jediný samouzavírající uzel do-import (žádný vnořený error):

• status="error" detail="Nemate patricna opravneni" – volající nemá r_import ani r_admin.
• status="error" detail="Systemova chyba pri vkladani pozadavku" – jakékoli selhání validace/založení úlohy: neznámý/neexistující doc-type, chybějící nebo neplatný column, nepovolená hodnota tran, attached-data="true" bez platného data, neúspěšný zápis do databáze aj. – všechny tyto různé příčiny vedou ke stejnému obecnému textu.
• status="skip" detail="Transakce byla preskocena" / status="error" detail="Transakce byla odvolana" – požadavek byl přeskočen/odvolán v rámci transakčního zpracování obálky – viz obálka požadavku.

Související požadavky

• job-list – seznam naplánovaných úloh včetně importů.
• undo – zrušení naplánované/opakované úlohy.
• do-export, do-force-import – další plánované úlohy práce se soubory.