Using the Workflow Enhancer

Validators and Conditions

To enter a validator or a condition provided by Workflow Enhancer for Jira, edit your workflow and in any transition add a new "Universal Validator" or "Universal Condition". You will be prompted with entering a boolean expression as explained below. In case of the universal validator, you will be prompted to enter a message as well.

Post Functions

You have the possibility of executing any post function depending on whether a boolean expression (see the rest of this documentation) evaluates to true or false, respectively. When adding a "Universal Post Function", you will not only be prompted for a boolean expression, but also for another post function to be executed for any values the post function might take.

Note that some of the provided post functions in Jira have unintuitive functionality:

Create a comment: If comment was added in the transition screen, it will be added again.
Update Issue Status: Will update the issue status after transition, although it was already changed.
Create Issue: Recreates the issue, e.g., previously there is an issue "TEST-4 - A task", but after the post function transition executes it becomes "TEST-5 - A task"

In the future we might decide to hide these post functions.

If you add a post function to the create transition, it must happen before the “Creates the issue originally.”

Fields

Name	Type	Explanation	Example	Annotation
Reporter, Assignee	String	User field containing a username, e.g., {Reporter} represents the username of the issue's Reporter field.	{Reporter} = "admin"	Anonymous is represented by ""
Environment, Description, Summary	String	Text field, e.g., {Summary} contains the text entered in the issue's Summary field.	{Summary} = "Summary"
Due Date, Created, Updated	Date	Date field, e.g., {Due Date} contains the date entered in the issue's Due Date field.	{Due Date} = 24.12.2012
Original Estimate, Remaining Estimate, Time Spent	Timespan	Timespan field, e.g., {Original Estimate} contains the timespan entered in the issue's Original Estimate field.	{Original Estimate} = 4w 5d 6h	If nothing is entered in the field, Workflow Enhancer for Jira returns 0min (i.e., {...} = 0min)
Σ Original Estimate, Σ Remaining Estimate, Σ Time Spent	Timespan	Time span field, e.g., {Σ Original Estimate} contains the sum of the Original Estimates of the issue's subtasks.	{Σ Original Estimate} = 1w 4d 3h	if nothing is entered in the field, Workflow Enhancer for Jira returns 0min (i.e., {...} = 0min)
Project	String	{Project} contains the issue's Project name.	{Project} = "Rocket"
Priority	String	{Priority} contains the text of the issue’s Priority field.	{Priority} = "Major"
Status	String		{Status} = "In Progress"
Resolution	String		{Resolution} = "Resolved"
Issue Type	String		{Issue Type} = "Bug"
Key	String	{Key} contains the issue’s key.	{Key} = "ROCKET-1"
Issue Links	String	{Linked Issues} <=> "Passive: LinkType % IssueKey $ ... $ LinkType % IssueKey Aktive: LinkType % IssueKey $ ...$ LinkType % IssueKey"	Linked exactly with ROCKET-1 as a Blocker and ROCKET-42 as a Cloner: `{Linked Issues} = "Passive: Blocks % ROCKET-1 Aktive: Cloners % ROCKET-42"` Linked exactly with ROCKET-42 as Cloner `{Linked Issues} = " Aktive: Cloners % ROCKET-42"` Has to have at least one active Link of type Relation: `{Linked Issues}=/ Aktive: .Relation./`	Jira’s default link types are Blocks, Cloners and Duplicate. Note the space before “Aktive“ and the spelling of “Aktive“. Set the log level to DEBUG and check in the logs as this syntax is not really easy to handle.
Labels	String	Returns the array of labels as String in alphabetical order; e.g., [label1, label2, label3]	`{labels} = "[labelX]"` for a single label or `{labels} = "[]"` for no label. `{labels} = /.labelX./` if you want to check if a version called "labelX” is set and you do not care about other versions.	Use regular expressions to check for one label among several.
Fix Version/s, Affects Version/s	String	Returns the array of versions as String in alphabetical order; e.g., [version1, version2, version3]	`{Fix Version/s} = "[versionX]"` for a single version or `{Fix Version/s} = "[]"` for no version. `{Fix Version/s} = /.versionX./` if you want to check if a version called "versionX” is set and you do not care about other versions.	Use regular expressions to check for one version among several.
Components	String	Returns the Array of components as String in alphabetical order; e.g., [component1, component2, component3]	`{Components} = "[componentX]"` for a single component or`{Components} = "[]"` for no component. `{Components} = /.componentX./` if you want to check if a component called "componentX” is set and you do not care about other components.	Use regular expressions to check for one component among several.
Transition Comment	String	Returns the comment added in the transition as a String.		Only useful for post functions and validators if a screen is shown during the transition.

