You can manipulate checklists using Jira’s REST APIs to:
Retrieve an issue's checklist data.
Use Jira’s Get Issue REST API.
Create an issue and supply checklist data.
Use Jira’s Create Issue REST API.
Update an existing issue’s checklist data.
Use Jira’s Edit Issue REST API.
Get the default value of a checklist, meaning the global items and default items.
Use Jira’s CreateMeta REST API or EditMeta REST API.
The data is available in the
allowedValues
property.The status returned by these APIs will only have an ID and no name.
(e.g.{ id: ‘inProgress’ } }
and not{ id: ‘inProgress’, name: ‘In Progress’ }
).
JSON schema structure
When a checklist is manipulated with REST APIs, it will be an array of checklist items.[ checklist-item, checklist-item, ...]
The properties of a checklist item are as follows:
Parameter
Type
Description
Accessibility
assigneeIds
String[]
A list of the usernames to which the item is assigned (only one assignee is currently supported).
Note |
---|
Can only be set if the User Assignment setting is enabled. |
read-write
checked
Boolean
Whether the item is checked or not.
Note |
---|
A disabled global item cannot be checked. |
read-write
dueDate
String
The due date of the item as an ISO string.
Note |
---|
Can only be set if the Due Dates setting is enabled. |
read-write
globalItemId
Number
The internal unique ID of the global item to which this item is linked.
When no ID is set, the item is considered to be a local item.
read-write
id
Number
The ID for the checklist item.
Info |
---|
The ID is automatically created and does not need to be manually set. If you do set an ID, ensure that it is unique across the entire checklist. |
read-write
isHeader
Boolean
Whether the item is a header or not.
Note |
---|
Can only be set to |
read-write
mandatory
Boolean
Whether the item is mandatory or not.
read-write
name
String
Status | ||||
---|---|---|---|---|
|
The name of the checklist item.
Note |
---|
The names of global items cannot be changed. |
read-write
option
Boolean
Status | ||||
---|---|---|---|---|
|
Use globalItemId
instead.
read-write
priorityId
String
The numeric priority ID of the item as a string.
Note |
---|
Can only be set if the Priorities setting is enabled. |
read-write
rank
Number
The rank of the item in the checklist, starting from 0. When the checklist is updated, the rank value is ignored, and the order in which the items are set in the array of checklist items is applied.
read
status
Object
The object that contains the status information. Only valid status IDs are accepted.
Note |
---|
Can only be updated if the Statuses setting is enabled. |
Also comes with the following sub-parameters:
read-write
name
String
The name of the status.
read
id
String
The status ID.
read-write
See here for the checklist item JSON structure for Jira REST APIs.
Update operations
When you update an issue, you can do perform different operations on the checklist. Here’s a list of supported operations and how to use them.
Set
The set operation overwrites the whole checklist with a new set of items. This means that all checklist items (including global items) must be provided on every update. As a result, a good operation workflow would be to query the existing issue value, modify the payload, and update it back.
Example payload of a set operation with one global item and one local item:
Code Block | ||
---|---|---|
| ||
{ "update": { "customfield_10101": [ { "set": [ { "id": 1, "name": "Code Review", "checked": false, "mandatory": true, "priorityId": "2", "dueDate": "2020-01-25T00:00:00.000Z", "assigneeIds": ["admin"], "globalItemId": 12001 }, { "id": 2, "name": "Reviewed by Architect", "checked": false, "mandatory": true, "status": { "id": "inProgress" } } ] } ] } } |
Add
Status | ||
---|---|---|
|
The add operation lets you add local items to an existing list. When an item is added, the id
field is ignored, and a new identifier is generated for the item.
The rank is a zero-based position that represents where the item will be located in the checklist. If no rank is provided, the item will automatically be added at the end of the checklist.
Example payload that adds two items, with one at the beginning of the checklist, and one at the end:
Code Block | ||
---|---|---|
| ||
{ "update": { "customfield_10101": [ { "add": [ { "name": "Run integration tests", "status" { "id": "blocked" }, "rank": 0 }, { "name": "Publish to production" } ] } ] } } |
Edit
Status | ||
---|---|---|
|
The edit operation lets you modify an item in the checklist. The id
field is required to identify which item will be modified.
The rank is a zero-based position that represents where the item will be located in the checklist.
Example payload that moves an item to the 4th position in the list and changes the due date and priority of another item:
Code Block | ||
---|---|---|
| ||
{ "update": { "customfield_10101": [ { "edit": [ { "id": 1, "rank": 3 }, { "id": 2, "dueDate": "2000-01-01T00:00:00.000Z", "priorityId": 2 } ] } ] } } |
Remove
Status | ||
---|---|---|
|
The remove operation lets you remove an item in the checklist. The id
field is required to identify which item will be removed.
Example payload that removes the items with IDs 1 and 2:
Code Block | ||
---|---|---|
| ||
{ "update": { "customfield_10101": [ { "remove": [ { "id": 1 }, { "id": 2 } ] } ] } } |
Status | ||
---|---|---|
|