Calculations API reference: variables and case

vars – case variables
task – current task
proc – current case
snaps – variable snapshots
dr – bulk operations on Dynamic Rows

This article is a reference for the vars, proc, task, snaps and dr objects available to code on the Calculations tab of a task (see How and when calculations run). Signatures and behaviour correspond to TAS version 5.19.12. The lib library of general functions and other services (ai, axios, ftp...) are described in the article Calculations API reference: lib library. Dynamic Tables (dt) have their own article, Dynamic Tables in calculations.

The screenshot shows an example from the Fill in the travel request task of the "Travel request" sample template: if the Traveller variable is empty, the calculation fills in the case owner when the task starts.

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

vars – case variables

vars is an array of all case variables, keyed both by name (TVAR_NAME) and by ID (TVAR_ID): vars['Supplier'] and vars['482'] return the same object. You can also read the variable's column values directly from the object, for example vars['Supplier'].IVAR_TYPE.

Method	Returns	Description	Example
`getValue(language?)`	variable value	Value of the variable according to its type (for DT it returns the row index, for DR a JSON string).	`const total = vars['TotalPrice'].getValue();`
`setValue(value)`	`Promise<void>`	Sets a new value. For a dynamic list, set `null` to clear it.	`await vars['Approved'].setValue(true);`
`getJSON()`	`object`	Variable value broken down into JSON (for Select/DL an object `{value, title}`).	`const supplier = vars['Supplier'].getJSON();`
`getJSONAttr(key)`	value	Reads a single property of the JSON value.	`vars['Supplier'].getJSONAttr('title');`
`setJSONAttr(key, value)`	`Promise<string>`	Sets a single property of the JSON value and saves it.	`await vars['Meta'].setJSONAttr('note', 'OK');`
`getTitle()`	value	Text form of the variable – for DT it returns the Title of the selected row, otherwise the same as `getValue()`.	`vars['Country'].getTitle();`
`getIndex()`	value	For DT the text value of the item, for a dynamic list (user/role/org. unit) the id (an array of ids for multi-select), otherwise the same as `getValue()`.	`vars['Approver'].getIndex();`
`getName()`	`string`	Variable name (TVAR_NAME).	`vars['Supplier'].getName();`
`getDR(col)`	`string`	Values of a column of a Dynamic Rows variable as JSON.	`vars['Items'].getDR('unitPrice');`
`isChecked()`	`boolean`	Is the checkbox variable checked?	`if (vars['UrgentFlag'].isChecked()) { ... }`
`getFileStream(encoding='binary')`	stream	File content of an attachment variable.	`const stream = await vars['Quote'].getFileStream();`
`setAttribute(attrName, value)`	`Promise<void>`	Saves the value of any column of the variable (e.g. `IVAR_NAME_CS`).	`await vars['Supplier'].setAttribute('IVAR_LABEL', 'Dodavatel');`

Value of a Select/DL variable
For a select-from-list variable, getValue() is often just the selected value, whereas getJSON()/getTitle() also return the label. If you need both the value and the text, use getJSON().

task – current task

task exposes the columns of the instance task table (INSTANCE_TASKS) directly as properties, e.g. task.ITASK_NAME, task.ITASK_COMMENT, task.ITASK_DUE_DATE_FINISH. ITASK_ID and TTASK_ID are read-only.

Method	Returns	Description	Example
`setAttribute(attrName, value)`	`Promise<void>`	Saves a new value of a task column to the database. Throws an exception for `ITASK_ID`/`TTASK_ID`.	`await task.setAttribute('ITASK_COMMENT', 'Schváleno manažerem.');`
`getTaskLink()`	`string`	Frontend URL of the task.	`const url = task.getTaskLink();`
`getOwnerUserName()`	`Promise<string>`	Display name of the task solver.	`await task.getOwnerUserName();`
`getSolvedByUserName()`	`Promise<string>`	Display name of the user who completed the task.	`await task.getSolvedByUserName();`

Common system values available via task/proc (the Insert variable field in the editor offers the same expressions):

Expression	Returns
`task.ITASK_NAME`, `task.ITASK_COMMENT`, `task.ITASK_DESCRIPTION`, `task.ITASK_INSTRUCTION`	Task name, comment, description and instructions.
`task.ITASK_DUE_DATE_START`, `task.ITASK_DUE_DATE_FINISH`	Planned start and due date of the task.
`task.ITASK_ACTUAL_DATE_START`, `task.ITASK_ACTUAL_DATE_FINISH`	Actual start and completion of the task.
`task.ITASK_USER_ID`, `task.getOwnerUserName()`	Task solver – id and name.
`task.ITASK_FINISHED_BY_USER_ID`, `task.getSolvedByUserName()`	Who actually completed the task – id and name.

proc – current case

proc exposes the columns of the instance process table (INSTANCE_PROCESSES) in the same way as task, e.g. proc.IPROC_NAME, proc.IPROC_INST_OWNER_USER_ID. IPROC_ID and TPROC_ID are read-only.

Method	Returns	Description	Example
`setAttribute(attrName, value)`	`Promise<void>`	Saves a new value of a case column.	`await proc.setAttribute('IPROC_DESCRIPTION', 'Objednávka Q1');`
`getCaseLink()`	`string`	Frontend URL of the case.	`proc.getCaseLink();`
`getCaseOwnerName()`	`Promise<string>`	Display name of the case owner.	`await proc.getCaseOwnerName();`
`getCaseNotes(asObject?)`	`Promise<string \| any[]>`	Case notes. Without a parameter, HTML text with line breaks; with `true`, an array of objects `{userFullName, userDisplayName, taskName, dateTime, note}`.	`const notes = await proc.getCaseNotes(true);`
`setCaseStatus(value)`	`Promise<void>`	Saves a freely defined text status of the case (`IPROC_CASE_STATUS`) – independent of the system status of the process.	`await proc.setCaseStatus('WAITING_FOR_SUPPLIER');`
`getCaseStatus()`	`string`	Current `IPROC_CASE_STATUS`.	`if (proc.getCaseStatus() === 'WAITING_FOR_SUPPLIER') { ... }`
`getTemplateTasksInfo()`	`Promise<Record<string, any>>`	Metadata of template tasks keyed by TTASK_NAME – useful for mapping localised task names in other languages.	`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 – variable snapshots

snaps['Name'] gives access to a snapshot (frozen) copy of a variable, for example the value saved at a specific approval step. It is only available in the task context (Task-JS).

Method	Returns	Description
`getName()`	`string`	Name of the snapshotted variable.
`getValue()`	value	Snapshot value according to the variable type (row index for DT, JSON for DR).
`setValue(value)`	`Promise<void>`	Saves a new snapshot value; also accepts API objects (UserApi etc.), which are converted to a primitive value.

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

dr – bulk operations on Dynamic Rows

The dr object (unlike the script inside a Dynamic Rows variable itself, see Dynamic Rows: script) is used to modify the rows of a DR variable directly from the task code.

Method	Returns	Description
`from(variable)`	`this`	Selects the DR variable to work with (a `vars['...']` object or its name).
`get()`	`object`	Current DR data.
`removeWhereCol(colName, value)`	`this`	Removes all rows where the `colName` column contains `value`. You must call `store()` to save.
`store()`	`Promise<this>`	Saves the changes back to the variable.

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

Related: How and when calculations run, Calculations API reference: lib library, Dynamic Tables in calculations, Calculations on a task.

Calculations API reference: the lib library

(opens in a new tab)