Expr Language (pronounced like "expert" without the "t") is a simple language that lets you specify an "expression", or a formula, which is calculated for an issue or another item.
Expr can be used in:
Expr fundamentals are easy to learn, and yet the language is powerful enough to address complex needs. The following guide will cover the basic requirements of the Expr language.
For a more in-depth study, see our Expr Language Reference and Formula Reference Documentation.
You can view examples of Expr formulas in Sample Formulas or by adding bundled formulas to your structure. To see the formula, simply open the column options panel. |
An expression may contain one or more of the following:
There are also more advanced constructs:
With Expr you can build formulas that operate on:
worklogs attribute.Normally, you don't need to worry about the value types when writing a formula. The language engine will try to make sense of the formula and convert the values as needed. For more complex formulas, or if something doesn't work as expected, see Expr Function Reference for the expected types for each function. |
Variables are user-defined names, which represent attributes, such as:
Variables can contain letters (English only), numbers or underscore ("_") characters. Variables cannot contain spaces, and the first character must be a letter or an underscore.
Examples:
prioritysprintNameremaining_estimateabc11As you write your formula, Structure attempts to map your variables to well-known attributes. For example, the "remaining_estimate" variable above will automatically be mapped to the Remaining Estimate field. See Mapping Variables for more information.
Variable names are case-insensitive. |
A function calculates a value based on its arguments and, sometimes, some external aspect. A function call is written as the function name, followed by parentheses, which may or may not contain arguments.
Examples:
SUM(-original_estimate, remaining_estimate, time_spent)CASE(priority, 'High*', 5, 1)TODAY()Function names are case-insensitive. You can write TODAY() or Today().
There are 100+ standard functions available with Structure – see Expr Function Reference for a complete list.
Function arguments may be separated by comma (,) or semicolon (;). But in every function call within a formula, you need to use either all commas or all semicolons. |
The chained notation allows you to easily apply a sequence of functions to a value, simply by listing each function one after the other, separated by a ( . ) dot.
F3(F2(F1(x)))x.F1().F2().F3()When you use the chain notation, the value that comes before the dot becomes the first argument for the function. If the function takes multiple arguments, the rest of the arguments must be written in parentheses.
For example:
created.FORMAT_DATETIME("yyyy").CONCAT(" year issue") |
In this example, FORMAT_DATETIME takes the date value in "created" and formats it based on the argument in parenthesis ("yyyy"). CONCAT takes the result from FORMAT_DATETIME and joins it with " year issue".
Formulas support whole numbers, decimals, or fractions. Commas, spaces, locale-specific, percentage, currency or scientific formats are not supported.
| Recognized as a number | Not recognized as a number |
|---|---|
0 | 0,0 |
1000 | 1,000 |
| 1 100 025 |
11.25 | 1.234e+04 |
.111 | ($100) |
You can write a number that is written with a locale-specific decimal and thousands separator as a text value, and it will be automatically converted to a number if needed. For example:
|
Text strings are a sequence of characters enclosed either in single (') or double quotes ("). Examples:
'a text in single quotes may contain " (a double quote)'"a text in double quotes may contain ' (a single quote)"""Everything within a text string is retained exactly when the expression is evaluated or displayed, except for the following:
\\) is converted to a single backslash (\).\') is converted to a single quote character (') for text values enclosed in single quotes.\") is converted to a double quote character (") for the text values enclosed in double quotes.Text Snippets allow you to generate strings using variables and expressions. This is particularly helpful in formulas that utilize wiki markup.
When using text snippets:
""" $var1 + $var2 = ${var1 + var2} """
""" this $glass is half-${IF optimist: 'full' ELSE: 'empty'} """ |
Expr provides basic arithmetic operations, comparisons, text operations and logical operations.
| Operations | Comments |
|---|---|
+ - * / | Basic operators. When used, the value is converted to a number. Follows the general precedence rules for arithmetic, so (2 + 3 * 4 = 14). |
= != | Equality and non-equality: if either part of the comparison is a number, the other part is also converted into a number. If both values are texts, then text comparison is used. Text comparison ignores leading and trailing whitespace and is case-insensitive (according to Jira's system locale). |
< <= > >= | Numerical comparisons. When used, both values are converted to numbers. |
AND, OR, NOT | Logical operations. |
CONCAT | An operation that joins together two text strings. Works similar to the function of the same name: a CONCAT b is the same as CONCAT(a, b). |
( ) | Parentheses can be used to group the results of operations prior to passing them to other operations. |
When several types of operations are used, they are done in the following order:
For detailed specification, see Expr Language Reference.
Formulas can get the value of an item's property using the following notation: object.property
fixVersion.releaseDate //returns the release date for the fixVersion |
You can also string multiple property calls together:
project.lead.emailAddress //returns the email address of the lead for the project |
For a complete list of supported properties, see Item Property Reference.
Simple "IF" expressions can be declared using the IF() function, but for more elaborate IF cases, with multiple conditions and/or requiring an ELSE option, a conditional expression can be used.
WITH total = x + y:
IF total > 0:
x / total
ELSE : error |
Note: the ":" after "ELSE" is optional – in the example above, we've included it for readability.
Local variables are helpful when an expression needs to be used in the same formula several times. For example:
IF time_spent + remaining_estimate > 0 : time_spent / (time_spent + remaining_estimate) |
You can see that in this formula we are using "time_spent + remaining_estimate" twice – once when we check that it's not zero (so we don't divide by zero) and again when we divide by it.
Instead of repeating the expression every time, we can rewrite this formula using the WITH construct:
WITH total_time = time_spent + remaining_estimate :
IF total_time > 0 :
time_spent / total_time |
You can define multiple local variables in succession. You can also use previously defined local variables when defining additional local variables. For example:
WITH total_time = time_spent + remaining_estimate : WITH progress = (IF total_time > 0 : time_spent / total_time) : IF(progress > 0.5, "Great Progress!", progress > 0.2, "Good Progress", "Needs Progress!") |
Note the position of the colon (" |
An aggregate function calculates some aggregate value (like sum or minimum) based on the values in a number of rows, typically for all sub-issues. Aggregate functions are written very similar to standard functions, except they use curly braces: SUM{x}.
Examples:
SUM { remaining_estimate + time_spent } – calculates the total effort (estimated and actual) for the issue and all its sub-issues.MAX { resolved_date - created_date } – calculates the maximum time it took to resolve an issue, among the issue and its sub-issues.They can also contain modifiers, which influence how the aggregation works:
SUM#all { business_value } – this will force the function to include values from all duplicate items in the total. (By default, duplicates are ignored.)See Aggregate Function Reference for a complete list of available aggregate functions and modifiers.
Any local variables used inside an aggregate function must also be declared inside the function - within the { } . |
A User Function allows you to define a locally-used function within a formula. User functions can be defined in a similar manner as local variables:
WITH square(x) = x * x : square(impactField) / square(storyPoints) |
In this example, the user function is given a name ("square") and then used to perform the same calculation on multiple fields. To learn more, see the language reference.
When you need to perform an operation on each element in an array, you can use a user function such as the one above, or simplify it using “$” to indicate each element in the array.
worklogs.FILTER($.author = ME()) |
In this example, the "$" tells Structure to apply "author = ME()" to each element in worklogs - if the author is the current user, it returns true and that worklog will be included in the FILTER results.
This method becomes very powerful when you combine multiple user functions together. To learn more, see the language reference.
You can embed JQL and Structured JQL queries inside an Expr formula, using a construct similar to Aggregate Functions. The result will be a boolean value:
1 (true) if the current row matches the query0 (false) otherwiseFor example:
// Collect total story points from all sub-issues assigned to members of Team2 group, unless the stories are under folder "Special"
SUM {
IF JQL { assignee in membersOf("Team2") } :
IF NOT SJQL { descendant of folder("Special") } :
storyPoints
} |
Since JQL is a Jira-based query, it will work only on issues; the result will be |
Comments are helpful when you have a large formula or when a reader might need explanations of what is being calculated. It's a good idea to add comments wherever the formula is not trivial.
// /* and end the comment with */Example:
// This is a single-line comment. /* This is a multi-line comment. It can be useful for longer explanations. */ |