Expr Language

An expression may contain one or more of the following:

• Variables - these are mapped to issue fields.

• Arithmetic and logical operations - add, subtract, multiply, divide, or compare items. 
• Numbers
• Text strings
• Function calls - apply specific calculations to the provided arguments and return a result to be used in the expression.

• Property access - get the value of a particular item property - such as the release date of a fix version.

• Conditional ("IF") expressions - calculate different results based on a specified set of criteria.

There are also more advanced constructs:

• Aggregate Functions - calculate an aggregate (such as the sum or average) of an expression's values calculated for multiple items in the structure.
• Local Variables - introduce a value and reuse it multiple times in the formula.
• User Functions - define a function, or a functional expression, to be reused in the formula or applied to an array of values.

• JQL  queries inside a formula - condition the results based on whether an item matches a query.

• Comments - document larger formulas.

With Expr you can build formulas that operate on:

• Basic values – numbers and text, which are either a part of the formula, or read from a Jira field, such as an issue's Summary or Story Points.

• Array values – a sequence of values, allowing you to represent multi-value fields such as Fix Versions.

• User function values – representing a piece of formula that is typically applied to each element in an array, for example, for filtering.
• Key-value maps – in rare occasions, these values are produced by the supplied functions like GROUP.
• Undefined – a special value that means "nothing" or "no value".
• Error values – produced if there was a problem calculating a formula.

Variables are user-defined names, which can represent:

• Jira issue fields

• Calculated attributes like Progress

• Structure-specific attributes like Item type

• Attributes provided by other Jira apps

• Another formula

• Values from another Structure column

Naming Variables

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:

• priority

• sprintName

• remaining_estimate

• abc11

As you write your formula, Structure attempts to map your variables to well-known sources.For example, the "remaining_estimate" variable above will automatically be mapped to the Remaining Estimate field. See Mapping Variables for more information.

Local Variables

IF time_spent + remaining_estimate > 0 :
   time_spent / (time_spent + remaining_estimate)

WITH total_time = time_spent + remaining_estimate :
  IF total_time > 0 :
     time_spent / total_time

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!")

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.

Chained Function Calls

created.FORMAT_DATETIME("yyyy").CONCAT(" year issue")

Aggregate Functions

User Functions

WITH square(x) = x * x : 
  square(impactField) / square(storyPoints)

// Collect total story points from all sub-issues assigned to members of Team2 group
SUM { 
    IF JQL { assignee in membersOf("Team2") } : 
      storyPoints
}

Formulas support whole numbers, decimals, or fractions. Commas, spaces, locale-specific, percentage, currency or scientific formats are not supported.

Text Strings

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:

• A sequence of two backslashes (\\) is converted to a single backslash (\).
• A sequence of a backslash and a single quote (\') is converted to a single quote character (') for text values enclosed in single quotes.
• A sequence of a backslash and a double quote (\") is converted to a double quote character (") for the text values enclosed in double quotes.

Text Snippets

Text Snippets allow you to generate strings using variables and expressions. This is particularly helpful in formulas that utilize markdown.When using text snippets:

• The snippet should be enclosed with """ (three double quotes, at the beginning and at the end)
• The expression portion of the snippet is introduced using the '$' symbol and should be enclosed in braces { }

""" $var1 + $var2 = ${var1 + var2} """
 
""" this $glass is half-${IF optimist: 'full' ELSE: 'empty'} """

Expr provides basic arithmetic operations, comparisons, text operations and logical operations.

Order of Operations

When several types of operations are used, they are done in the following order:

1. Arithmetic operations
2. Text operations (CONCAT)
3. Comparison operations
4. Logical operations. 

For detailed specification, see Expr Advanced 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

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.

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.

• To add a single line of comment, begin the comment with //
• To add multiple lines of comment, start the comment with /* 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. */