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

Modify checklist on issue transition

Owned by Jack (Hunter) Jaroczynski
Last updated: Nov 25, 2021 by Jennifer Choban

Introduction

This page describes how to modify Checklist during issue transition (i.e. when issue is being moved to a different state in the workflow).

This feature allows to accomplish following example scenarios:

  • Add / Replace checklist with new one when issue is transitioned
  • Clear Checklist when issue is being resolved.
  • Add new Checklist items when issue is transitioned, (e.g. you can add testing notes/items to the Checklist when issue goes to QA state).

Add / Replace checklist on transition

We will use "Update Issue Custom Field" post function to modify "Checklist Text" custom field. 

  1. Prepare the Checklist that you want to add at certain workflow step:
    • Add checklist to the issue.
    • Copy checklist to the clipboard from Editor. We will use the copied value later.
  2.  Edit your workflow transition (the one that should modify Checklist) and add post function "Update Issue Custom Field":
    • Go to your JIRA/Project configuration.
    • Edit workflow and find your transition.
    • Add new post function "Update Issue Custom Field" and add new value for a "Checklist Text" field (paste the value copied in point 1)

     
  3. Test your setup (move issue through the transition changed above and watch checklist items added to the issue)

Remove checklist on transition

Removing checklist can be achieved with "Clear Field Value" post function.

Append checklist on transition

This guide is based on Jira built-in automation functionality.

The guide works for Classic projects only. Next-gen projects are too limited and do not support automation features.

Prerequisites

"Save checklist data to Jira custom fields" option must be enabled in Issue Checklist Global Settings. 

Step by step guide

  1. Create a new rule in Automation (go to Project Settings > Automation and click Create rule button)



  2. Select "Issue transitioned" as a trigger and next choose source and destination statuses (details of transition)



  3. Select Action as the next step and choose "Edit issue" from the list of actions



  4. Select Checklist Text field on the next screen 



  5. Provide details for the custom field update as presented on the screenshot, i.e.:
    1. Checklist Text field ID in the double curly braces in order to insert existing checklist (check how to find custom field ID)

    2. New checklist items that you want to append, e.g.:



      Example Text
      * [] acceptance criteria 1
* [] acceptance criteria 2

      If you want to replace/overwrite the checklist, then remove custom field ID in curly braces from the first line. Read more. 

  6. Save the rule and test your setup (transition an issue, refresh the page and spot the checklist updated).

     If it doesn't work, read this

    If the checklist is not updated then, please add Checklist Text custom field to issue screen and check if it is correctly updated when the issue is transitioned.

    1. If Checklist Text field is not updated (its content does not change) then please check the created rule, especially step 2 (source and destination transition) as the rule might not be started for a given transition.
    2. If Checklist Text field is updated but the checklist panel (list of checkboxes) does not, then most likely custom fields integration is not enabled (please enable it).
     Read why page refresh is required to see the checklist

    The following happens in the background:

    1. Issue is transitioned
    2. Jira sends a webhook notification to Automation plugin (this is asynchronous; usually 1 to 3 seconds but might take significantly more time)
    3. Automation plugin does its job (updates issue by setting the checklist field)
    4. When the issue is updated (checklist field), Jira sends a webhook notification to Checklist plugin (again, this is asynchronous; usually 1 to 3 seconds but might take significantly more time)
    5. Checklist plugin reads checklist text field and transforms it into the checklist that you can see in the UI (this is synchronous and almost instant 1-3 seconds)

    The above means that:

    • The issue page needs to be refreshed to see the checklist (because the process described in the list above is not finished yet when the issue page is loaded after transition - that is how plugins work in Jira Cloud).
    • On average, few seconds after transition are required to see the checklist in the UI (so usually the first page refresh after transition shows checklist already)
    • In rare cases, it might take longer to see the checklist (dozen of seconds or a couple of minutes so keep refreshing the issue page)