Formulas
A formula calculates a value when the command runs, the way a formula does in an Excel cell. Any value that starts with = is a formula, so a small calculation goes right into the command that needs it. You do not need a separate block for it:
set --name:gross --type:number --value:=$net$ * 1.2
log --message:="Order " & $orderId$ & " is ready"
set --name:vat --type:number --value:=round($total$ * 0.18, 2)
excel --action:writecell --session:Book --col:B --row:2 --value:=format(adddays(today(), -1), "dd.MM.yyyy")
if --type:string --left:=upper(trim($status$)) --operator:equals --right:APPROVED
endifIn the editor
Fields that can hold a formula have a small fx button next to their name. It opens the formula builder:
- an input with colours for functions, text, numbers and variables; mistakes are underlined, with the reason below;
- the functions, grouped and searchable, each with a one-line description and an example. Click one to insert it;
- buttons for the operators and Insert variable (or type
$to choose a variable); - the result preview. It is calculated in the browser with sample values: the variable's initial value when the editor knows it (
set --value,input --default), otherwise a value you type. Sample values are only for the preview; the task uses the real values.
You can also type = at the start of a text field: the field turns into a formula field (marked fx), with a hint and the result calculated with the variables' initial values. Number and true/false fields get their formula through the fx button. To go back to a plain value, remove the formula with the × in the field.
In the code editor formulas are coloured too, and the editor checks them as you type: a syntax error, an unknown function or a wrong number of values is an error, and a variable the task does not have is a warning.
Writing formulas
| Part | Written as | Example |
|---|---|---|
| Numbers | With a dot, no thousands separator | 1.5, 1000 |
| Text | In double quotes; "" is a quote inside |
"Order ", "say ""hi""" |
| Variables | Between dollar signs, with fields and items | $total$, $order.Total$, $items[0]$, $list.Count$ |
| True/false, empty | true, false, null |
|
| Arithmetic | + - * /, % (remainder), parentheses |
=($a$ + $b$) * 2 |
| Join text | & |
=$first$ & " " & $last$ |
| Comparison | = (or ==), != (or <>), <, >, <=, >= |
=$amount$ > 1000 |
| Logic | and, or, not |
=$a$ > 0 and not $done$ |
| Functions | name(value, value, …); ; also separates values |
=round($x$, 2), =round($x$; 2) |
- Function names and
and/or/notare not case-sensitive (ROUND,Roundandroundare the same). $references$inside text are filled in too:="Dear $name$,".- Results keep their type: a number, text, true/false, a date or empty.
set --type:number --value:=$a$ + 1stores a number. A formula in a text field gives text (a number like120, a date like2026-03-05 14:30:00), and a number field gets the number. - An empty value counts as 0 in a calculation. Text that is not a number cannot be added (
"abc" + 1fails: join text with&). - Comparisons compare numbers as numbers (
"10" > "9"is true), dates by time, and everything else as text (case matters). - Formulas need no quotes around the whole value, even with spaces.
- In
datatable --action:addcolumn --valuethe formula is calculated once per row, and$row.Column$is that row's value:--value:=$row.Price$ * $row.Qty$(see data table operations).
Text that starts with =
Text that should start with = gets an apostrophe in front, as in Excel: log --message:'=== done === writes === done ===. The apostrophe is removed when the task runs. Tasks saved before formulas existed are converted this way automatically, so their values keep their meaning.
Some values are never formulas: conditions (--condition, which has its own syntax), variable names, choices from a list, JavaScript code, comments, step descriptions, and the Excel formula of excel --action:writeformula (it goes into the cell as written: --formula:=SUM(C2:C10)).
Numbers, dates and cultures
Numbers in formulas are written and read with a dot, whatever the language of the computer. A number becomes text with a dot and without trailing zeros (1.50 becomes 1.5). Use format for any other form. format and value take an optional culture: format($total$, "#,##0.00", "tr-TR") gives 1.234,50, and value("1.234,56", "tr-TR") gives 1234.56.
Formats are .NET format strings. For numbers: 0 (a digit), # (a digit if there is one), . (decimal point), , (thousands), % (percent), or N2 / F2. For dates: dd, MM, yyyy, HH (0 to 23), hh, mm, ss, MMM/MMMM (month name), ddd/dddd (day name), and text in single quotes.
Functions
Text
| Function | Gives | Example |
|---|---|---|
upper(text) |
The text in capital letters | =upper($name$) |
lower(text) |
The text in small letters | =lower($email$) |
proper(text) |
Every word starting with a capital letter | =proper("ali veli") → Ali Veli |
trim(text) |
The text without spaces at the start and end | =trim($name$) |
len(text) |
How many characters the text has (items, for a list) | =len($code$) |
left(text, count?) |
The first characters (1 when no count is given) | =left($code$, 3) |
right(text, count?) |
The last characters (1 when no count is given) | =right($iban$, 4) |
mid(text, start, count) |
Characters from the middle; the first character is 1 | =mid($code$, 4, 2) |
replace(text, find, with) |
The text with every "find" replaced (case-sensitive) | =replace($amount$, ",", ".") |
substitute(text, find, with) |
Same as replace (the Excel name) | =substitute($phone$, " ", "") |
contains(text, part) |
true when the text contains the part (case-sensitive) | =contains($subject$, "Invoice") |
startswith(text, part) |
true when the text starts with the part | =startswith($code$, "TR") |
endswith(text, part) |
true when the text ends with the part | =endswith($file$, ".pdf") |
concat(value, …) |
The values joined into one text (like &) |
=concat($first$, " ", $last$) |
format(value, format, culture?) |
A number or date as text in the given format | =format($date$, "dd.MM.yyyy") |
text(value, format, culture?) |
Same as format (the Excel name) | =text($total$, "#,##0.00") |
Numbers
| Function | Gives | Example |
|---|---|---|
round(number, digits?) |
Rounded to the digits after the point (0 when not given); 0.5 rounds away from zero; negative digits round to tens, hundreds… | =round($total$ * 0.18, 2) |
roundup(number, digits?) |
Rounded away from zero | =roundup($hours$, 0) |
rounddown(number, digits?) |
Rounded toward zero (the extra digits cut off) | =rounddown($price$, 1) |
abs(number) |
The number without its sign | =abs($difference$) |
min(number, …) |
The smallest of the numbers (lists included) | =min($a$, $b$) |
max(number, …) |
The largest of the numbers (lists included) | =max($a$, 0) |
int(number) |
The number rounded down to a whole number | =int($amount$) |
mod(number, divisor) |
The remainder of a division (with the sign of the divisor) | =mod($row$, 2) |
power(number, power) |
The number raised to a power | =power(1.1, 3) |
sqrt(number) |
The square root | =sqrt($area$) |
value(text, culture?) |
Text as a number | =value("1.234,56", "tr-TR") |
Dates
| Function | Gives | Example |
|---|---|---|
today() |
Today at 00:00 | =today() |
now() |
The current date and time | =now() |
date(year, month, day, hour?, minute?, second?) |
A date from its parts | =date(2026, 12, 31) |
adddays(date, days) |
The date plus (or minus) days | =adddays(today(), -1) |
addmonths(date, months) |
The date plus months (the day is kept, or the month's last day) | =addmonths($start$, 1) |
addyears(date, years) |
The date plus years | =addyears(today(), 1) |
addhours(date, hours) |
The date plus hours | =addhours(now(), 2) |
addminutes(date, minutes) |
The date plus minutes | =addminutes(now(), 30) |
year(date), month(date), day(date) |
The year; the month, 1 to 12; the day, 1 to 31 | =year($date$) |
hour(date), minute(date) |
The hour, 0 to 23; the minute, 0 to 59 | =hour(now()) |
weekday(date) |
The day of the week: 1 Monday … 7 Sunday | =weekday(today()) |
datediff(start, end, unit?) |
Whole days from start to end; the unit may be "hours", "minutes", "seconds", "months" or "years" |
=datediff($invoiceDate$, today()) |
A date may also be written as text: adddays("2026-01-31", 1).
Logic
| Function | Gives | Example |
|---|---|---|
if(condition, then, else?) |
One value when the condition is true, another when it is not (empty without else) | =if($amount$ > 1000, "Large", "Small") |
and(condition, …) |
true when every condition is true | =and($a$ > 0, $b$ > 0) |
or(condition, …) |
true when any condition is true | =or($status$ = "New", $status$ = "Open") |
not(condition) |
true when the condition is false | =not(isempty($email$)) |
isempty(value) |
true for empty text (spaces only included), an empty list or no value | =isempty($note$) |
iferror(value, fallback) |
The value, or the fallback when calculating it fails | =iferror(value($text$), 0) |
if and iferror calculate only the part they use, so =if($count$ > 0, $total$ / $count$, 0) never divides by zero.
Conversion
| Function | Gives | Example |
|---|---|---|
tonumber(value) |
The value as a number | =tonumber($quantity$) + 1 |
totext(value) |
The value as text | =totext($count$) |
When a formula fails
A formula that cannot be calculated stops the command with an error that shows the formula and where the problem is, for example =$a$ / 0: division by zero (position 6). As with any error, a try block or --onerror handles it. To give a value instead, use iferror.
Agents
Formulas are calculated by the agent. An agent from before formulas cannot run a task that uses them: the server does not send it the task and says which formula needs a newer agent. Update the agent to the current version.