We have a new documentation site. Please go here to see the latest.
Block workflow transition using regular expression
On this page
- 1 Prerequisites
- 2 Introduction
- 3 Step by step guide
- 3.1 Example 1 - block transition if checklist items with given text are not completed
- 3.2 Example 2 - block transition if mandatory checklist items are not completed
- 3.3 Example 3 - block transition if checklist items on given position are not completed
- 3.4 Example 4 - block transition if there are no checklist items at all
- 3.5 Example 5 - block transition if there are items with "open" status
- 3.6 Example 6 - block transition if no items are checked (optionally requiring non-empty checklist)
- 3.7 Looking for something else?
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.