Expr Advanced Reference - Local Variables

Local variables are similar to Variables, but they are not mapped to an item's attribute or Jira field, but rather defined and calculated right in the expression.

If you plan to use an expression more than once in the same formula, you may want to turn it into a local variable, using WITH :

CODE

WITH total_time = timeSpent + remainingEstimate :
  IF total_time > 0 :
     timeSpent / total_time

In this example, declaring a local variable “total_time” ensures that every instance of total_time is exactly the same - and if we ever need to change how we calculate total_time, we only have to change it once.

Declaring a Local Variable

Local variables are declared using the following construct:

WITH variable_name = value_represented_by_the_variable :

Multiple Local Variables

You can define multiple local variables in succession. You can also use previously defined local variables when defining additional local variables. For example:

CODE

WITH total_time = timeSpent + remainingEstimate :
WITH progress = (IF total_time > 0 : timeSpent / total_time) :
  IF(progress > 0.5, "Great Progress!", progress > 0.2, "Good Progress", "Needs Progress!")

Note the position of the colon (:) – it must be present where each local variable definition ends.

A few facts about local variables

ExpressionWithLocalVariable may start with another local variable definition, so you can introduce many local variables in sequence. When defining a second variable, you can use the first variable already defined, and so on.
Local variables can "shadow" previously defined local and free (mapped) variables with the same name. If you write WITH priority = 10: <expression>, then when calculating <expression>, the value of priority will be 10, even if there was a variable attached to the issue's priority in the enclosing scope.
The WITH... construct is itself an expression, so you can use it, enclosed in parentheses, anywhere an expression can be used. The name defined in this expression is not visible outside the WITH... expression.

Immutability

Expr language constructs are immutable. Once a local variable is defined, it cannot change its value. (So, in fact, calling it a "variable" is not exactly correct. Although, if a local variable depends on external variables, which vary from item to item, the local variable itself will also vary from item to item.)

So if you're building your formula and you need to take a number of values through a series of calculations, you may need to use multiple local variables, going through each step and assigning each intermediate result to another local variable.