Page History
| Panel | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
there was Jira Workflow Toolbox (JWT) and now, almost ten years after the initial public release, used by more than 4000 active customers and 140 versions later, comes its natural descendant, Automation Toolbox for Jira . The team at Decadis took a long time planning the development of Automation Toolbox for Jira as this new app had some very major prerequisites to fulfill - namely providing as much known and proven JWT functionality as possible in a non-workflow environment. It has been a daunting task, but, we hope for you as a user, worthwhile. Even though you need no prior knowledge of JWT to use Automation Toolbox for Jira, you can depend on the functionality designed and developed with many years of Jira app experience. Where JWT has used the slogan "Turn your ideas into workflows" for many years, ATJ will hopefully help you to "Turn your ideas into automatisms" wherever and whenever these are appropriate. The possible use-cases are endless. To get started, please continue to the ATJ Fundamentals, a summary of the primary functions and the terminology used by ATJ. |
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 where the condition will return true if the issues Due date is greater than the current date. 
| Info |
|---|
The available Selectors, Conditions and Actions depend on the selected Trigger. |
There are five types of expressions that can be parsed:
- Mathematical and Time: returns a number. When it represents a Date or Time, it returns the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMT
Examples:-
(1 * 2) / 3 -
{...duedate}+ 2 * {HOUR} -
round(({...duedate} - {...currentDateTime}) / {HOUR}): calculate the number of hours from Current date and time to Due Date.
-
- Text-String: returns a string. This kind of expressions is used in advanced mode of the Action Update Field .
Examples:-
"Hello" + " " + "world" + ".": concatenating 4 string literals. -
trim(%{...summary}): removing leading and trailing blanks from Summary. -
%{...description} + "\nLAST USER: " + toUpperCase(%{...currentUser}): adding to Description a new line with string "LAST USER: " and the name of current user in upper case.
-
true or false . Examples:
%{...cf10005} = "Yes" : compares the value stored in a field with literal string "Yes".datePart({...duedate}, LOCAL) > datePart({...currentDateTime}, LOCAL) : returns true only if Due Date (field code {...duedate}) is later than Current date (field code {...currentDateTime}) in server's local timezone.%{...cf10020} != null AND %{cf10021} = null : returns true only if {...cf10020} field is initialized and field {...cf10021} is not initialized.timePart({...currentDateTime}, LOCAL) >= 8:00 AND timePart({...currentDateTime}, LOCAL) <= 17:30 : Current time (field code {...currentDateTime}) is between 8:00 AM and 5:30 PM in server's local timezone. Issue List: is used for selecting issues (is much like JQL) within Automation Toolbox for Jira expressions, and returns a list of issues.
Examples:
subtasks() : returns the list of sub-tasks of current issue.linkedIssues("is blocked by, is caused by") : returns the list of issues linked to current one through issue link types "is blocked by" and "is caused by".filterByIssueType(linkedIssues(), "Bug, Incident") : returns the list of linked issues with issue type "Bug" or "Incident".filterByPredicate(siblingSubtasks(), %{...resolution} != null) : returns the list of sibling sub-tasks (i.e., sub-tasks of same parent as current sub-task) which are not resolved. - String List: expression that returns a list of strings.
Examples:-
["red", "blue", "green"]: literal definition of a string list with the names of 3 colors. -
fieldValue(%{...summary}, subtasks()): returns the list of summaries of sub-tasks of current issue. -
toStringList(%{...components}): returns a list with the names of the components in current issue.
-
The parser used in the app for mathematical calculation, time-formulas and boolean expressions uses the following data types:
true or false , as well as some functions.This type represents numeric values, and is also used to store Date, Time and Date-Time (
) values. When storing any temporal value, the number represents the milliseconds elapsed since January 1, 1970, 00:00:00 GMT. Status title date_time
Number or Date-Time fields can be referenced as numbers using the following notation: {...somefield}.
1, 1.1, -1.1, .1, -.1 This type represents any kind of text or character string including all kinds of select and multi-select fields
. 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: %{...anyfield}, and %{...anyfield.i} for 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).Status title multi
"Hello world" | Status | ||||||
|---|---|---|---|---|---|---|
|
[1, 2, 3]. fieldValue(), append(), union(), except(), intersect() and distinct(),
[1, 2, 3]
Status subtle true colour Yellow title String []
["string_A", "string_B", "string_C"]. fieldValue(), append(), union(), except(), intersect() and distinct(),
["string_A", "string_B", "string_C"]
| Status | ||||
|---|---|---|---|---|
|
It's returned by issue selection or filtering functions like subtasks(), linkedIssues(), filterByIssueType(), distinct(), etc.
subtasks(), linkedIssues(), transitionLinkedIssues(), filterByFieldValue(), filterByStatus(), filterByIssueType(), filterByResolution(), filterByProject(), append(), union(), except(), intersect() and distinct( Casting values to another type
There are two functions available for transforming types from Text-String to Number and viceversa, and also from other types to Text-String.
Status title date_time
Example: toString(3.141592) returns "3.141592" .
Example: toString(3.141592, 2) returns "3.14" .
Status subtle true colour Blue title number []
Example: toString([1, 2, 3, 4.0]) returns "1, 2, 3, 4" .
Status subtle true colour Blue title number []
Example: toString([1.123, 2.452, 3.64612], 2) returns the following string: "1.12, 2.45, 3.65" .
Status subtle true colour Blue title number []
Example: toString([1.123, 2.452, 3.64612], 2, " : ") returns the following string: "1.12 : 2.45 : 3.65" .
Status subtle true colour Yellow title String []
Example: toString(["Hello", " ", "world", "!"]) returns "Hello, , world, !" .
Status subtle true colour Yellow title String []
Example: toString(["blue", "red", "green"], "; ") returns "blue; red; green" .
Status subtle true title Issue []
Example: toString(subtasks()) returns "CRM-5, CRM-6" , being CRM-5 and CRM-6 the keys of current issue's sub-tasks.
toString(issue list l, string separator)
Status subtle true title Issue []
Example: toString(subtasks(), " ") returns "CRM-5 CRM-6", being CRM-5 and CRM-6 the keys of current issue's subtasks.
null is returned.Example: toNumber("3.14") returns 3.14 .
toInteger(string s, string radix)
Example: toInteger("ff", 16) returns 255 .
Returns a
with tokens in argument s separated by characters in argument separators. Leading and trailing spaces around each token are automatically removed.Status subtle true colour Yellow title String []
Example: toStringList("red, orange, yellow; green; blue; purple", ",;") returns the following string list: ["red", "orange", "yellow", "green", "blue", "purple"] .
field code for a
-value field in format %{...somefield}. Multi-valued fields are Multi Select, Checkboxes, Components, Versions, Multi User Picker, Multi Group Picker, Issue Pickers, Attachments and Labels.Status title multi
Returns a
representing each of the values selected in the field.Status subtle true colour Yellow title String []
Example: toStringList(%{...components}) returns a list of strings with each of the components selected in current issue.
This function expects in argument s a string containing numbers in decimal representation separated by characters in argument separators, and returns a
.Status subtle true colour Blue title number []
Example: toNumberList("1, 3, 5; 7; 11; 13", ",;") returns the following number list: [1, 3, 5, 7, 11, 13] .
Returns an
with all issues with keys in argument issue_keys. Argument issue_keys is a string containing a comma separated list of issue keys.Status subtle true title Issue []
Example: issueKeysToIssueList("CRM-12, HT-254") returns an issue list with issues with keys CRM-12 and HT-254.
Automatic casting from Number to Text-String: Whenever you write a numeric term at the right-hand side of concat operator + or a comparison operator like = , and the left-hand side is occupied by a text-string term, the parser will automatically transform the right-hand side term into a string
-
+(string concat):"His age is " + 30is equivalent to"His age is " + toString(30). -
=(any comparison operator):"30" = 30is equivalent to"30" = toString(30).
Operators
The following comparison operators are available for types Number, Text-String, Number List, String List and Issue List. Operators = and != are also available for type Boolean.:
true)= 1 = 1 "HELLO" = toUpperCase("Hello") %{...description} = {...timeoriginalestimate} , auto-casting numeric field {...timeoriginalestimate} to Text-String. %{...timeoriginalestimate} = toString({...timeoriginalestimate}) , explicit casting of numeric field {...timeoriginalestimate} to Text-String. true = true %{...cf10001} = null , for checking whether field with code %{...cf10001} is not initialized. [1, 2, 3] = [1, 2, 3] , when used with lists elements existence and its order are evaluated. ["blue", "red", "green"] = ["blue", "red", "green"] != 0 != 1 "HELLO" != "Hello" %{...description} != "Hello" true != false {...cf10010} != null , for checking whether the numeric field with code {...cf10010} is initialized. [1, 2, 3] != [1, 3, 2] , when used with lists elements existence and its order are evaluated. ["blue", "red", "green"] != ["blue", "green", "red"] < 1 < 2 "abc" < "bbc" "abc" < "abcd" > 2 > 1 "bbc" > "abc" "abcd" > "abc" <= >= ~ "Hello world!" ~ "world" , checks whether a string contains a substring. %{...componentLeads} ~ %{...currentUser} , checks whether "Component leaders" contains "Current user". linkedIssues() ~ subtasks() , checks whether all sub-tasks are also linked to current issue. [1, 2, 3, 2, 2, 4] ~ [2, 1, 2] , when used with lists cardinalities must match. ["blue", "red", "green", "red", "white", "red"] ~ ["red", "green", "red"] (["green", "red"] ~ ["red", "green", "red"]) = false !~ "world" !~ "Hello world!" %{...fixVersions} !~ %{...versions} , checks whether "Fix version/s" doesn't contain all versions in "Affects version/s". fieldValue(%{...reporter}, linkedIssues()) !~ fieldValue(%{...reporter}, subtasks()) , checks whether linked issues reporters don't include all sub-tasks reporters. [1, 2, 3, 2, 2, 4] !~ [2, 1, 1, 4] , when used with lists cardinalities must match. ["blue", "red", "green", "red", "red"] !~ ["red", "green", "green", "red"] in "world" in "Hello world!" , to check whether a substring is contained in a string. %{...currentUser} in %{...componentLeads} , checks whether "Current user" is contained in "Component leaders". subtasks() in linkedIssues() , checks whether all sub-tasks are also linked to current issue. [1, 1, 2] in [2, 1, 1, 1, 4] , cardinality must match. ["blue", "red", "red"] in ["red", "green", "blue", "red", "red"] , cardinality must match. 2 in [1, 2, 3] "blue" in ["red, "blue", "white"] not in "Hello world!" not in "world" %{...versions} not in %{...fixVersions} , checks whether not all versions in "Affects version/s" are contained in "Fix version/s". fieldValue(%{...reporter}, subtasks()) not in fieldValue(%{...reporter}, linkedIssues()) , checks whether not all sub-tasks reporters are included in linked issues reporters. [1, 1, 2, 2] not in [2, 1, 1, 1, 4] , cardinality must match. ["blue", "red", "red", "blue"] not in ["red", "blue", "red", "red"] , cardinality must match. 5 not in [1, 2, 3, 3, 4] "orange" not in ["blue", "red", "white"] any in %{...versions} any in %{...fixVersions} , checks whether any version in "Affects version/s" is contained in "Fix version/s". fieldValue(%{...reporter}, subtasks()) any in fieldValue(%{...reporter}, linkedIssues()) , checks whether any sub-task's reporter is present among linked issues reporters. [1, 3] any in [3, 4, 5] ["blue", "white"] any in ["black", "white", "green"] none in %{...versions} none in %{...fixVersions} , checks whether there isn't a single version "Affects version/s" in "Fix version/s". fieldValue(%{...reporter}, subtasks()) none in fieldValue(%{...reporter}, linkedIssues()) , checks whether there isn't a single sub-task reporter among linked issues reporters. [1, 2] none in [3, 4, 5] ["blue", "red"] none in ["black", "white", "green"] Case Ignoring Operators
The following comparison operators are applicable to String and String List types. This operators have the peculiarity that ignores the case of the characters.
true)=~ "HELLO" =~ "Hello" "up" =~ "UP" ["blue", "red", "green"] =~ ["Blue", "RED", "Green"] !=~ " HELLO" !=~ "Hello" "up" !=~ "down" ("up" !=~ "UP") = false ["blue", "red"] !=~ ["Blue", "green"] ["blue", "red"] !=~ ["Red", "BLUE"] (["blue", "red", "green"] !=~ ["Blue", "RED", "Green"]) = false ~~ "Hello World!" ~~ "world" , checks whether a string contains a substring. "A small step for a man" ~~ "STEP" , checks whether a string contains a substring. ["one", "two", "three"] ~~ ["TWO", "One"] , checks whether a string list contains all the elements of another string list.!~~ "Hello World!" !~~ "bye" , checks whether a string doesn't contain a substring. "A small step for a man" !~~ "big" , checks whether a string doesn't contain a substring. ["one", "two", "three"] !~~ ["Four"] , checks whether a string list doesn't contain one element of another string list. (["one", "two", "three"] !~~ ["TWO"]) = false in~ "world" in~ "Hello World!" , checks whether a substring is contained in another string. "STEP" in~ "A small step for a man" , checks whether a substring is contained in another string. ["TWO", "One"] in~ ["one", "two", "three"] , checks whether all the elements of a string list are contained in another string list.not in~ "bye" not in~ "Hello World!" , checks whether a substring is not contained in another string. "big" not in~ "A small step for a man" , checks whether a substring is not contained in another string. ["Four"] not in~ ["one", "two", "three"] , checks whether any of the elements of a string list are not contained in another string list. (["TWO"] not in~ ["one", "two", "three"]) = false any in~ ["blue", "violet"] any in~ ["Blue", "Red", "Green"] ["Five", "One"] any in~ ["FOUR", "FIVE", "SIX"] none in~ ["Orange"] any in~ ["red", "blue", "green"] (["orange"] any in~ ["Red", "Orange"]) = false Applicable Data Types
= != < > <= >= ~ !~ in not in any in none in =~ !=~ ~~ !~~ in~ not in~ any in~ none in~ Notice that:
- Operators
~,!~,inandnot incan be used for checking a single element (number or string) against a number list or a string list. Example:1 in [1, 2, 3]or["blue", "red"] ~ "blue". - Operators
~,!~,inandnot inwhen used with string are useful to look for substrings in another string. Example:"I love coding" ~ "love"but"I don't like Mondays" !~ "Fridays", or"love" in "I love coding"but"Fridays" not in "I don't like Mondays". - Operators
~,!~,inandnot inrespect cardinality, i.e., container list must have at least the same number of elements as contained list. Example:[1, 1] in [1, 1, 1]but[1, 1] not in [1, 2, 3]. - Operators
=and!=, when used for comparing lists, require to have the same elements, with the same cardinality and the same order. Example:[1, 2, 3] = [1, 2, 3]but[4, 5, 6] != [4, 6, 5]. - Operators
<,>,<=and>=work according to lexicographical order when comparing strings.
| Info |
|---|
A reference of all data types can be found here. |
- Operators
~,!~,inandnot in - Operators
any inandnone in - Operators
=~,!=~,~~,!~~,in~,not in~,any in~andnone in~
expressions
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
Numbers, dates and times
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
Strings
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
Issue lists
Excerpt Include Issue lists Issue lists nopanel true
Number lists
Excerpt Include Number lists Number lists nopanel true
String lists
Excerpt Include String lists String lists nopanel true
List operators
Excerpt Include List operators List operators nopanel true
Selectable fields
Excerpt Include Selectable fields Selectable fields List operators List operators nopanel true
Users, groups and roles
Excerpt Include Users, groups and roles Users, groups and roles nopanel true
Versions
Excerpt Include Versions Versions nopanel true
Historical field values
Excerpt Include Historical field values Historical field values nopanel true
Miscellaneous
null is returned if project property doesn't exist. Example:
projectProperty("maxNumberOfReopenings") returns "3" , provided there is a string {maxNumberOfReopenings=3} in the description of current issue's project.null is returned if project property doesn't exist. Example:
projectProperty("maxNumberOfReopenings", "CRM") returns "3" , provided there is a string {maxNumberOfReopenings=3} in the description of project with key CRM.Returns true only if there is a project property with name property_name in current issue's project, i.e., if project's description contains a string like {property_name=value}.
Example: projectPropertyExists("maxNumberOfReopenings") returns true only if there is a string like {maxNumberOfReopenings=x} in the description of current issue's project.
Returns true only if there is a project property with name property_name in project with key project_key.
Example: projectPropertyExists("maxNumberOfReopenings", "CRM") returns true only if there is a string like {maxNumberOfReopenings=x} in the description of project with key CRM.
Returns a string list with all the comments in issues with keys in issue_keys, in order of appearance in issue_keys, and by creation date in ascension order. Argument issue_keys is a comma separated list of issue keys.
Example: allComments(%{...parentIssuekey}) returns parent issue's comments.
Example:
allComments(subtasks()) returns all the comments in all the sub-tasks of current issue.Excerpt Include Miscellaneous Miscellaneous nopanel true
Functions to temporarily store and retrieve values
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
"") is returned."") is returned."") is returned.Example:
allComments(%{...parentIssuekey}) returns a string list with the user names of comment authors of parent issue.Example:
allCommenters(linkedIssues("is blocked by")) returns a list with all the commenters and comment updaters for linked issues blocking current issue.Returns a string list with the names of the users who transitioned current issue from origin_status to destination_status, order ascending by time. An empty string as argument is interpreted as any status.
Example: last(usersWhoTransitioned("Open", "In Progress")) returns the name of the user who executed transition "Start Progress" more recently.
Example:
count(usersWhoTransitioned("Open", "In Progress", %{...parentIssuekey})) returns the number of times transition "Start Progress" has been executed in parent issue.Example:
last(timesOfTransition("", "Resolved")) returns the most recent time when the issue was resolved.Example:
first(usersWhoTransitioned("Closed", "", %{...parentIssuekey})) returns the first time when parent issue was reopened.Example:
componentLeader(%{...components}) returns a comma separated list with the user names of the leaders of current issue's components.Example:
componentLeader("Web Portal", "CRM") returns the user name of the leader of the component with name Web Portal in project with key CRM.Example:
issueIDFromKey("CRM-1") returns "10001" .Example:
issueIDFromKey("10001") returns "CRM-1" .Returns a string list with all the project keys in the JIRA instance.
projectName(string project_key) : string
| Div | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||
|
