We have a new documentation site. Please go here to see the latest.

Block workflow transition if checklist is not complete

Introduction

This page describes how to block workflow transition if there is an unchecked item on the checklist.

As a result, all checklist items must be completed to move the issue to another status (e.g. Done or Resolved).

This guide works for Classic (Company managed) projects only. Next-Gen (team managed) projects do not support workflow validators (Jira limitation). 

Prerequisites

None. "Save checklist data to Jira custom fields" option from Issue Checklist Global Settings does not influence this feature.

Step by step guide

Here is a step-by-step instruction on how to configure Jira to block selected transitions.

Configuration:

  1. Navigate to "Project settings > Workflows" or "Jira settings > Issues > Workflows".
  2. Edit the selected workflow (click "pen" icon or "Edit" link)
  3. Select Diagram view (1) and next select the transition (2) that you want to block, e.g. Done. After that press Validators link (3):



  4. Press "Add Validator" link:



  5. Select "All checklist items are completed" validator and press "Add" button:



  6. Confirm that validator is available on the list and press "Publish Draft" link:


Test how it works

  • Confirm that validator (blocking issue transition) works fine:
    • Open issue in a project that uses modified workflow
    • Add checklist items and leave at least one of them unchecked
    • Press the transition button and observe the error message displayed by Jira

      Old Issue View:



      New Issue View:



      Sprint / Board View:

       

Troubleshooting

Issue Checklist tells Jira to use issue entity properties to provide the following features:

Therefore, the Issue Checklist must be able to set issue entity properties (which is the default behavior). 

However, Issue Checklist might not be able to set issue entity property if jira.permission.* workflow property is set on a workflow step. For example, the following property will prevent Issue Checklist from setting issue properties, and features listed above won't work correctly:

Solution: please remove jira.permission.* workflow property and use standard Jira permissions to control who can edit the issue.