Expr Advanced Reference - Property Access

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.releaseDate
sprint.startDate
issueType.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")

If the value does not have the requested property, or if the value is neither an Item nor a Key-Value Map, the resulting value is 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.storyPoints
parent.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

In the resulting array, all undefined results will be removed and the array will be flattened. This is the same behavior as shown by functions with /Each parameter type.