Checklist item representations

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

Parameter	Type	Description			Accessibility
`assigneeIds`	String[]	A list of the usernames to which the item is assigned (only one assignee is currently supported). Can only be set if the User Assignment setting is enabled.			read-write
`checked`	Boolean	Whether the item is checked or not. A disabled global item cannot be checked.			read-write
`dueDate`	String	The due date of the item as an ISO string. 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.			read-write
`isHeader`	Boolean	Whether the item is a header or not.			read-write
`mandatory`	Boolean	Whether the item is mandatory or not.			read-write
`name`	String	mandatory The name of the checklist item.			read-write
`option`	Boolean	deprecated since 5.0 removed since 6.2.2 Use `globalItemId` instead.			read-write
`priorityId`	String	The numeric priority ID of the item as a string.			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. 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

JSON property	Type	Description
`id`	Number	The unique identifier, which can be ignored when creating items.
`optionId`	Number	deprecated since 5.0 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 mandatory property 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

Method	Return value	Description
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	deprecated since 5.0 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	Deprecated since 5.0 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	deprecated since 5.0 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

Field	Type	Description
assigneeIds	String[]	A list of the usernames to which the item is assigned (only one assignee per item is currently supported).
checked	Boolean	Whether the item is checked or not.
dueDate	String	The due date of the item as an ISO string.
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.
isHeader	Boolean	Whether the item is a header or not.
mandatory	Boolean	Whether the item is mandatory or not.
name	String	MANDATORY The name of the checklist item.
priorityId	String	The numeric priority ID of the item as a string.
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.
since checklist 6.1.0 since connector 1.0.1 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.

Smart Value	Description

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.

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

Checklist for Jira - Server & Data Center Docs