We have a new documentation site. Please go here to see the latest.
Block workflow transition using regular expression
- Jack (Hunter) Jaroczynski
- Maciej Opala (Deactivated)
On this page
Prerequisites
"Save checklist data to Jira custom fields" option must be enabled in Issue Checklist Global Settings.
Introduction
This page describes how to block workflow transition if selected checklist items are not completed.
As a result selected checklist items must be completed to move the issue to another status (e.g. Done or Resolved).
At the same time, other checklist items can stay not completed and the transition will be still enabled.
If you want to enable transition only when all the items are completed then please follow the guide Block workflow transition if checklist is not complete.
The regular expression must match the value in the field to allow the transition. If the regular expression does not match the field value, the transition is blocked.
The regular expressions in this guide are provided as-is. Please adjust them to your needs on your own.
If you have custom checklist statuses corresponding to checked items you will need to explicitly include them; for example, if you have an additional status named "finished", you should replace "x|done|skipped" fragment with "x|done|skipped|finished".
Step by step guide
Example 1 - block transition if checklist items with given text are not completed
In this guide we will block "Done" transition (that moves issue to "Done" status) if "first item" is not completed.
Let's assume that our checklist contains two items:
- first item
- second item
as presented on the screenshot:
The textual representation of the Checklist is stored in "Checklist Text" custom field, which you can also see on the screenshot above.
Please follow the step-by-step instruction below to configure Jira to block selected transition:
- Navigate to "Project settings > Workflows" or "Jira settings > Issues > Workflows".
- Edit the selected workflow (click "pen" icon or "Edit" link)
- Select Diagram view (1) and next select the transition (2) that you want to block, e.g. Done. After that press Validators link (3):
- Press "Add Validator" link:
- Select "Regular Expression Check" and press "Add" button:
Select "Checklist Text" field in the dropdown, and paste following value in "Regular expression" field, next press "Add" button:
(?ms).*^\*\s+\[(x|done|skipped)\]\s+first item.*
Below is an example of a regular expression that checks for two items:(?ms).*^\*\s+\[(x|done|skipped)\]\s+first item.*^\*\s+\[(x|done|skipped)\]\s+second item.*
- Confirm that validator is available on the list and press "Publish Draft" link
- Confirm that validator (blocking issue transition) works fine:
- Open issue in a project that uses modified workflow
- Add checklist items ("first item" and "second item")
Press transition button and observe error message displayed by Jira if "first item" is unchecked
It is not possible to specify a custom error message for a blocked transition. The described solution relies on a built-in JIRA validator that comes with its own message.
The solution presented above is based on the checklist item text (please spot "first item" text in the regular expression). It means that for single item checklist items order is not important and the solution works well if items are reordered and "second item" is on the first position.
However, if your regular expression checks for multiple items then they have to occur in the same order as in checklist.
Example 2 - block transition if mandatory checklist items are not completed
Instead of relying on the regular expression, you can use a dedicated validator for that.
Example 3 - block transition if checklist items on given position are not completed
To block transition if the fourth item on the list is not completed, create a regular expression validator for Checklist Text custom field with the following expression:
\A(\*.*\r?\n){3}\*\s+\[(x|done|skipped)]\s+(.*\r?\n?)*\Z
To block transition if Nth item is not completed change "3" in the expression above to N - 1. It cannot be used though for the very first item. The transition will also fail unless the checklist has at least N items.
To block the transition when more than one item on a given position needs to be completed add a separate validator for each position.
Please do remember that correctly formatted content of the Checklist Text custom field contains names of the checklists, even if there is only one, default checklist. For more details see Checklist Text custom field documentation.
Example 4 - block transition if there are no checklist items at all
For that case, you can also use a dedicated validator.
Example 5 - block transition if there are items with "open" status
To block transition if there are checklist items in "open" status, please follow the steps from the Example 1 above, but use use the following regular expression for the Checklist Text field:
(?s)^(?!.*\*\s+\[open\]).*$
As a result, the transition will require that all the checklist items are in a status different from "open". Transition will be also possible in case issue has no checklist at all.
Example 6 - block transition if no items are checked (optionally requiring non-empty checklist)
One of the following regular expressions can be used to make the transition requre at least one checked item and optionally require that checklist has at least one item. Two of them work with item statuses disabled, the other two - with statuses enabled. If you use custom statuses for checked items you will need to add them to the expression.
(?s)^(?!.*\*\s+\[.*?\])|(?=.*\*\s+\[x\]).*$
(?s)^(?=.*\*\s+\[x\]).*$
(?s)^(?!.*\*\s+\[.*?\])|(?=.*\*\s+\[done|skipped\]).*$
(?s)^(?=.*\*\s+\[done|skipped\]).*$
Looking for something else?
Let us know if the solutions above don't satisfy your needs - we'll try to come up with a solution.
Tip
You might want to test your regular expression in one of the available online tools/testers, e.g. this one (use Java 8 flavor).