Reference API výpočtů: proměnné a případ

vars – proměnné případu
task – aktuální úkol
proc – aktuální případ
snaps – snímky proměnných
dr – hromadná práce s řádky Dynamického řádku

Tento článek je referencí objektů vars, proc, task, snaps a dr, které má k dispozici kód na záložce Výpočty úkolu (viz Jak a kdy běží výpočty). Signatury a chování odpovídají verzi TAS 5.19.12. Knihovnu obecných funkcí lib a další služby (ai, axios, ftp...) popisuje článek Reference API výpočtů: knihovna lib. Dynamické tabulky (dt) mají vlastní článek Dynamické tabulky ve výpočtech.

Snímek ukazuje příklad z úkolu Fill in the travel request ukázkové šablony „Travel request“: když proměnná Traveller není vyplněná, výpočet do ní při spuštění úkolu doplní vlastníka případu.

if (!vars['traveller'].getValue()) {
    vars['traveller'].setValue(proc.IPROC_INST_OWNER_USER_ID);
}

vars – proměnné případu

vars je pole všech proměnných případu podle jejich názvu (TVAR_NAME) i ID (TVAR_ID): vars['Supplier'] i vars['482'] vrací tentýž objekt. Z objektu lze také přímo číst hodnoty sloupců proměnné, například vars['Supplier'].IVAR_TYPE.

Metoda	Vrací	Popis	Příklad
`getValue(language?)`	hodnota proměnné	Hodnota proměnné podle jejího typu (u DT vrací index řádku, u DR JSON řetězec).	`const total = vars['TotalPrice'].getValue();`
`setValue(value)`	`Promise<void>`	Nastaví novou hodnotu. U dynamického seznamu nastavte `null` pro vynulování.	`await vars['Approved'].setValue(true);`
`getJSON()`	`object`	Hodnota proměnné rozpadnutá do JSON (u Select/DL objekt `{value, title}`).	`const supplier = vars['Supplier'].getJSON();`
`getJSONAttr(key)`	hodnota	Přečte jednu vlastnost JSON hodnoty.	`vars['Supplier'].getJSONAttr('title');`
`setJSONAttr(key, value)`	`Promise<string>`	Nastaví jednu vlastnost JSON hodnoty a uloží.	`await vars['Meta'].setJSONAttr('note', 'OK');`
`getTitle()`	hodnota	Textová podoba proměnné – u DT vrací Title zvoleného řádku, jinak totéž co `getValue()`.	`vars['Country'].getTitle();`
`getIndex()`	hodnota	U DT textová hodnota prvku, u dynamického seznamu (uživatel/role/org. jednotka) id (u multi-výběru pole id), jinak totéž co `getValue()`.	`vars['Approver'].getIndex();`
`getName()`	`string`	Název proměnné (TVAR_NAME).	`vars['Supplier'].getName();`
`getDR(col)`	`string`	Hodnoty sloupce proměnné typu Dynamické řádky jako JSON.	`vars['Items'].getDR('unitPrice');`
`isChecked()`	`boolean`	Je proměnná typu zaškrtávací pole zaškrtnutá?	`if (vars['UrgentFlag'].isChecked()) { ... }`
`getFileStream(encoding='binary')`	stream	Obsah souboru proměnné typu příloha.	`const stream = await vars['Quote'].getFileStream();`
`setAttribute(attrName, value)`	`Promise<void>`	Uloží hodnotu libovolného sloupce proměnné (např. `IVAR_NAME_CS`).	`await vars['Supplier'].setAttribute('IVAR_LABEL', 'Dodavatel');`

Hodnota proměnné Select/DL
U proměnné typu výběr ze seznamu je getValue() často jen zvolená hodnota, zatímco getJSON()/getTitle() dávají i popisek. Pokud chcete hodnotu i text zároveň, použijte getJSON().

task – aktuální úkol

task zpřístupňuje sloupce tabulky úkolů instance (INSTANCE_TASKS) přímo jako vlastnosti, např. task.ITASK_NAME, task.ITASK_COMMENT, task.ITASK_DUE_DATE_FINISH. ITASK_ID a TTASK_ID jsou jen ke čtení.

Metoda	Vrací	Popis	Příklad
`setAttribute(attrName, value)`	`Promise<void>`	Uloží novou hodnotu sloupce úkolu do databáze. Na `ITASK_ID`/`TTASK_ID` vyhodí výjimku.	`await task.setAttribute('ITASK_COMMENT', 'Schváleno manažerem.');`
`getTaskLink()`	`string`	Frontendová URL adresa úkolu.	`const url = task.getTaskLink();`
`getOwnerUserName()`	`Promise<string>`	Zobrazované jméno řešitele úkolu.	`await task.getOwnerUserName();`
`getSolvedByUserName()`	`Promise<string>`	Zobrazované jméno uživatele, který úkol splnil.	`await task.getSolvedByUserName();`

