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

Automation Toolbox for Jira provides a set of special fields called virtual fields, making almost all properties of issues, projects and users accessible to every feature in the app.

Virtual fields may be read and written by Automation Toolbox for Jira in the same way ordinary custom fields are.

Virtual fields and their associated field codes, were created to

• provide data accessibility beyond the scope of normal Jira workflow processing
• insure data integrity throughout their use.

In Automation Toolbox for Jira you can use virtual fields by searching for and picking their associated field codes in the dropdown menus provided wherever a parser expression can be inserted. 

All comprehensive overview of all available virtual fields can be found here. 

%{issue.summary}

%{issue.description}

%{issue.assignee}

%{parent.issue.assignee}

%{issue.votes}

Functions and Operators

Please use one of the following links for detailed descriptions of functions and operators.

• Boolean expressions - Logical and conditional 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.

#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.

This is the issue summary: %{trigger.issue.summary}

"This is the issue summary:" + %{trigger.issue.summary} + " and the assignee mail is: " + userEmail(%{trigger.issue.assignee})

{trigger.issue.resolutionDate} - {trigger.issue.createdDate}

{trigger.issue.assingee} = {trigger.issue.reporter}