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

Checklist Custom Fields

 

 

Overview

When Checklist is installed, six 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 local checklist items to Jira custom fields must be enabled (see below).

  • 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

  • The Checklist Template custom field has been deprecated. It is recommended that you use labels integration to add Checklist Templates to issues.

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.

 

Enable the Apply checklist templates from issue labels global setting as an alternative to using this field.

  • 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 local checklist items 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 local checklist items 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)

A view-only copy of the Checklist Text field without user mentions or item descriptions.

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

The difference between Checklist Text and Checklist Text (view-only) is shown below:

  • Can be used to display a more concise view of the checklist content (for example, in JQL search results).

  • Save local checklist items 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. 

  • This field is intended to be view-only. Any changes a user makes to the field will be immediately overwritten upon the next sync from the database.

 

Save local checklist items 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.

To find the ID of the custom field:

  1. Log in as a Jira Administrator.

  2. Go to Jira Settings > Issues > Custom fields.

  3. Search for the indicated custom field.

  4. Click the More menu () and select Edit Details.

  5. Copy the URL of the page. The URL will end with the ID number of the custom field.