Checklist Custom Fields

 

If the Save checklist data to Jira custom fields setting is enabled and the Checklist Text field is included on Jira screens, then the checklist content will be visible to users regardless of whether or not they have View checklist permission.

Overview

When Checklist is installed, five custom fields are created. These fields give you access to advanced functionality such as creating automation rules, working with the Jira REST API, or making checklist progress visible on Jira boards.

Field

Uses

Limitations

Field

Uses

Limitations

Checklist Completed

Read-only, single line text field with a value of “All Completed” or “Not Completed”.

Value will be null for issues that do not have a checklist.

  • Save Checklist data to Jira custom fields must be enabled.

  • Not available in Team-managed (Next gen) projects.

  • If there are multiple checklists on the issue and any of them are incomplete, the field will be set to “Not Complete”.

Checklist Progress

Read-only, single line text field with a value of “Checklist: x/y” where x is the number of completed items in the list and y is the total number of items in the list.

Value will be null for issues that do not have a checklist.

  • If there are multiple checklists on the issue, then progress will be shown as “x/y” where x is the total number of completed items on all of the checklists and y is the total number of items on all of the checklists.

Checklist Progress %

Read-only, number field that shows the percent of checklist items which have been completed.

Value will be null for issues that do not have a checklist.

 

  • If there are multiple checklists on the issue, the field will show the total number of completed items as a percent of the total number of items across all checklists.

Checklist Template

Single-select dropdown that allows the user to pick a checklist template they want to add to the issue. When the field is updated, the checklist will be added to the issue.

 

  • Can be used with automation, for example to add a checklist when an issue is transitioned.

  • Can be added to issue Create, Edit or Transition screens to allow users to add a template checklist.

  • Can be used when bulk editing to add a checklist to multiple issues.

  • Checklist items for each checklist template can be accessed via the Jira API.

  • If the Checklist Template field is updated when the Enable multiple checklists per issue global setting is disabled and there is already a checklist on the issue, then the selected template will be appended to the existing checklist.

  • If the Checklist Template field is updated when the Enable multiple checklists per issue global setting is enabled and there is already a checklist on the issue, then the selected template will be added as a separate checklist.

Checklist Text

Multi-line text field that stores the content of the checklist(s) and can be used to read or modify the checklist(s). The value of the field is automatically kept in sync with the checklist(s) if Save checklist data to Jira custom fields option is enabled. The field can be modified by Jira users.

  • Can be used to Import/export checklists from Trello, CSV or another Jira instance.

  • Can be used with advanced JQL to search for specific contents of a checklist.

  • Can be used when bulk editing to add a checklist to multiple issues.

  • Allows access to the checklist via the Jira API.

  • Can be used to modify a checklist when an issue is edited or transitioned.

  • Records changes to the checklist in the Jira History tab.

  • Can be used with automation or scripting apps to access and/or modify the checklist.

  • Save checklist data to Jira custom fields must be enabled (see below).

  • Field size is limited to 32,767 characters. Larger checklists may not fit into the Checklist Text field and syncing may not work as expected. 

  • To set a default checklist to be automatically added when issues are created, include the Checklist Text field as a hidden field on the Create issue screen.  Hiding the field will not impact its functionality.

  • Modification to the Checklist Text field must follow these formatting rules in order for the checklist to render correctly.

  • Not available in Team-managed (Next gen) projects.

Checklist Text (view-only) (Soon)

Multi-line text field that stores the content of the checklist(s). This field is designed to be (view-only field). So the changes you make to this field will not update your checklist(s). To provide a good overview of your checklists’ status, user mentions and item descriptions are removed from the text. So compared to the Checklist Text custom fields, this view-only version is more concise.

The value of this field is automatically kept in sync with the checklist(s) if Save checklist data to Jira custom fields option is enabled.

You can see the difference between Checklist Text and Checklist Text (view-only) in the following image:

  • They can be used with advanced JQL to search for specific issues, just like the Checklist Text field, but they are more concise.

  • They are also available in team-managed projects.

  • Save checklist data to Jira custom fields must be enabled (see below).

  • Field size is limited to 32,767 characters. Larger checklists may not fit into the Checklist Text field and syncing may not work as expected. 

  • They should not be modified be modified the user. Although their value will be updated on the every change made to the checklist.

 

Save checklist data to Jira custom fields Global Setting

Enabling the Save checklist data to Jira custom fields global setting will mean that the Checklist Text custom field will be automatically synced with the checklist(s) on the issue.  The other custom fields hold metadata and will remain in sync regardless of whether the setting is enabled.

How to Find the Custom Field ID

When using custom fields with automation, scripts, etc. you will need the ID number of the custom field.