Using expressions with dependencies and properties
- Synopsis
- Full Details
In briefAn expression is a property token that computes a value instead of looking one up.
You write it as [[= … ]]. It can do arithmetic, compare values, slice and change the case of
strings, work with durations, and convert between types. It works over literal values and over
other property tokens. An expression never writes: an assignment is parsed and then refused.
WhereAn expression is evaluated in six places: in a job parameter, in an event a job or workflow fires, in a notification template, as an expression dependency on a job, as a job event's Completion Expression trigger, and as a Self Service button's Hidden or Disabled rule.
WhenUse an expression when:
- a parameter needs a value worked out from a property, such as a count plus one or a name in upper case;
- a job should wait until a condition over properties is
True; - an input may be malformed, and you want a fallback value rather than a failure.
To read a value as it is stored, use a plain token — see Properties.
How
- Write the expression inside
[[=and]], for example[[= ToInt([[JI.RetryCount]]) + 1 ]]. A property's value is always a string, so convert it withToIntorToFloatbefore you calculate with it. - Use parentheses to make the grouping you want.
- Where an input may be bad, use the matching
NEfunction with a fallback, such asSubStrNEorToIntNE. - Check the result in the place it is used. A job parameter fails the job if the expression fails.
- Function and operator names are matched ignoring case.
- A property token's value is always a string inside an expression.
%binds tighter than*,&&and||share one level, and^is left-associative.&&and||evaluate both sides. Neither can guard the other.==compares numbers with a small tolerance, but!=compares them exactly.Expralways returns a string.
SubStrfails when the start is past the end of the string, soSubStr("", 0)fails. UseSubStrNEfor input that may be short.- In an event field or a notification, a failing expression is left as text and the tokens around it still resolve. An assignment is different: it leaves the whole event field as you wrote it.
- An assignment fails a job parameter and fails a notification send.
Expris refused once a run fact, such as a job name, has been read earlier in the same expression.- An Encrypted global property cannot be an operand in any expression, directly or through another global. Using it on its own, outside an expression, still works.
Written from the Properties token grammar. Read that page first
— an expression is a property token with a = after the opening delimiter, and everything it says
about scopes, system names, delimiters, and when tokens resolve applies here unchanged.
A property token normally names a value to look up. An expression token computes one instead:
[[= ToInt([[JI.RetryCount]]) + 1 ]]
[[= ToUpper([[OI.Environment]]) ]]
[[= SubStr([[JI.$JOB NAME]], 0, 8) ]]
[[= [[OI.LastRunStatus]] == "OK" ]]
Write it as [[= … ]] or {{= … }}. The one-delimiter-pair-per-string rule
still decides which pair is live, so an expression written with {{= in a string that contains [[
anywhere is left as written.
- Where It Works
- Operands
- Operators
- Functions
- Results and Failures
Where It Works
Where an expression is evaluated
The three moments a plain token resolves, under the same rules — plus three places an expression is the whole point rather than part of a string:
| Where | Evaluated | If the expression fails |
|---|---|---|
| A job parameter | As the job is dispatched | The job fails. |
| An event a job or workflow fires | As the event fires | The event still fires, and the failing expression keeps its authored text. Other tokens in the same field still resolve. |
| A notification template | As the notification is sent | The notification still goes out, and the failing expression is left as text. |
| An expression dependency on a job | Repeatedly while the job waits, until it renders True | The job is put On Hold and the cause is recorded against it. |
| A job event's Completion Expression trigger | Once, when the job reaches a final status | The event is skipped and a warning is logged. Only True fires the event. |
| A Self Service button's Hidden or Disabled rule | Each time the portal loads the button list, and when a request form opens | The rule answers an error, and the button stays visible and submittable, except for the case that page describes. |
An expression is charged against the same work budget as the rest of the string it sits in, so two expressions in one job parameter share one budget rather than each getting their own.
Two of this page's rules are reversed at that gate, and both follow from its answer being a decision rather than a value:
- No degraded reading. The fallback described in
When an expression fails (on the Results and Failures tab) is what the event and notification rows do. Source text
that happened to read
Truewould open the gate, so an unresolvable token there holds the job instead. - No encrypted global properties. A mask would answer a comparison that has no relation to the
value, so the gate does not mask: an
OI.property marked Encrypted cannot be used in an expression dependency at all. The save is refused, and a job whose gate still reaches one when it runs is put On Hold — see An expression is resolved strictly.
The language parses assignment — [[= [[OI.Flag]] = "x" ]] — and then refuses it. No expression
can change a property, a threshold, or a resource count. See
Assignment is refused (on the Results and Failures tab).
Operands
Operands
An expression is built from four kinds of operand:
| Operand | Notes |
|---|---|
| Number | Written as digits, with an optional decimal point: 42, 2.5. There is no exponent form. Always a floating-point number. "Integer" means a whole number that fits in 32 bits. |
| String | In double quotes: "OK". |
| Boolean | true or false, matched ignoring case. |
| Property token | A full [[Name]] / [[Scope.Name]] token, resolved exactly as it would be on its own — including its scope routing, date formats, and offsets. Its value is always a string, even when it looks like a number. |
[[= [[JI.RetryCount]] + 1 ]] fails with a type error: the token's value is text, and + does not
mix a string and a number. Convert first — [[= ToInt([[JI.RetryCount]]) + 1 ]], or ToFloat for
a value with a decimal part. The same applies to -, *, /, %, ^ and to < and its siblings.
== does not fail on a mismatch, it answers false: compare a property with a string —
[[OI.BatchReady]] == "Y" — or convert it before comparing it with a number.
Whitespace between operands and operators is ignored. Operator and function names are matched
ignoring case, so SubStr, substr and SUBSTR are one function.
A property token inside an expression goes through the ordinary resolution path, so a cycle is still detected and a name that cannot be resolved fails the expression rather than silently becoming empty. An encrypted global property is the exception: it cannot be an operand at all (see Encrypted global properties are refused as operands).
Encrypted global properties are refused as operands
An expression's result is shown, so comparing an Encrypted OI. property would let someone
confirm a guess at its value. No [[= … ]] expression may read one — in a job parameter, a
notification, or an event — whether the expression names it directly or reaches it through another
global property whose value names it. The refusal names the property, never its value: Encrypted
property OI.… cannot be used in an expression. Using the encrypted property on its own, such as
[[OI.DbPassword]] in a command line, works as it always did.
| Where the expression is | What happens |
|---|---|
| A job's task parameters | The workflow save or import, and the save of an edit to the job on a running instance, is refused, naming the job. If the global became encrypted after the save, the job ends Initialization Error at dispatch with that message and does not run. |
| A notification action, an escalation level, or a test send | The save is refused. If one is still reached when the notification is sent, the expression is shown as its own text and the email, SMS or in-app notification still goes out. An OpCon Event action fails its delivery instead. |
| A job or workflow event | The save is refused. If one is still reached when the event fires, that expression keeps its written text and the event still fires. |
Expression dependencies follow the same rule, with their own handling described in the note above.
Writing a quote or a backslash in a string
| You type | You get |
|---|---|
"C:\\logs" | C:\logs — a doubled backslash is one backslash. |
"say \\\"hi\\\"" | say "hi" — three backslashes before the quote. |
"say \"hi\"" | Refused: Escaped quotes are not supported inside an expression string literal; double the escape to write a quote |
One or two backslashes before a quote are refused by name rather than producing a mangled token.
Operators
Precedence
Operators are applied by precedence, highest first. Everything is left-associative, including
^.
| Level | Operators |
|---|---|
| 100 | every named function, and unary - |
| 90 | ^ |
| 80 | % |
| 70 | * / |
| 50 | + - |
| 20 | == <> != < > <= >= |
| 10 | && || |
| 7 | = (assignment — parsed, then refused) |
| 5 | , (the argument separator is an operator, not punctuation) |
Use parentheses when you want a different grouping. Unbalanced parentheses are a syntax error.
These are the model's own rules, not defects, and each is worth checking in an expression you inherit:
%binds tighter than*.2 * 3 % 2is2 * (3 % 2)— that is 2, not 0.&&and||share one level, so they associate left to right.a || b && cis(a || b) && c.^is left-associative.2 ^ 3 ^ 2is(2 ^ 3) ^ 2— that is 64, not 512.
- is read as subtraction when it follows a ) or an operand, and as negation otherwise. Two
adjacent minus signs are read as one subtraction operator, so 5--2 is 3.
Arithmetic and logic
| Operator | Name | Accepts | Notes |
|---|---|---|---|
+ | Add, or join | two numbers, or two strings | Numbers add; strings concatenate, so "ACH" + "_" + "0421" is ACH_0421. A number and a string together is a type error. |
- | Subtract, or remove | two numbers, or two strings | Numbers subtract; strings remove — "abcabc" - "b" is "acac", every occurrence. Removing an empty string is an error. |
- (before a value) | Negate | a number | -5 is minus five. |
* | Multiply | two numbers | 3 * 4 is 12. |
/ | Divide | two numbers | 10 / 4 is 2.5. Dividing by zero fails; it does not produce infinity. |
% | Modulo (the remainder) | two integers | 7 % 3 is 1. A non-whole value is a type error, so 4.5 % 2 fails while 4.0 % 2 is fine. |
^ | Power | two numbers | 2 ^ 3 is 8. |
&& | And | two booleans | true only when both sides are true. |
|| | Or | two booleans | true when either side is true. |
&& and || do not short-circuitBoth sides are evaluated before the operator is applied, so a || cannot guard the expression on
its right. [[= ToInt([[OI.Divisor]]) == 0 \|\| 100 / ToInt([[OI.Divisor]]) > 1 ]] still fails when the
divisor is zero. There is also no truthiness: 1 && true is a type error, not true.
Comparison
| Operator | Name | Accepts | On a type mismatch |
|---|---|---|---|
== | Equal to | numbers, strings, booleans | Returns false. Never fails. |
<> or != | Not equal to | numbers, strings, booleans | Returns true. Never fails. Both spellings are the same operator. |
< | Less than | two numbers, or two strings | Fails. |
> | Greater than | two numbers, or two strings | Fails. |
<= | Less than or equal to | two numbers, or two strings | Fails. |
>= | Greater than or equal to | two numbers, or two strings | Fails. |
Every comparison answers True or False. A string comparison with == is case-sensitive:
"OK" == "ok" is False.
Two things about comparison decide answers a reader would otherwise have to guess at:
==compares numbers with a tolerance;!=compares them exactly. So for two values that differ only in the last few digits —0.5and0.5000004—a == banda != bare both true. Pick one operator and stay with it rather than assuming the other is its negation.- String ordering is linguistic, not character-by-character.
<and its siblings order strings the way a person sorting a list would, in the culture the platform is rendering dates in. TheIndexfunction, by contrast, searches by exact characters — so a string<comparison and anIndexsearch can disagree about whether two strings are "the same".
AreEqual(a, b, …) compares an argument list. It compares adjacent pairs, uses the same
tolerance == does for numbers, returns false on the first type mismatch — and returns true
for a single argument, because there is no pair to compare.
Functions
Functions
Every function is written Name(arguments), binds tighter than any operator, and rejects the wrong
number of arguments rather than guessing.
Strings
| Function | Returns | Example |
|---|---|---|
SubStr(s, start[, len]) | The slice of s beginning at start (0-based), len characters long, or to the end when len is left out. | SubStr("ACH20261021.txt", 3, 8) is 20261021. |
Index(hay, needle) | The position of needle in hay (0-based), or -1 if it is not there. | Index("ACH20261021.txt", ".") is 11. |
Replace(s, find, with) | s with every occurrence of find replaced. | Replace("2026-10-21", "-", "") is 20261021. |
ReplaceBackslashes(s, with) | s with every backslash replaced. | ReplaceBackslashes("C:\\exports\\ach", "/") is C:/exports/ach. |
Length(s) | The number of characters in s. | Length("ACH") is 3. |
ToLower(s), ToUpper(s) | s case-folded. | ToUpper("prod") is PROD. |
SubStr is strict about its bounds, and this is the function most likely to fail on real data:
startmust be a whole number.SubStr("abcdef", 1.5, 2)fails; it does not read from position 1.- A
startat or past the end of the string fails, soSubStr("", 0)is an error rather than the empty string — worth knowing when the first argument is a property that may be empty. start + lenpast the end of the string fails.
Use SubStrNE when the input may not be long enough; see Falling back instead of failing.
Conversion
| Function | Notes |
|---|---|
ToStr(x) | Renders x as a string, so ToStr(3) + " files" is 3 files. A boolean renders as True or False. |
ToInt(x) | Truncates toward zero, so ToInt(-2.7) is -2, not -3. A string is read as a number first, using the decimal separator of the culture the platform renders dates in, so ToInt("2.7") is 2 where that separator is a point. A boolean is refused. |
ToFloat(x) | A number, or a string read as one: ToFloat("2.5") * 2 is 5. |
ToLong(x) | A number is truncated. A string must be a whole number — ToLong("2.5") fails, where ToInt("2.5") is 2. |
ToBool(x) | A string must be the text true or false, in any case, with surrounding spaces allowed, so ToBool("TRUE") is True; a boolean passes through unchanged. A number is refused — ToBool(1) fails. |
Dates and durations
| Function | Notes |
|---|---|
ToOaTime("[[dd:]hh:]mm") | Converts a duration into a serial date-time number, counted in days: ToOaTime("01:30") is 0.0625, an hour and a half. One, two, or three colon-separated parts — minutes, hh:mm, or dd:hh:mm — each a non-negative whole number. A leading + is accepted; a leading - is not. |
TimeDiff(t1, t2, format) | The difference t1 minus t2 between two durations. Both times must be strings in exactly hh:mm:ss. |
TimeDiff's format is one of six names. The examples are for
TimeDiff("00:30:00", "01:00:00", format), half an hour against an hour:
| Format | Returns | Example |
|---|---|---|
signed_secs / unsigned_secs | The difference in seconds, signed or absolute. | -1800 / 1800 |
signed_string / unsigned_string | The difference as a duration string. | -00:30:00 / 00:30:00 |
signed_percent / unsigned_percent | The difference as a percentage of the second duration. | -50 / 50 |
The two percent formats divide by the second duration, so they fail when it is 00:00:00.
Maths and nested evaluation
| Function | Notes |
|---|---|
LogToBase(x, base) | The logarithm of x in the given base: LogToBase(100, 10) is 2. |
Expr(s) | Evaluates the string s as an expression: Expr("1+1") is the string 2. |
Expr always returns a string, whatever the inner expression computed. So Expr("1+1") + 1 is
a type error, and Expr("1+1") + "x" is "2x". A chain of nested Expr calls is bounded by the
same depth limit as the rest of the resolution, so it fails with a depth error rather than running
away.
Falling back instead of failing
Six functions take one extra trailing argument and return it when the operation fails. This is the only error handling the language has.
| Function | Example |
|---|---|
SubStrNE(s, start, fallback) or SubStrNE(s, start, len, fallback) | SubStrNE("", 0, "n/a") is the empty string — see below. |
ToStrNE(x, fallback) | The fallback is never used — see below. |
ToIntNE(x, fallback) | ToIntNE("n/a", 0) is 0. |
ToFloatNE(x, fallback) | ToFloatNE("n/a", 0) is 0. |
ToLongNE(x, fallback) | ToLongNE("2.5", 0) is 2 — see below. |
TimeDiffNE(t1, t2, format, fallback) | TimeDiffNE("1:00", "01:00:00", "signed_secs", 0) is 0, because 1:00 is not hh:mm:ss. |
Three things to know about them:
- The fallback covers the operation, not the call. Calling one with the wrong number of
arguments is still an error —
SubStrNE("abc", 0)fails rather than returning something. - An
NEfunction is not simply its base function plus a fallback, and two differ on purpose:SubStrNEperforms no bounds pre-check, soSubStrNE("", 0, "n/a")returns the empty string whereSubStr("", 0)fails; andToLongNE("2.5", 0)returns2whereToLong("2.5")fails. ToStrNE's fallback can never fire, because nothing in the conversion it performs can fail. It exists for compatibility.
The fallback covers a syntax, type, or divide-by-zero failure. (TimeDiffNE given a time or format
that is not a string still fails.) It does not swallow a budget
limit, a cycle, or a refused assignment — those are reported rather than hidden.
Results and Failures
What a result looks like
| Result | Renders as |
|---|---|
| A string | Its text, without the quotes. |
| A whole number | 42 |
| A very large or very small number | Scientific notation — 1E-06, 1E+21 — rather than a long run of zeros. |
| A boolean | True or False |
A result outside the range a number can represent — 10 ^ 400, for instance — fails rather than
rendering as infinity, because an infinity spliced into a job's command line is worse than an error.
When an expression fails
Four kinds of read failure are reported separately, so a log entry says which one happened: a syntax error, a type error, a divide by zero, and a wrong argument count.
What that costs depends on where the expression is:
- In a job parameter, the job fails. A parameter is an instruction to a machine.
- In an event field, the event still fires, and the failing expression keeps its authored text, delimiters and all. Every other token in the same field, and every other field, still resolves.
- In a notification template, the message still goes out. The failing expression degrades on its own, and every other substitution in the template still resolves.
=In a notification, a degraded token renders the text inside its delimiters — which for an expression includes the
leading marker. [[= 1 @@ 2 ]] renders as = 1 @@ 2, not as 1 @@ 2. That is what to search the
rendered output for when you are hunting one down.
Assignment is refused
= is the assignment operator, and the language parses it so that an assignment can be recognised
and refused specifically, rather than every expression being turned away. Any attempt to assign
fails with a refusal that says so.
Nothing is ever written. What the refusal costs:
- In a job parameter, the job fails.
- In a notification template, the send fails — unlike a read failure, it is not degraded. A template that assigns has to be edited; it will not start working on its own. An attempted write that degraded quietly would be a write nobody ever learned was tried.
- In an event field, the event still fires and that whole field keeps its authored text — unlike a read failure, the other tokens in that field are not substituted either.
A run's own facts cannot be used as expression source
The values the platform captures from a run — a job name, a termination description, a schedule
date, and the other names an event can resolve
— are facts, not templates. Several of them arrive from an agent on your own infrastructure, so
they are not allowed to build a token name or to be handed to Expr. A job renamed
[[OI.Secret]] = "x" would otherwise become an expression authored by whoever can rename a job.
Reading such a value is fine — [[= ToUpper([[JI.$JOB NAME]]) ]] works. Handing one to Expr is
refused.
The refusal triggers when any captured run fact was read earlier in the same expression, not
only when one is Expr's own argument. So these two are not equivalent:
[[= [[JI.$JOB NAME]] + " " + Expr("1+1") ]] refused
[[= Expr("1+1") + " " + [[JI.$JOB NAME]] ]] evaluates
Same names, same operators, different order, different answer. If an Expr call is refused and you
cannot see why, look for a run fact read ahead of it in the same expression.
Limits
| Limit | Value |
|---|---|
| Tokens in one expression | 100,000 |
| Characters a single substitution may produce | 256 KB |
Characters ToLower / ToUpper will fold | 256 KB |
Depth, total expansions, and total output length are the resolution budgets
of the string the expression sits in — the expression does not get its own. Exceeding one is reported
as a budget failure and is never degraded or swallowed by an NE fallback.
Contact support when
- An expression that worked in Classic returns a different answer here, and it is not one of the rules on this page.
- You need an expression to set a property, a threshold, or a resource count.
- A notification stops sending after a template edit and the template contains
=inside an expression.
Related topics
- Properties — the token grammar, scopes, and when tokens resolve
- Notifications — template tokens and what is frozen at event time
- Workflow events — the Completion Expression trigger, which fires a job's
event when its expression is
Trueat the job's final status