Jira, Regex & Checklists

Combining checklists with automation and workflow behaviors opens up a world of possibilities for automating and streamlining processes. You can:

• Automatically close an issue when a checklist is completed
• Replace checklist items when an issue transitions to a new status
• Reset a checklist daily
• Clear a checklist when an issue is transitioned
• Mark all checklist items complete when an issue is transitioned
• Validate that all checklist items are complete before an issue can be transitioned

But what if you want to perform operations on / validate for a specific checklist item, rather than the checklist as a whole?

This is where Regex comes into the picture. Using Regex allows you to match for exact text, or a defined range in any string. You can use Regex to check for the specific text of a checklist item, or a checklist custom status.  This article will provide examples of how you can use regular expressions with checklists in Jira.

What is Regex?

Regex, also known as Regular Expressions or Regexp, is a set of characters that can be used to define a search pattern in text. These patterns can be used to find text in a string, to validate input, etc. For example, given a list of file names, you could use Regex to identify only those that have a “.pdf” extension. Or you could validate that a date or a phone number in a text field is formatted correctly.

Regex is a powerful tool. However, it is not easily readable or particularly intuitive. Therefore it’s good to have a few resources available when you’re learning Regex:

• RegexLearn includes a detailed tutorial, a cheat sheet, and a playground where you can practice/test your regular expressions
• QuickRef.Me has a nicely formatted Regex cheat sheet
• Regex 101 provides a great environment for developing and testing Regex

How Can I Use Regex in Jira?

There are three places where you are likely to use Regex in Jira:

• Automation rules – The Advanced Compare Condition in Jira automation allows you to check for text that either contains, or exactly matches a regular expression.
  ‍

• Validators  – You can also use Regex in a Jira validator to block a transition unless he contents of a given field exactly match your expression.
  ‍

‍

• JQL (with an add-on)  – Sadly, Jira search out of the box does not work with Regex. However, there are apps in the Atlassian Marketplace that will allow you to use Regex in your JQL searches.

Using Regex with Checklists

Change Status of Checklist Items to Custom Status

You can use the replaceAll function with Regex to transition checklist items to a custom status. In this case, an automation rule accessed the Checklist Text custom field to change the status of all checklist items to “Deployed” when the issue was transitioned.

{{issue.customfield_100xx.replaceAll("\[.*?\]","[Deployed]")}}

‍

Validate for a Specific Checklist Item

You can use the Regex validator to check that a specific checklist item is complete. The examples below will work with both simple checkboxes and item statuses.

• To check that a checklist item called first item is complete

(?ms).*^\*\s+\[(x|done|skipped)\]\s+first item.*

• To check that two items, called first item and second item are complete

(?ms).*^\*\s+\[(x|done|skipped)\]\s+first item.*^\*\s+\[(x|done|skipped)\]\s+second item.*

• To check that an item in a given position (4th) on the list is complete

\A(\*.*\r?\n){3}\*\s+\[(x|done|skipped)]\s+(.*\r?\n?)*\Z

The example above will block the transition if the fourth item in the list is incomplete. To block transition if Nth item is incomplete, change the 3 in the expression above to N - 1.
Note that this expression cannot be used to validate for the first item in the list, and that the list must contain at least N items. If you want to validate for more than one position in the list, you will need to create separate validators for each position.

• To check that there are no items in an Open status

(?s)^(?!.*\*\s+\[open\]).*$

‍

The following regular expressions can be used to make the transition require at least one checked item, and optionally to require that checklist has at least one item. The expressions can work with or without statuses. If you use custom statuses, you will need to adjust the expressions.

• Statuses disabled, allow empty checklist

(?s)^(?!.*\*\s+\[.*?\])|(?=.*\*\s+\[x\]).*$

• Statuses disabled, require at least one item

(?s)^(?=.*\*\s+\[x\]).*$

• Statuses enabled, allow empty checklist

(?s)^(?!.*\*\s+\[.*?\])|(?=.*\*\s+\[done|skipped\]).*$

• Statuses enabled, require at least one item

‍

(?s)^(?=.*\*\s+\[done|skipped\]).*$

‍

Validate that a Particular Checklist has a Minimum Number of Items

In this case, a team was using multiple checklists on development issues. They used a Definition of Ready checklist that was added to stories by default. Later they added an Acceptance Criteria list. A Regex validator blocked the issue from being transitioned to the QA status unless the Acceptance Criteria list was present and had at least three items:

(.|\n)*(?=# Acceptance Criteria((((\n---[^\n]*)|(\n\*\s\[.*?]\?\s[^\n]*))*\n\*\s\[.*][^\n]*)){3})(.|\n)*

‍

Transition Issue when Items on a Given Checklist are Complete

These expressions are useful if you have multiple checklists on a single issue.

• Check that all items on a given checklist are complete

(\n|.)*(# Name of the Checklist|--- Name of the Checklist)(\n(\* |---|>> )(?!\[(|open|in progress|yes)]).*)+(\n#.*|\Z)(\n|.)*

‍

• Check that all mandatory items on a given checklist are complete

(\n|.)*(# Name of the Checklist|--- Name of the Checklist)(\n(\* |---)(?!(\[] |\[open] |\[in progress] |\[yes] )).*)*(\n#.*|\Z)(\n|.)*

‍
These are just a few examples of how you can use the powerful combination of Checklists and Regular Expressions in Jira. See the automation section of our documentation for more ideas.

‍