The Expr language is used in the Formula columns to produce calculated values based on Jira data. This reference is a detailed description of the Expr language, its syntax, and the calculation rules.
To start learning Expr and what you can do with Structure Formulas, check out our more high-level Expr Language description. What follows is advanced material that may be useful for digging deeper, troubleshooting, or building advanced formulas. It may require some programming knowledge.
This reference contains railroad diagrams to illustrate some of the language syntax. They are intentionally simplified and should not be considered a full definition of the language.
All expressions, when evaluated, produce either a value or an error. All values are immutable – if you need to change a value, you derive another value from it.
Each value belongs to a certain type. There are simple and complex types.
Simple types represent just one value and allow you to write literal values (constants). Simple types are:
Undefined
Text
Number
Complex types represent a value that has some internal structure. Complex types are:
Item
Array
User Function
Key-Value Map
Errors are special values, but they usually cause the whole expression to return an error.
A library function may expects certain types as parameters and will produce a particular type as the result. Expr will also try to convert one type to another as needed.
Undefined
Undefined is a special value, which represents "no value" or a missing value. For example, variable Assignee will have undefined value if the issue is unassigned.
Undefined value can be used instead of a value of any other type.
To use the undefined value in a formula explicitly, you can write undefined.
Functions can return undefined when the result of the function is not specified. For example, the function IF(N = 0; "No apples"; N = 1; "One apple") only has a specified value when N is equal to 0 or 1. If N is equal to anything else, it returns undefined.
Text
A text value consists of 0 or more Unicode symbols. Its literal representation consists of the value enclosed in single quotes (') or double quotes ("). Example: "Major" represents text value Major. Similarly, 'Major' represents the same text value.
If the text value itself contains quotes, you'll need to insert a backslash (\) before them. Example: "Charlie \"Bird\" Parker" represents the text value Charlie "Bird" Parker. Alternatively, you can use another kind of quotes to enclose the literal representation: 'Charlie "Bird" Parker'.
If you need to use the backslash at the end of text value, you will need to insert another backslash before it. Example: "C:\Users\John\\" represents text value C:\Users\John\.
Text Snippets (""")
Sometimes you need a long text value that contains some words and symbols, but also the value of a certain expression or a variable. One way to create it is to use the CONCAT function and join all the pieces of text together. A more convenient way could be writing a text snippet.
A text snippet starts with triple double quotes (""") and continues until the next triple double quotes. It includes ends of line, so you can create multiline text values with a text snippet.
Text snippets may contain special sequences that get replaced with a calculated value:
A dollar sign followed by a variable name is replaced by that variable's value. For example,
"""Assigned to: $assignee""".A dollar sign followed by an Expr expression in curly braces is replaced by the value of that expression. For example,
"""Total score: ${ score + subtasks.score.SUM() }""".
Number
A number represents a single numerical value. Aside from representing some quantity, a number value can also represent a point in time or a duration of time. In this case, you can use Format settings in the Formula column to properly display the results as dates or durations.
There are two forms of literal representations of numbers:
a whole number:
42a fractional number:
0.239
Note that only dot (.) can be used as a decimal separator. Comma (,) is used to delimit function arguments. Thus, MAX(X, 0,618) will be understood as the maximum of three values: X, 0, and 618.
Group separators are not supported, so 100 000 is not a literal representation of number 100000. However, you can write a string value and explicitly call the conversion function – NUMBER("100 000").
Technical note: internally, numbers are represented as decimal floating-point numbers with 16 digits of precision and half-even rounding. Most of the operations are carried out in this form; however, some of the more sophisticated functions, such as SQRT, might first convert the numbers into binary floating-point, calculate the result and then convert it back into decimal floating-point.
Date and Date/Time
A Date/Time value is represented as an integer number of milliseconds since Unix epoch (1970-01-01 00:00:00 GMT). Date functions will help you convert those numbers to readable Text values.
A Date value (without the time component) is represented in the same way as the date/time value, calculated for the midnight of the specified day – in the user's current time zone. 
This means that expressions involving Date values (for example, using Jira's Due Date field) may produce different results for different users if they are in different time zones.
Duration
A Duration value is represented as an integer number of milliseconds. Duration functions help transform duration values into readable Text values.
Boolean
A boolean value, such as returned from comparison functions, is represented by a number 1 if true, or 0 if false.
Additionally, all values can be converted to a boolean value based on whether they are "truthy". (See Value Conversions.)
Item
An item value represents an object that you can potentially have as a row in a structure – a project, sprint, version, status, priority and others. It can also represent purely Structure-owned objects like flex items.
Items have properties that you can access by writing item.propertyName, or (item-resulting expression).propertyName. The types of items, their properties and their type is listed in Item Properties.
Special conversion of Item values
Item values always can be used as Text. Each item will then be represented by a text – an issue by issue key, a project by its name, etc.
Array
An array value is a list of other values. Each value in an array is called an element of the array.
Each value in an array may be of any type – you can have an array of texts, array of items, array of arrays, and so on. An array can contain different types of values in each element – the first one could be a number, the second one an item, and the third one an array of some other elements.
The values in an array may be accessed by their index. The first value has index 0, the second value has index 1, and so on.
There's a number of array functions that allow you to write formulas that deal with multiple values – see Array Functions.
Creating an array
You can create an array by calling the ARRAY function: ARRAY(element1, element2, element3, ...)
When you need to change an array, you apply some transformations to an existing array – most frequent being FILTER and MAP. This effectively creates a new array.
Accessing array elements
You can access an element of an array by its index, using the GET function: array.GET(index)
However, it's typically not needed, as the calculations with arrays are done mostly with FILTER, MAP and REDUCE.
User Function
A user function value (sometimes called a "lambda value") represents a piece of Expr code that defines a function – see User Functions below.
Typically, you create a user function value to apply it to an array via one of the system functions, such as FILTER or MAP.
For example, consider the following code:
|
There are three user functions here, $.author = ME() , w -> w.timeSpent , and (a, b) -> a + b . The first defines the condition for filtering work logs, the second defines how to transform each work log into a number, and the third one defines how to aggregate multiple numbers into one.
Each of these three pieces of Expr are evaluated and are represented by a value of the "User Function" type, and passed to FILTER, MAP, and similar functions.
As with any other value, a User Function value can be assigned to a variable. A more traditional function definition form could be used for that. The following two definitions are identical:
|
Key-Value Map
A key-value map is produced by some of the Expr functions, and is a collection of pairs, where "key" is the property name and "value" is the property value.
Currently, only GROUP function creates a key-value map, with key group mapping to the value the array is grouped by, and key elements mapping to an array of the matching elements.
To access the value, you need to write kvm.keyName, where kvm is a local variable or an expression that represents the key-value map.
Keys are supposed to be well-known; there's no way to iterate over all keys.
There's no way for the user to create an arbitrary Key-Value Map; this type is intended only for some system functions.
Errors
Errors are special values, which indicate that the calculation of some part or the whole of the expression encountered a problem.
The list of possible errors is available at Expr Error Codes.
Normally if an error occurs somewhere in the formula, the result of the whole calculation is an error as well. But, if receiving an error from a part of the expression is legitimate, you can use the IFERR and ISERR functions to handle it.
A conditional "IF" expression allows you to switch between two expressions, based on whether a condition is true (truthy) or false. It is identical to calling the IF function with two or three arguments.
The "ELSE" part, as well as the colon (":") after ELSE are optional. If the ELSE part is omitted, and the test expression evaluates to false, the result is undefined.
If you use nested IF expressions with only one ELSE, the ELSE part applies to the innermost IF. We recommend using parentheses to make it clear which IF it applies to.
You can use indentation to make the formula with nested IFs more readable – but the indentation has no effect on how the formula is parsed. Use parentheses!
Examples:
IF dueDate < NOW() : "overdue!" ELSE: """${DAYS_BETWEEN(NOW(), dueDate) - 1} days left!"""
---
IF priority = "Critical":
IF dueDate < DATE_ADD(TODAY(), 7, "days"):
"critical and urgent"
ELSE:
"critical and not urgent"
Some Expr values – Items and Key-Value Maps – contain "properties", named values that are parts of the bigger value. For example, a Version item contains properties such as "name", "description", "releaseDate". And function GROUP returns a value that is an array of Key-Value Maps, each map having "group" and "elements" properties.
To access a property, use the dot ("."), followed by the property name. The names are case-insensitive.
Examples:
version.releaseDatesprint.startDateissueType.isSubtask
undefined – not an error! (See also a note about arrays below.)There's no way to check if a value contains a certain property (other than try and access it), or list all available properties for an item.
Accessing Property of Each Element in an Array
You can apply property access to an array of values. Expr will then apply property access to each element and return the result as an array.
For example:
- version.releaseDate – will return an array of release dates
undefined results will be removed and the array will be flattened. This is the same behavior as shown by functions with /Each parameter type.
A function takes zero or more values, and produce another value. A function call consists of a function name (an identifier), followed by its arguments enclosed in parentheses. An argument can be any expression. Different arguments are separated by commas (,) or semicolons (;) — for one function call, all separators must be the same.
Examples:
NOW()ROUND(storyPoints / 10)FILTER(sprint, $.state = "active")MAKE_DATETIME(2017; 12; 31; 23; 59; 59)myUserFunction("argument1", "argument2")
A function call can evaluate only some or even none of the arguments, depending on the function. This is useful for functions that perform choices. For example, in an IF function, the argument that wasn't chosen is not evaluated, so the whole expression doesn't produce an error when that argument produces an error.
System and User Functions
System functions are provided by Structure. The functions are listed in the Standard Functions. Each function expects a certain number and type of parameters.
User functions are explained in the next section. A user function is called using the same syntax as a system function.
User functions can take any number of arguments, regardless of how many arguments are declared. If a parameter was declared, but a value was not provided when calling the function, the parameter's value will be undefined.
Chained Function Calls
A different way to call a function is by "chaining" it to its first argument by adding a period ("."), a function name, parentheses, and any additional parameters, if any.
For example, sprint.FILTER($.state = "active") is the same as FILTER(sprint, $.state = "active").
This allows nice, readable expressions, where a value is sequentially transformed by applying functions to the result of a previous function call:
affectsVersion.MAP($.releaseDate - $.startDate).MAX()
Unlike some other languages, in Expr any function may be written in the chained syntax, regardless of what the value is.
Applying Functions to Arrays
When a function is applied to an array value (meaning that an array is passed as the first argument of the function), the result may be calculated in a number of ways, depending on which function is called and what type of argument it expects.
You can always apply a function to each element of an array using the MAP function. For example:
array.MAP(SOME_FUNCTION($))
The cases below relate to cases where an array is passed directly as an argument: SOME_FUNCTION(array).
Using an Array Function
There are special functions that expect an array as their first argument – FILTER, MAP, and others.
There's no special behavior in this case – an array is expected. In fact, if the value passed is not an array, it will be converted to either an array of one element (containing that value), or an empty array if the value is undefined.
Passing Array as an Argument of Text/Joined Type
If a function declares that it expects "Text/Joined" as an argument, then the system will try to convert an array into a text value. See the "Text vs Text/Joined" section above.
For example:
CONCAT("Versions: ", fixVersion) → "Versions: v1, v2, v3"
Passing Array as an Argument of /Each Type
If a function declares that it expects "Number/Each" or "Text/Each" or any other "/Each" type as an argument, then it would work on that simple type, but if an array is passed, it will apply its logic to each element in that array. The result of calling this function will be an array, where each element is a result of applying the function to the original element.
For example:
UPPER(fixVersion) → ARRAY("V1", "V2", "V3")
In addition, when applying a function to an array in this way, the resulting array is "flattened" (elements from any sub-arrays moved to be the elements of the top array) and "compacted" (all undefined elements are removed).
Passing Array to a User Function
You can call a user function and pass an array as an argument. No special handling takes place – just as with a system function expecting an array.
All Other Cases
If a system function does not expect an array, but it is passed as an argument, it will try to convert it to the value type it expects. A one-element array will be converted to its single element and an empty array will be converted to undefined. See "Value Conversions" above.
If the conversion is not possible, the result will be an error.
User Functions are functional expressions, defined by the user. (They could also be called "lambdas".) User functions are helpful when the user needs to apply some repetitive action, or to pass an action to be applied to each item in an array.
A User Function contains a list of parameters and then an expression that is calculated for these parameters.
A User Function is a type of value, so you can assign a user function to a local variable, or pass it to some higher-order function as a parameter.
There are three ways to define a user function.
Functional Expression
A functional expression is the canonical form for user functions. It contains a list of parameters in parentheses, followed by the "maps to" symbol (->), followed by the expression calculated by the function. When there's only one parameter, the parentheses can be omitted.
Examples:
() -> START_OF_MONTH(NOW())(x) -> x * xversion -> version.releaseDate - version.startDate(s1, s2) -> s1 CONCAT " " CONCAT s2
All these examples evaluate to a "User Function" value type, which can be assigned to a variable:
WITH square = x -> x * x : ...
Traditional Function Definition
A more traditional function definition looks similar to a variable definition, only the variable is followed by a list of parameters in parentheses, and the expression is based on those parameters.
To rewrite the examples above:
WITH currentMonth() = START_OF_MONTH(NOW()) : ...WITH square(x) = x * x : ...WITH versionDuration(version) = version.releaseDate - version.startDate : ...WITH joined(s1, s2) = s1 CONCAT " " CONCAT s2 : ...
These declarations are identical to the corresponding examples in the previous section, with local variables assigned to the corresponding User Function values.
Implicit Functional Expression ($)
Most of the time when we're creating a formula with an array, we need to apply some kind of operation to each element of the array. Implicit functional expressions help define the corresponding user function easily by having "$" denote "each element".
For example:
versions.FILTER($.startDate < NOW())worklogs.UMAX_BY(IF $.author = ME() : $.timeSpent)
In each case, the expression with "$" is transformed into a User Function with a single parameter, which is then substituted for $. So, the last example from the list above is identical to:
worklogs.UMAX_BY(w -> IF w.author = ME() : w.timeSpent)
When reading these expressions, you can say "each" when the dollar sign is encountered.
An implicit user function must always be used in an argument to a system function, which expects a user function. Otherwise, it won't be accepted.
For example – here's how we can filter an array to contain only even numbers:
| Correct | Incorrect – Parse Error |
|---|---|
... or, alternatively ...
|
|
Calling User Functions
If a User Function is assigned to a variable, you can call it in your expression in the same way you call a system function.
WITH square(x) = x * x :square(impact) / square(cost)
You can also use the chained function call notation:
WITH square(x) = x * x :WITH fquare(x) = x.square().square() :storyPoints.fquare()
Note that you cannot invoke a functional expression unless it is assigned to a local variable. The following will produce an error: (x -> x * x)(3)
Function Name Collisions
Both system functions and user functions are invoked in the same way – FUNCTION_NAME(arg1, arg2, arg3, ...), or with a chained call syntax – arg1.FUNCTION_NAME(arg2, arg3, ...). This leaves a potential for the user to define a function that has the same name as a system function.
When Expr encounters a function call, first it looks up if there is a system function of that name.
The system function will be called even if there's a local variable of the same name. To protect the user from name collisions, Expr will show an error if you try to define a function with a name that matches a system function name. (However, it won't be able to detect the collision if a local variable is defined through a series of assignments of a functional expression.)
You can define a local variable of any other type with a name identical to a system function's name.
| Works as expected | Error |
|---|---|
// Using "SUM" as a local variable,
// but "SUM()" is also a system function
// and "SUM{}" is an aggregate function.
WITH SUM = cost + parent.cost :
SUM(SUM, SUM { cost })
| // Cannot define a user function with a name collision. // Note that the language is case-insensitive: "SUM" and "sum" are the same. WITH sum(issue) = issue.timeSpent + issue.parent.timeSpent : ... |
Note that the function name collision resolution provides potential challenges when upgrading to a newer version of Structure, if that version introduces new system functions.
Let's say you have defined a user function LAST_COMMENT() in your formula and used it successfully in an older Structure version. If the newer version of Structure adds a system function LAST_COMMENT(), that formula will likely stop working after the upgrade, and you will need to rename the user function.
To minimize the probability of this happening, we suggest naming your user function in a way that makes potential collision unlikely. It could be a name that is very specific to your configuration, or you can always prepend the name with an underscore – in our example, call it _LAST_COMMENT().
An aggregate function calculates values for some other rows in the structure (for example, for all sub-items), aggregates these values (for example, adds them together), and produces the resulting value to be used in the formula.
For example:
SUM#children { storyPoints }– calculates total story points for all the child issues.PARENT { fixVersion }– provides the value of the fixVersion field from the parent's issue.VALUES { components }– collects all distinct components that are set for any of the sub-issues of the current row.
Aggregate functions allow you to calculate complex values that depend not only on the "current" item, but also on other items in relation to it.
An aggregate function starts with a name, optionally followed by modifiers, then curly braces ("{}"), and inside them – an "inner expression", which will be calculated for some other rows. You can use whitespace between any elements of the aggregate function calls.
The inner expression may return any type of value – number, text, array, and others – except a user function. You cannot pass a user function from the inner formula into the outer formula.
Available Aggregate Functions are listed in Aggregate Functions.
Aggregate Function Modifiers
An aggregate function may have one or more modifiers that govern the aspects of the function's execution. Each modifier starts with hash sign ("#"); then comes the modifier's name; optionally followed by the equals sign ("=") and a value, which can be a string or a numeric constant. If a value is omitted, it is assumed to be 1 (a representation of true in Expr).
Examples:
SUM#all { cost }SUM#all#leaves { IF type = "story": storyPoints }JOIN#separator=", " { key }JOIN #separator=", " #fromDepth=0 #toDepth=-1 { key }
Each aggregate function supports a specific set of modifiers, not all of them. Using an incompatible modifier will result in an error. To learn more about available modifiers and their restrictions, see Aggregation Modifiers.
Sharing Values Between Outer and Inner Formulas
It's important to understand that the formula inside an aggregate function – the inner formula – is calculated fully separately from the "outer" formula. Both formulas will share variable mappings (to fields), but any local variables and user functions defined on one side will not be accessible from the other side.
| Will not work! | Correct version |
|---|---|
// Cannot use "total" on line 4!
WITH total = SUM#children { storyPoints } :
WITH median = MEDIAN#children { storyPoints / total } :
...
| WITH median = MEDIAN#children {
WITH total = PARENT { SUM#children { storyPoints } } :
storyPoints / total
} :
...
|
As you can see from the example above, you may need to use nested aggregate functions instead.