Page Comparison

Checklist items can be represented in different ways.

This guide will provide the different structures in which items can be found and interacted with.

JSON (Jira REST API)

When interacting with Checklist in Jira REST APIs, the structure will always be an array of checklist item objects.

[checklistItem, checklistItem, ...]

The properties of each checklist item is 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 `true` if the Section Headings setting is enabled.

read-write

mandatory

Boolean

Whether the item is mandatory or not.

read-write

name

String

Status

colour	Yellow
title	mandatory

The name of the checklist item.

Note
The names of global items cannot be changed.

read-write

option

Boolean

Status

colour	Red
title	deprecated since 5.0

Status

colour	Red
title	removed since 6.2.2

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

JSON

The JSON structure differs slightly whenever you are working outside of Jira REST APIs. You will most likely find this structure when working with JSON in the Checklist custom REST APIs or when working with the Java class.

JSON property

Type

Description

id

Number

The unique identifier, which can be ignored when creating items.

optionId

Number

Status

colour	Red
title	deprecated since 5.0

Status

colour	Red
title	removed since 6.2.2

Replaced by globalItemId.

globalItemId

Number

The identifier of the global item, which only needs to be provided if you want to modify a global item.

name

String

The name of the item; this is the only mandatoryproperty to create a checklist item.

checked

Boolean

Whether the item is checked or not.

isHeader

Boolean

Whether the item is a header or not.

assigneeIds

String Array

The list of the usernames to which the item is assigned (only one assignee is currently supported).

dueDate

String

The due date of the item in ISO format.

priorityId

String

The numeric priority ID of the item as a string.

mandatory

Boolean

Whether the item is mandatory or not.

rank

Number

The order of the item.

statusId

String

The status ID of the item (none if no status is selected).

Java class

The ChecklistItem Java class uses public methods (as opposed to properties). The class is particularly useful when used in direct code-accessing scripting (like Groovy) or in app-integrations.

Here is a list of the ChecklistItem class public methods:

Method

Return value

Description

Status

colour	Yellow
title	static

ChecklistItem.buildFromJsonString(String json)

ChecklistItem

An alternate way to create a new checklist item. You should not use this approach if you are creating items with a globalItemId value.

The parameter is expected to be a JSON representation of the item.

formatDueDate(String format)

String

Returns the due date formatted in the desired format (see the Available formats).

getAssigneeIds

List<String>

The usernames of the users to which the item is assigned.

getDueDate

String

The due date (and time) of the item in ISO format.

getGlobalItemId

Integer

The ID of the global item (previously known as an “option”), if applicable, otherwise -1 is returned.

getId

Integer

Unique identifier for the item.

getIsHeader

Boolean

Whether the item is a header or not.

getName

String

The name of the item, including Markdown and the description.

To learn more about Markdown and descriptions, see Using special formatting and Adding descriptions to items or headers.

getNameWithoutDescription(Boolean trim)

String

The name of the item, without the description. Passing true to the trim parameter strips the name of line breaks and redundant spaces.

getOptionId

Long

Status

colour	Red
title	deprecated since 5.0

Status

colour	Red
title	removed since 6.2.2

Use getGlobalItemId instead.

getPriorityId

String

The numeric priority ID of the item as a string.

getPriorityName

String

The name of the priority assigned to the item.

This searches Jira’s priority scheme. If the item’s priority ID is not found in the scheme, an empty string will be returned.

getRank

Integer

The rank of the item in the checklist.

getStatusId

String

The status ID of the item (none if no status is selected).

hasStatus

Boolean

Whether the item has a status or not. If getStatusId returns none, this will return false.

isChecked

Boolean

Whether the item is checked or not.

isDisabled

Boolean

Whether the linked global item (previously known as an “option”) is disabled or not.

isGlobalItem

Boolean

Whether the item is a global item (previously known as an “option”) or not.

isMandatory

Boolean

Whether the item is mandatory or not.

isOption

Boolean

Status

colour	Red
title	Deprecated since 5.0

Status

colour	Red
title	removed since 6.2.2

Use isGlobalItem instead.

setAssigneeIds(List<String> assignees)

Void

Changes the users to which the item is assigned. To learn more about assignees, see Assigning users to items.

