Skip to main content

Using expressions with dependencies and properties

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

  1. Write the expression inside [[= and ]], for example [[= ToInt([[JI.RetryCount]]) + 1 ]]. A property's value is always a string, so convert it with ToInt or ToFloat before you calculate with it.
  2. Use parentheses to make the grouping you want.
  3. Where an input may be bad, use the matching NE function with a fallback, such as SubStrNE or ToIntNE.
  4. Check the result in the place it is used. A job parameter fails the job if the expression fails.
Notes
  • 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.
  • Expr always returns a string.
Watch out
  • SubStr fails when the start is past the end of the string, so SubStr("", 0) fails. Use SubStrNE for 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.
  • Expr is 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.