Časté systémové hodnoty dostupné přes task/proc (stejné výrazy nabízí i pole Vložit proměnnou v editoru):

Výraz	Co vrací
`task.ITASK_NAME`, `task.ITASK_COMMENT`, `task.ITASK_DESCRIPTION`, `task.ITASK_INSTRUCTION`	Název, komentář, popis a instrukce úkolu.
`task.ITASK_DUE_DATE_START`, `task.ITASK_DUE_DATE_FINISH`	Plánovaný začátek a termín úkolu.
`task.ITASK_ACTUAL_DATE_START`, `task.ITASK_ACTUAL_DATE_FINISH`	Skutečný začátek a dokončení úkolu.
`task.ITASK_USER_ID`, `task.getOwnerUserName()`	Řešitel úkolu – id a jméno.
`task.ITASK_FINISHED_BY_USER_ID`, `task.getSolvedByUserName()`	Kdo úkol fakticky splnil – id a jméno.

proc – aktuální případ

proc zpřístupňuje sloupce tabulky procesů instance (INSTANCE_PROCESSES) stejným způsobem jako task, např. proc.IPROC_NAME, proc.IPROC_INST_OWNER_USER_ID. IPROC_ID a TPROC_ID jsou jen ke čtení.

Metoda	Vrací	Popis	Příklad
`setAttribute(attrName, value)`	`Promise<void>`	Uloží novou hodnotu sloupce případu.	`await proc.setAttribute('IPROC_DESCRIPTION', 'Objednávka Q1');`
`getCaseLink()`	`string`	Frontendová URL adresa případu.	`proc.getCaseLink();`
`getCaseOwnerName()`	`Promise<string>`	Zobrazované jméno vlastníka případu.	`await proc.getCaseOwnerName();`
`getCaseNotes(asObject?)`	`Promise<string \| any[]>`	Poznámky případu. Bez parametru HTML text se zalomením, s `true` pole objektů `{userFullName, userDisplayName, taskName, dateTime, note}`.	`const notes = await proc.getCaseNotes(true);`
`setCaseStatus(value)`	`Promise<void>`	Uloží volně definovaný textový stav případu (`IPROC_CASE_STATUS`) – nezávislý na systémovém stavu procesu.	`await proc.setCaseStatus('WAITING_FOR_SUPPLIER');`
`getCaseStatus()`	`string`	Aktuální `IPROC_CASE_STATUS`.	`if (proc.getCaseStatus() === 'WAITING_FOR_SUPPLIER') { ... }`
`getTemplateTasksInfo()`	`Promise<Record<string, any>>`	Metadata úkolů šablony podle TTASK_NAME – hodí se pro mapování lokalizovaných názvů úkolů v dalších jazycích.	`const tasks = await proc.getTemplateTasksInfo();`

// Poznámka k případu se zápisem i čtením zpět
await debug.log('Order approved by manager.');
const history = await proc.getCaseNotes(true);
vars['LastNote'].setValue(history.at(-1)?.note ?? '');

snaps – snímky proměnných

snaps['Název'] zpřístupňuje snapshotovou (zamrzlou) kopii proměnné, například hodnotu uloženou při konkrétním kroku schvalování. Je k dispozici jen v kontextu úkolu (Task-JS).

Metoda	Vrací	Popis
`getName()`	`string`	Název snímkované proměnné.
`getValue()`	hodnota	Hodnota snímku s ohledem na typ proměnné (u DT index řádku, u DR JSON).
`setValue(value)`	`Promise<void>`	Uloží novou hodnotu snímku; přijímá i objekty API (UserApi apod.), které se převedou na primitivní hodnotu.

const approvedAmount = snaps['RequestedAmount'].getValue();

dr – hromadná práce s řádky Dynamického řádku

Objekt dr (na rozdíl od skriptu uvnitř samotné proměnné typu Dynamické řádky, viz Dynamické řádky: skript) slouží k úpravě řádků DR proměnné přímo z kódu úkolu.

Metoda	Vrací	Popis
`from(variable)`	`this`	Nastaví práci s danou DR proměnnou (objekt `vars['...']` nebo její název).
`get()`	`object`	Aktuální data DR.
`removeWhereCol(colName, value)`	`this`	Odebere všechny řádky, kde sloupec `colName` obsahuje `value`. Nutné zavolat `store()` pro uložení.
`store()`	`Promise<this>`	Uloží provedené změny zpět do proměnné.

// Odebere položky objednávky s nulovým množstvím
await dr.from(vars['Items']).removeWhereCol('quantity', 0).store();

Související: Jak a kdy běží výpočty, Reference API výpočtů: knihovna lib, Dynamické tabulky ve výpočtech, Výpočty na úkolu.

Reference API výpočtů: knihovna lib

(opens in a new tab)