This article is for Data Center. Visit Cloud
Expr Advanced Reference
- Jaramy Conners
The Expr language is used in the Formula columns and in other places in Structure to produce calculated values based on Jira and Structure 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 Sample Formulas or a more high-level Expr Language description. This is an 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:
42 - a 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 Jira issue, project, sprint, version, user, status, priority and others. It can also represent purely Structure-owned objects like folders.
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 Property Reference.
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.
Also, items may be compared using UMAX and UMIN functions, which will respect the "natural" order for the items. Most items will be compared alphabetically, but some will have a predefined order, like Priority items.
Special treatment of Item values by generators
Similar to max/min operations, if a formula column produces Item values, then you can sort by that column (or use Attribute Sorter) to reorder the structure according to the natural order of the resulting items.
If an Attribute Grouper is configured with a formula that produces Item values, the groups will become those items.
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.
Special treatment of Array values by the Attribute Grouper generator
When an array value is returned by a formula to the Attribute Grouper generator, it will create multiple groups – one for each non-empty, distinct value returned by the formula.
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.
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.
The declaration syntax is the following:
Note the colon (":") that separates the expression assigned to the variable and the expression where the variable is used.
A few facts about local variables:
ExpressionWithLocalVariablemay 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 ofprioritywill 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 theWITH...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.
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 assignee = ME() : "mine!"
---
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
An alternative way to access a property is by using the ACCESS() function – in this way, the property name itself may be calculated:
parentTask.ACCESS("Story Points")
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 Custom Fields via Properties
In most cases a formula will refer to the issue's custom fields directly by name – for example, the formula impact / storyPoints uses the values of two custom fields, Impact and Story Points, of the currently calculated issue to calculate the benefit-to-cost ratio.
You can, however, use a formula to access other, related issues, and their corresponding custom fields – for example, the formula impact / (storyPoints + subtasks.storyPoints.SUM()) calculates a similar value but takes into account the cost (in story points) of all the subtasks.
Note that the actual custom field is named "Story Points", with a whitespace. When you access a property of an issue item, Structure tries to match the property name with available custom field names using loose rules, dropping whitespace and any non-identifier-friendly characters. The property name is also case insensitive.
You can also use the ACCESS() function to specify the name of the field precisely, or use "customfield_NNNNN" property name to identify a field by its ID.
parent.storyPointsparent.ACCESS("Story Points")parent.customfield_10000
You can use this variable to access properties of the currently calculated item. Normally it's not needed, since the same values are available as corresponding variables.
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:
- fixVersion.releaseDate – will return an array of release dates
- worklogs.author.UNIQUE() – will return a list of people who logged work
- subtasks.remainingEstimate.SUM() – will return a total remaining estimate from the subtasks
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 Expr Function Reference. 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()
linkedIssues.FILTER(x -> NOT x.resolution).MAP(x -> x.remainingEstimate).SUM()
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())issueLinks.FILTER($.type = "Relates").MAP($.destination)
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 Function Reference.
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 attributes), 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.
Using Formulas with Aggregate Functions in Generators and Transformations
Note that when you use an aggregate function, it relies on the existing structure to figure out the parent item, child items, and other related items addressed by the formula. When the formula is used to build or transform a structure, the hierarchy and items that the aggregate functions "see" will correspond to the structure that exists immediately before the generator or the transformation is applied.
Therefore, when using a formula with Attribute Filter, Attribute Grouper, Attribute Sorter and other generators, you should apply aggregate functions carefully, understanding what is the preceding structure before the generator is applied. For example, if you use a grouper on a folder with a flat list of issues, the formula in the grouper will see issues and the folder will be their parent item – there are no groups yet!
You can embed JQL and S-JQL in a formula to check if the item (the one the formula is being calculated for) satisfies the condition of the query – that is, it will be a part of the query result.
The syntax is similar to calling an aggregate function:
IF JQL { assignee in membersOf("Team-Alpha") } : ...IF NOT SJQL { descendant of folder("Excluded") } : ...
The result of evaluating JQL {} or SJQL {} is always 0 (false) or 1 (true).
When SJQL is used, it is always applied to the current structure. (Or the one being generated – see the note below.)
Note that, unlike aggregate functions, these constructs do not use Expr, but rather another other languages, as the inner expression. Use the corresponding documentation as a reference for JQL and S-JQL.
The embedded queries are calculated separately from the Expr formula they are used in. Therefore, you cannot use any values from the Expr formula inside a JQL or SJQL query or vice versa. Also, you cannot check the query match for any other item except the one the formula is being calculated for.
In other words, the only data that is passed between an embedded query and the outer Expr formula is 1 or 0 depending on whether the current item matches the query.
Using S-JQL in Generators and Transformations
An S-JQL query usually depends on the structure it's being calculated for. So, similar to Aggregate Functions, when you use a formula with an embedded S-JQL in a generator or a transformation, the query will be applied to the underlying "preceding" structure, that exists before the generator is applied.
S-JQL Query Performance
Structure optimizes the calls to embedded queries. A query will be run only once for multiple items that the formula is being calculated for, and the result will be checked separately in the calculations for each row.
That said, the JQL itself may potentially be an intensive calculation, if it uses JQL functions or historical conditions like WAS. Please be careful when trying this JQL in a formula, and watch for how long the value is being calculated before publishing the formula for other users. Normally, calculating a "heavy" formula should not prevent users from doing other things in Structure (including using other columns with formulas), but it can place some stress on the Jira server.
Please avoid using the structure() JQL function in JQL or S-JQL that is being embedded in a formula.