Enhancing checklists using scripts

The Checklist custom field can be programmatically manipulated to extract and modify its data.

You can use any scripting tool that allows you to access the custom field’s Java-based classes, but one of the most popular tools for this is ScriptRunner, which uses Groovy scripts. All the examples provided in this section have been built and tested with ScriptRunner, but should still work with other automation tools.

On this page:

Using Checklist classes and APIs

Every custom field in Jira is based on a custom field type. The class of the Checklist custom field type is ChecklistCFType, which extends Jira’s native Multi Custom Field Type. Besides the ChecklistCFType class, another very important class is ChecklistItem, which represents a checklist item.

Class

Package

Class

Package

ChecklistCFType

com.okapya.jira.customfields

ChecklistItem

com.okapya.jira.customfields

While many operations can be performed on the custom field directly, such as extracting and updating checklist data, some operations require access to the custom field type.

Here are a few tips for interacting with the Checklist custom field:

  • The data that the custom field returns is a collection of ChecklistItem.

  • When you update a checklist, you also need to provide a collection of ChecklistItem.

  • To find a specific checklist item, you must iterate through the collection of ChecklistItem.

  • To create a new ChecklistItem, it’s best to use the getSingularObjectFromString(string) method of the ChecklistCFType class. The input string to the method is a JSON representation of a checklist item.

ChecklistCFType useful methods

Method

Return value

Description

Method

Return value

Description

getSingularObjectFromString(String)

ChecklistItem

This is the best way to create a new checklist item.

updateValue(CustomField, Issue, Collection<ChecklistItem>)

Void

Updates the custom field value directly without dispatching any events or generating any change logs.

ChecklistItem public methods

Method

Return value

Description

Method

Return value

Description

ChecklistItem.buildFromJsonString(String json)

ChecklistItem

An alternate way to build a checklist item from a JSON string.

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 https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1951662210/Using+special+formatting and https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1965752414/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 v5.0

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 v5.0

Use isGlobalItem instead.

setAssigneeIds(List<String> assignees)

Void

Changes the users to which the item is assigned. To learn more about assignees, see https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1965719702/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 v5.0

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 https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1951662210/Using+special+formatting and https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1965752414/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.

ChecklistItem JSON representation

This JSON structure differs slightly from the JSON structure in Modifying checklists using a REST API. Use the following structure when creating a ChecklistItem:

JSON property

Type

Description

JSON property

Type

Description

id

Number

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

optionId

Number

deprecated since v5.0

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).

Creating ChecklistItem objects using "getSingularObjectFromString"

The best way to create a ChecklistItem object is to use the getSingularObjectFromString(String) method of the custom field type. The input to the method is a string containing a JSON representation of the item.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 import com.atlassian.jira.component.ComponentAccessor; // Retrieve the custom field type for the Checklist custom field def customFieldManager = ComponentAccessor.getCustomFieldManager(); def checklistCustomField = customFieldManager.getCustomFieldObject("customfield_10013"); def checklistCustomFieldType = checklistCustomField.getCustomFieldType(); // JSON representation of an item def itemJson = ''' { "name": "Run all tests", "checked": false, "statusId": "none", "mandatory": false, "rank": 0 } '''; // Create a checklist item def ChecklistItem newItem = checklistCustomFieldType.getSingularObjectFromString(itemJson);

Utility method

If you need to create many checklist items, using a utility method is a good practice and will make creating ChecklistItem objects easier.

1 2 3 4 5 6 7 8 9 10 11 12 def ChecklistItem createChecklistItem(ChecklistCFType cfType, String name, boolean checked, String status, boolean mandatory, int rank) { def itemJson = """ { "name": "${name}", "checked": ${checked ? "true" : "false"}, "statusId": "${status == null || status == "" ? "none" : status}", "mandatory": ${mandatory ? "true" : "false"}, "rank": ${rank} } """; return cfType.getSingularObjectFromString(itemJson); }

Creating your first Groovy script

  1. Get access to the Checklist classes in your script by adding the following statements in the import section:

    1 2 3 import com.onresolve.scriptrunner.runner.customisers.WithPlugin; @WithPlugin("com.okapya.jira.checklist") import com.okapya.jira.customfields.*;
  2. Access the Checklist custom field and use it to get the checklist items from the issue.

    1 2 3 4 5 6 7 8 9 import com.atlassian.jira.component.ComponentAccessor; // Retrieve the Custom Field Type for the Checklist Custom Field def customFieldManager = ComponentAccessor.getCustomFieldManager(); def checklistCustomField = customFieldManager.getCustomFieldObject("customfield_10013"); // Get the Checklist value. In this example, the issue is taken from inside a Scriptrunner listener def issue = event.issue; def ArrayList<ChecklistItem> existingChecklistValue = (ArrayList<ChecklistItem>) issue.getCustomFieldValue(checklistCustomField);
  3. Loop over the checklist’s value to find out whether any items have been checked.

    1 2 3 4 5 6 7 8 def anyItemChecked = false; // Find out if any item is checked for (ChecklistItem item : existingChecklistValue) { if (item.isChecked()) { anyItemChecked = true; break; } }

Congratulations! You now have the basic building blocks to programmatically access a checklist. Next, try powering up your scripting skills even further with the other procedures provided in this section:


SERVER documentation (On Cloud? Go here.)
Have questions? Contact our Service Desk for help anytime.