Introduction
The Automation Toolbox for Jira expression parser provides over 200 functions and operators to read, manipulate and filter data from Jira issues, users, groups, projects and more.
Among the long list of functionalities, the parser functions support setting and/or updating field values, issue filtering, date and time calculations, string manipulation and the execution of mathematical operations.
The expression parser has been in constant development since 2009 when it was first introduced in Jira Workflow Toolbox. Since that time, the expression parser has seen constant development, improvement, and extended functionality.
Main Features
The expression parser has two major core functionalities:
- extended accessibility to
- issue
- system
- project
- version
- component
- and user data through the use of Virtual Fields
- an extensive set of operators and functions to
- read
- filter
- extract
- manipulate
- write
- update related data
Field codes and usage
One of the most important features of Automation Toolbox for Jira is the easy accessibility to Jira data stored in system fields, custom fields and a significant number of other, virtual fields that are made available by the Automation Toolbox for Jira implementation. You can access, validate, do mathematical calculations and manipulate the values found in these fields through the use of field codes. These codes are unique identifiers (keys) to all available fields. Automation Toolbox for Jira uses field codes in triggers, conditions, selectors, and actions: Field codes are not only used as unique field identifiers, but they are also an important safety feature for the Jira instance. Custom fields, for instance, can be renamed and the names do not have to be unique, but using Automation Toolbox for Jira field codes make the fields you use in your rules immune to renaming. You can choose the appropriate field codes by using the drop-down lists that Automation Toolbox for Jira makes available wherever expressions can be used. Depending on the context in which they are being used, field codes will contain a prefix following this notation: {origin.field/data}. Available contexts (or origins) in Automation Toolbox for Jira are: Trigger Selector The issue currently being processed by the selector. (e.g. an issue returned by a JQL query). Selectors usually hold multiple issues. They will processed iteratively one by one. System All selected custom fields will be notated like this %{trigger.issue.cfnnnnn} where nnnnn contains the Jira custom field id. The purpose of using the cfnnnnn notation is quite simple - custom fields can be renamed . Field codes must always be enclosed by curly brackets (or braces) but if they are used for text-strings, the brackets must be preceded by a percent sign %. NUMBER or Date-Time fields can be referenced as numbers using the following notation: {somenumberfield}. ( no preceding % sign) STRING Any field type or data type is susceptible of being transformed to text, so any field can be referenced as a text-string value using the following notation: %{somefield}. Cascading Select or Multi-Cascading Select fields, where i is the index that represents the level to be accessed. (i = 0 is used for base level) are notated as %{somefield.i} . A full list of available data types can be found here. Wherever field codes are used in the documentation they will be notated with three periods (...) instead of prefixes. The example below shows and expression usage in a Boolean Condition.Overview
Field code notation
Context Description The issue, user, version, component or project event that triggers the execution of the rule. Some data does not have an issue context (e.g. the currently logged in user or the system date and time)
The prefix, denoting the origin (where the data should be read from / written to), is a referential part of the field code and will be inserted into the expression whenever you select a field from a dropdown list (as shown below).
Here are some examples:
Field codes for Jira standard or system fields will display the attribute in a legible form like %{trigger.issue.summary}.
Once an expression has been saved, the real name will be displayed in the configuration element.Field codes: STRING vs. NUMBER
Field codes in the documentation
Example of using field codes
Virtual fields
All comprehensive overview of all available virtual fields can be found here.
Remember
Numeric field codes are only available for number fields, date/time fields and countable virtual fields.
Functions and Operators
Please use one of the following links for detailed descriptions of functions and operators.
- Numbers, Dates and Times - Mathematical operators
- List operators
Functions
- Issue data functions
- User, Group & Role functions
- Version functions
- Field history functions
- Selectable fields functions
- Mathematical functions
- Date-Time functions
- String functions
- String list functions
- Issue list functions
- Number list functions
- Cast functions
You can find all functions here.
The Expression Parser Syntax Specification
Automation Toolbox for Jira uses a powerful expression parser for interpreting expressions with logical, mathematical, date-time and string-text terms.
This parser is a fundamental part of the app, and is used by various features in the app. The parser offers very similar functionality to the expression parser known to Jira Workflow Toolbox users. There are some differences, mainly in field code usage and the lack of ephemeral fields.
You can use the provided parser functionality with a number of triggers, conditions, actions and selectors.
The following is a simple example of parser usage for the Condition → Boolean Condition .
The condition will return true if the issues Due date is greater than the current date.
The available Selectors, Conditions and Actions depend on the selected Trigger.
The syntax depends on the parser mode and the context of the rule. Therefore the following table explains the different parsing modes.
#basic parsing mode %{trigger.issue.description} Last comment: %{trigger.issue.comment.last} #advanced parsing mode %{trigger.issue.description} + "\nLast comment: \n" + %{trigger.issue.comment.last}
Parsing modes
There are multiple parsing modes available in the expression parser. The two most commonly used parsing modes are:
- Basic: with this simple parsing mode you can write free text and insert field codes with format %{nnnnn} or %{nnnnn.i} anywhere in your text. These field codes will be replaced at runtime with the corresponding field values of the issue currently being processed
- Advanced: with this parsing mode we can do much more complex text composition thanks to the usage of functions for replacing substrings, changing case, reading fields in linked issues, sub-tasks, JQL selected issues, and much more. It requires the text to be parsed to be written as string expression respecting the parser syntax.
- Automatic parsing mode converter: You can write your text in basic mode, and then switch to advanced mode. The text to be parsed will be automatically rewritten as a string expression. Now, you can simply make the modifications you require, making use of text formatting functions, or inserting math or time expressions where needed.
The Expression Parser offers you different modes to provide a flexible usage in certain places. You can calculate an issue due date depending on the current date or filter the issue sub-tasks by status to add a comment to those.
To update issue fields the parsing result will be cast to the expected value e.g. a user name will be cast to a user to update a user field like the assignee field.
Mode | Supported features | Return type | Example |
---|---|---|---|
Basic | Field codes | String Object | The basic parsing mode supports the usage of field codes. Field codes can be used to access issue field values. simple text using a field code to read the summary This is the issue summary: %{trigger.issue.summary} |
Advanced | Field codes Parser Functions | String Object | The advanced parsing mode has a defined syntax that allows you to write functions to read and manipulate data from any issue in Jira. Field codes are supported as well as clear text, written in quotation marks. Advanced expression to read the issue summary and use a function to get the assignee mail address "This is the issue summary:" + %{trigger.issue.summary} + " and the assignee mail is: " + userEmail(%{trigger.issue.assignee}) |
Math/date time | Field codes Parser Functions | Number Date Date Time | The mathematical and date time parsing mode works like the advanced mode but expect a number as result instead of a string. The resulting number is used to updated numeric or date time fields. In case of date or date time fields the number will be cast to a date. Time to resolve the issue {trigger.issue.resolutionDate} - {trigger.issue.createdDate} |
Logical | Field codes Parser Functions | true false | The logical parsing mode works like the advanced parsing mode but expression result must return true or false. Check if the assignee is equals the reporter {trigger.issue.assingee} = {trigger.issue.reporter} |
Issue List | Field codes Parser Functions | issue list | |
String List | Field codes Parser Functions | string list | |
Mixed | Field codes Parser Functions written in three curly braces | String |