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
`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 unique ID for the checklist item. The ID is used internally by the Checklist app. It is automatically generated and can be reset during certain processes.			read
`isHeader`	Boolean	Whether the item is a header or not. 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	MANDATORY The name of the checklist item. The names of global items cannot be changed.			read-write
`priorityId`	String	The numeric priority ID of the item as a string. 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. 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
`linkedIssueKey`	String	The key of the issue created when the item got converted to an issue.			read

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
`assigneeIds`	String Array	The list of the usernames to which the item is assigned (only one assignee is currently supported).
`checked`	Boolean	Whether the item is checked or not.
`dueDate`	String	The due date of the item in ISO format.
`globalItemId`	Number	The identifier of the global item, which only needs to be provided if you want to modify a global item.
`id`	Number	The read-only unique identifier, which can be ignored when creating items. The ID is used internally by the Checklist app. It is automatically generated and can be reset during certain processes.
`isHeader`	Boolean	Whether the item is a header or not.
`linkedIssueKey`	String	The key of the issue resulting from an item-to-issue conversion.
`mandatory`	Boolean	Whether the item is mandatory or not.
`name`	String	The name of the item; this is the only mandatory property to create a checklist item.
`priorityId`	String	The numeric priority ID of the item as a string.
`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
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.
`getLinkedIssueKey`	String	The key of the issue resulting from an item-to-issue conversion.
`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.
`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.
`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.
`setDueDate(String dueDateISO)`	Void	Changes the due date of the item.
`setIsHeader(Boolean isHeader)`	Void	Changes whether the item is a header or not.
`setLinkedIssueKey(String issueKey)`	Void	Changes the linked issue key in the item.
`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). Only useful if the User Assignment setting is enabled.
checked	Boolean	Whether the item is checked or not. A disabled global item cannot be checked.
dueDate	String	The due date of the item as an ISO string. 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. The ID is used internally by the Checklist app. It is automatically generated and can be reset during certain processes.
isHeader	Boolean	Whether the item is a header or not. Only useful if the Section Headings setting is enabled.
linkedIssueKey	String	The key of the issue resulting from an item-to-issue conversion.
mandatory	Boolean	Whether the item is mandatory or not.
name	String	MANDATORY The name of the checklist item. Name changes in global items will not be saved.
priorityId	String	The numeric priority ID of the item as a string. 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. Only useful if the Statuses setting is enabled.

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.

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.
`isHeader`	Whether the item is a header or not.
`linkedIssueKey`	The key of the issue resulting from an item-to-issue conversion.
`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.

Example

CODE

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