Jira fields (written as `{field_id}`) may themselves contain a special value. Therefore if a field contains a value such as `1h 30min`, it will automatically be parsed as a timespan. This also allows for a chain of field identifiers (by putting the identifier of another field in a field). An application might be that the first element of the chain is set as a post-function to dynamically change the behavior of the condition/validator depending on the steps in the workflow we have visited.

To make the field value non-evaluating (i.e not evaluating chained field identifiers within the field), use double brackets (e.g. {{description}})

Please compare Jira fields always with English field values, e.g., {Resolution} = "Resolved".

Fields of type String only allow String comparisons. So, especially the order operations <, <=, >=, and > often do not make sense, e.g., in the case of priority {Priority} > "A String which begins with the letter a" always evaluates to "True".

You can use both, field names in your local language as well as english lower-case names, e.g., in German {resolution} and {Lösung} both refer to the resolution while {Resolution} tries to evaluate a custom field.

Custom Fields

Use field id to include custom fields in an expression: {customfield_123}

While using custom field names directly works for expression evaluation, it does not work for cloud migration.

Type	Explanation	Annotation
Date Picker	{Date Picker} represents the picked date as a date value.	e.g., `{Date Picker} = 25.09.2012 00:00` if you picked 25/Sep/2012 in the issue's Date Picker field or {Date Picker} = "" if you want to check that the date picker is empty
Version Picker	{Single Version Picker} represents all picked versions of the issue as a comma and space separated String.
Single Version Picker	{Version Picker} represents the picked version as a String.
Project Picker	{Project Picker} represents the picked project name as a String.
User Picker	{User Picker} represents the picked username as a String.
Multi User Picker	{Multi User Picker} represents all picked usernames in a comma and space separated String.	e.g., `{Multi User Picker} = "username1, username2"` if you picked user1 and user2 in the issue's Multi User Picker field.
Group Picker	{Group Picker} represents the picked group name as a String.
Multi Group Picker	{Multi Group Picker} represents all picked group names in a comma and space separated String.	e.g., `{Multi Group Picker} = "jira-developers, jira-users"` if you picked these groups in the issue's Multi Group Picker field
Number Field	{Number Field} represents the entered number as a Float value.	e.g., `{Number Field } = "3.14"` if you entered 3.14 in the issue's Number Field field
Free Text Field	{Free Text Field} represents the entered text as a String.	e.g., `{Free Text Field} = "all work and no play makes Jack a dull boy"` if you entered all work and no play makes Jack a dull boy in the issue's Free Text field
Text Field	cf. Free Text Field
Label	{Labels} represents all labels, which are set for this issue, as a String.	e.g., `{Label} = "label1, label2, label3"` if you set these labels to the issue. Note that Jira might sort the labels so that "label1, label2" = "label2, label1"
Date Time	{Date Time} represents the picked point in time as a Date value.	e.g., `{Date Time} = 24.12.2012 15:45` if you picked this date time in the issue's Date Time field.
URL Field	{URL Field} represents the entered URL as a String.	e.g., `{URL Field} = "http://en.wikipedia.org/wiki/Uniform_Resource_Locator"`
Import Id	NOT SUPPORTED
Read only Text Field	NOT SUPPORTED
Cascading Select	{Cascading Select} represents the selected options as a String in the same format as Atlassian's `.toString()` method for Cascading Select fields: `null=PARENT, 1=CHILD` `null=PARENT` if no child value is selected `""` if no value is selected	e.g., `{Cascading Select} = /null=., 1=./` to ensure both values are set
Bug Import ID	NOT SUPPORTED
Multi Select	{Multi Select} represents the selected options as a comma and space separated String.
Radio Buttons	{Radio Button Field} represents the selected option as a String.
(Multi) Checkbox	{Checkbox} represents the selected options as a comma and space separated String.
Select List	{Select List} represents the selected option as a String.
Hidden Job Switch	NOT SUPPORTED

Boolean evaluations (equations and comparisons) are logged. If you are not sure, to which value Workflow Enhancer for Jira evaluates your custom field, just do the following:

Administration → Logging & Profiling
Configure a new logger: com.tng.jira.workflowenhancer.evaluator.types.AbstractGenericValue
Set the logging level to DEBUG (or below).
Now, you can see every evaluation and its result in the logs.