Only the first assignee is taken into account.

setChecked(Boolean checked)

Void

Changes the checked state of the item.

setDicretionary(Boolean discretionary)

Void

Status

colour	Red
title	deprecated since 5.0

Status

colour	Red
title	removed since 6.2.2

Use setMandatory instead.

setDueDate(String dueDateISO)

Void

Changes the due date of the item.

setIsHeader(Boolean isHeader)

Void

Changes whether the item is a header or not.

setMandatory(Boolean mandatory)

Void

Changes the mandatory state of the item.

setName(String name)

Void

Changes the item name, including Markdown and the description, as required.

To learn more about Markdown and descriptions, see Using special formatting and Adding descriptions to items or headers.

setPriorityId(String priorityId)

Void

Changes the priority ID of the item.

setRank(Integer rank)

Void

Changes the rank of the item.

Global item ranks cannot be changed.

Setting an item’s rank to a rank already in use by another item will have unpredictable results. The changed item may end up before or after the other item.

setStatusId(String statusId)

Void

Changes the status ID of the item.

toJson

String

Returns the JSON representation of the item.

oChecklistItem SIL structure

This structure makes it easier to manipulate checklist items in SIL scripts without having to worry about the back-end JSON format.

Field

Type

Description

assigneeIds

String[]

A list of the usernames to which the item is assigned (only one assignee per item is currently supported).

Note
Only useful if the User Assignment setting is enabled.

checked

Boolean

Whether the item is checked or not.

Note
A disabled global item cannot be checked.

dueDate

String

The due date of the item as an ISO string.

Note
Only useful if the Due Dates setting is enabled.

globalItemId

Number

The internal unique ID of the global item to which the item is linked.

When no ID is set, the item is considered to be a local item.

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 different from all other checklist items.

isHeader

Boolean

Whether the item is a header or not.

Note
Only useful if the Section Headings setting is enabled.

mandatory

Boolean

Whether the item is mandatory or not.

name

String

Status

colour	Yellow
title	MANDATORY

The name of the checklist item.

Note
Name changes in global items will not be saved.

priorityId

String

The numeric priority ID of the item as a string.

Note
Only useful if the Priorities setting is enabled.

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 organized in the array of checklist items is applied.

statusId

String

The status ID of the item.

Note
Only useful if the Statuses setting is enabled.

Status

title	since checklist 6.1.0

Status

title	since connector 1.20.01

linkedIssueKey

String

The key of the issue resulting from an item-to-issue conversion.

Smart Value

The Smart Value representation is very similar to the JSON representation, the biggest difference being that the assignee’s information is directly available to improve usability in the automation rules.

Info
The following values may be incomplete depending on the context in which they are used. See the integration page of the trigger you are using for more details.

Smart Value	Description
`id`	The ID for the checklist item.
`globalItemId`	The internal unique ID of the global item to which the item is linked. When no ID is set, the item is considered to be a local item.
`name`	The name of the checklist item, including its description and Markdown formatting.
`checked`	Whether the item is checked or not.
`assigneeName`	The assignee's full name.
`assigneeUserName`	The assignee's username.
`assigneeEmail`	The assignee's email address.
`dueDate`	The due date of the item as an ISO string.
`priorityId`	The numeric priority ID of the item as a string.
`mandatory`	Whether the item is mandatory or not.
`rank`	The rank of the item in the checklist, starting from 0.
`statusId`	The status ID of the item ("none" if no status is selected).
`statusName`	The name of the item’s status.

Previous state of items

All values can be accessed in their previous state by appending last at the start of the value and capitalizing the first letter of the value.

Expand

title	Example

Code Block
The item’s name was changed from {{lastName}} to {{name}} Its previous status was {{lastStatusName}}. Now it is {{statusName}}.

Versions Compared

Old Version 3

New Version Current

Key

On this page:

JSON (Jira REST API)

JSON

Java class

oChecklistItem SIL structure

Smart Value

Previous state of items

Status
title SERVER documentation
(On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

On this page:

JSON (Jira REST API)

JSON

Java class

oChecklistItem SIL structure

Smart Value

Previous state of items

StatustitleSERVER documentation (On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Status
title SERVER documentation
(On Cloud? Go here.)