Note that Workflow Enhancer for Jira can change the left and right side of the equation/comparison.

Macros

Macro	Type	Description	Example
[user]	String	The username of the current user.
[groups]	String	A comma-separated list of the groups the user belongs to.
[roles]	String	A comma-separated list of the project roles the user belongs to.	`[roles]=/.role_name_1./`
[now]	Date	The current date and time.
[subtasks#field]	String	A comma-separated list of the values in the subtasks.	`[subtasks#Summary]=/.Test./`: Checks if any subtask has a summary containing the text "Test" `[subtasks#Status]=/\0133(Done(, Done)*)?\0135/`: Checks if all subtasks are in the status "Done". \0133 and \0135 are encoded "[" and "]" as you cannot use them directly in a regular expression.

Values

String

	Example
any String has to be enclosed by " (quotation marks)	`"String"`

Regular Expression

	Example
any regular expression has to be enclosed by / (forward slashes)	`/ab/`
* matches the preceding element zero or more times	`/a*/` = {ε,a,aa,aaa,aaaa,...}
+ matches the preceding element one or more times	`/a+/` = {a,aa, aaa,aaaa,...}
? matches the preceding element zero or one time	`/a?/` = {ε,a}
( ) defines subexpression	`/(ab)+/` = {ab,abab,abab,ababab,...}
{n} matches the precending element exactly n times	`/a{3}/` = {aaab}
{min, max} matches the preceding element at least min and at most max times	`/a{2,4}/` = {aa,aaa,aaaa} `/a{1,}/` = /a+/ = {a,aa,aaa,...} `/a{ ,5}/` = {ε,a,aa,aaa,aaaa,aaaaa}

In the examples above ε always stands for the empty word. For example, in the case of /a?/ there can be either one "a" or no "a".

Field interpolation in Regular Expression

For your field to be evaluated in regex, you must use the {field_id} notation, as expressions of the type {field_name} will not be evaluated. For custom fields, this will be of the form {customfield_123}, for system fields, it is generally the name in lowercase with spaces and special characters removed, as per the table below. Note that, when inserting a field using the UI, it will show the {field_name} by default, and this must be converted to {field_id}.

	Example
A field in a regular expression is replaced by its value (as string)	`/{description}/` = `abc` (when the value of description is abc)
The value of the field is evaluated	`/{description}/` = `Max` (when `{description} = "{assignee}"` and `{assignee} = "Max"`
Use double curry brackets (`{{`) to skip the evaluation of a field value	`/{{description}}/` = `{assignee}` (when `{description} = "{assignee}"` and `{assignee} = "Max"`)
Custom fields are supported	`/{customfield_123}/`
Use `\` to escape the interpolation (only works in regex, not in the field’s value)	`/\{description\}/` becomes regex `/\{description\}/`, matches the string `{description}`
Use `\Q` and `\E` to escape a sequence	`/\Q{description}.\E/` becomes the same regex, and matches the string `{description}.`

Both left and right curry braces need to be escaped. Regex like /\{abc}/ will not work.

System Field Name in English	Field ID
Description	description
Summary	summary
Issue Type	issuetype
Priority	priority
Resolution	resolution
Version/s	versions
Fix Version/s	fixVersions
Component/s	components
Labels	labels
Environment	environment
Linked Issues	issuelinks
Attachment	attachment
Assignee	assignee
Reporter	reporter
Due Date	duedate
Time Tracking	timetracking
Security Level	security

Date

	Example
Date pattern: dd.mm.yyyy hh:mm	`24.12.2012 15:30`
Time is optional	`24.12.2012`

The maximum date value is 31.12.2099 23:59.

Timespan

	Example
Labor Timespan pattern: n₁w n₂d n₃h n₄min , where n₁, n₂, n₃, n₄ are non negative integers	`12w 13d 5h 3min` = 12 labor weeks 13 labor days 5 hours and 3 minutes
Real Timespan pattern: n₁W n₂D n₃H n₄MIN , where n₁, n₂, n₃, n₄ are non negative integers	`12W 13D 5H 3 MIN` = 12 weeks 13 days 5 hours and 3vminutes
If a component is 0, it can be omitted	`0w 5d 3h 0min` = 5d 3h
It is not possible to change the order	Wrong: `5d 8w` Right: 8`w 5d`

Workflow Enhancer for Jira works with the time tracker of your Jira such that a timespan of Jira is automatically a labor timespan. This also means that a date and timespan field cannot be added.
If the time tracker is disabled, we have 1 day = 8 hours and 1 week = 5 days.

So, if your Jira time tracker settings are 1 labour day = 24 hours and 1 labor week = 7 labor days, labor timespan and real timespans are the same.

Float

	Example
Pattern: d+(.d)? or d(.d+)? where d is an integer	`3.14`

The Workflow Enhancer for Jira float data type works with negative values, but the parser does not support unary operations.

Operators

Boolean Operators

Description	Operator
AND	& (alternatively && or AND)
OR	\| (alternatively \|\| or OR)
NOT	!
Parentheses	( )

Order Operators

Description	Operator
Equal	= (alternatively ==)
Not equal	!=
Greater	>
Greater or equal	>=
Less	<
Less or equal	<=

Arithmetic Operators

Description	Operator
Plus	+
Minus	-

Order Operations

The following matrix shows which values allow order operations and how they are defined.

	String	Float	Date	Real Timespan	Labor Timespan	Regular Expression
String	s	default	default	default	default	r
Float	default	f	default	default	default	default
Date	default	default	d	default	default	default
Real Timespan	default	default	default	t	t	default
Labor Timespan	default	default	default	t	t	default
Regular Expression	r	default	default	default	default	default

Order operations are possible if the field at the crossing point is not empty. The type of the operation is explained in the legend.

Type	Explanation	Example
s	Lexicographical comparison based on the Unicode value of each character in the Strings.	`"zoo" >= "a much longer String but with an a at the beginning"`, `"2 test Strings" < "A test String without a number at the beginning"`
f	Standard comparison of numbers.	`4.5 < 42`, `7.77 >= 2.2222`
d	The time is considered if and only if both values match the pattern dd.mm.yyyy hh:mm.	`24.12.2012 15:30 = 24.12.2012`, `24.12.2012 15:30 < 24.12.2012 16:00`
t	Number comparison of the timespan values converted to minutes.	`1w > 1min`, `1h <= 61min`, `1d 1h = 1d 1h`
r	Equal if and only if the String matches the regular expression.	`"Bar"= /Ba[a,r]/`, `/Ba[a,r]/ > "A"`
default	Lexicographical comparison after both values have been converted to String.	`10.10.2000 = "10.10.2000"`, `10.10.2000 < "a String"` `42 = "42.0"`, `"0 A String with a zero at the beginning" < 42` `"1w 0d 0h 0min" = 1w`, `1w >= "1w 0d 0h 0min"`

Arithmetic Operations

Addition

The following matrix shows between which values additions are possible and how they are defined.

	String	Float	Date	Real Timespan	Labor Timespan
String	s
Float		f
Date				d
Real Timespan			d	t	t
Labor Timespan				t	t
Regular Expression

Additions are possible if the field at the crossing point is not empty.

Type	Explanation	Example
s	String concatenation.	`"An" + "na" = "Anna"`
f	Standard addition of numbers.	`1.5 + 3 = 4.5`
t	Standard addition of timespan values based on minutes. If the timespan values do not have the same type (i.e., not both real or both labor), the result has the type of the first operand.	`1w 2d 3h + 2w 2d 2h = 3w 4d 5h` `1D + 1h = 1D 1H`
d	The timespan value is added to the date. If the date has no entered time, hours and minutes do not matter.	`(12.10.2016 + 14H) + 12H = 12.10.2016`, `12.10.2016 + 1W 3D = 22.10.2016`

Subtraction

The following matrix shows between which values subtractions are possible and how they are defined.

	Float	Date	Real Timespan	Labour Timespan
String
Float	f
Date			d
Real Timespan		d	t	t
Labor Timespan			t	t
Regular Expression

Subtractions are possible if the field at the crossing point is not empty.

Type	Explanation	Example
f	Standard subtraction of numbers.	`4.5 - 3 = 1.5`
t	The subtraction of two timespans returns the absolute difference based on minutes. If the the timespan values do not have the same type (i.e., not both real or both labor), the result has the type of the first operand.	`8w 1d 3h - 8w 2d 4h 9min = 1d 1h 9min` `2h - 1H = 1h`
d	The timespan value is subtracted from the date. If the date has no entered time, hours and minutes do not matter.	`(29.05.2015 - 12H 5MIN) - 12H 5MIN = 29.05.2015`, `29.11.2019 - 6D = 23.11.2019`

The subtraction of Date values is not supported. Use, e.g., {Date A} < {Date B} + 1W instead of comparing the difference of the dates to a week.