Manipulating Checklists using Groovy Scripts

The Checklist custom field can be programmatically manipulated to extract and modify it’s 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 tool for doing this is ScriptRunner which uses groovy scripts.

Checklist Classes and API

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

Checklist Classes and Packages

Class Name

Package

Class Name

Package

ChecklistCFType

com.okapya.jira.customfields

ChecklistItem

com.okapya.jira.customfields

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

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

  • The data returned by the custom field is a collection of ChecklistItem.

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

  • To get to a specific checklist item, you will need to iterate through the collection of ChecklistItem to find it.

  • To create a new ChecklistItem, it is 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 Name

Return Value / Description

Method Name

Return Value / Description

getSingularObjectFromString(String)

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

valuesEqual(Collection<ChecklistItem>, Collection<ChecklistItem>)

Boolean. Will deeply compare both checklists and return if they have the same items.

updateValue(CustomField, Issue, Collection<ChecklistItem>)

Void. Updates the custom field value directly without dispatching any events and generating any change log.

ChecklistItem Public Methods

Method Name

Return Value / Description

Method Name

Return Value / Description

getId

Long. Unique identifier for the item (returns the Option ID if an Option).

isChecked

Boolean. Indicates if the item is checked.

getName

String. Item name.

getRank

Integer. Indicates the order of the item.

isMandatory

Boolean. Indicates if the item is mandatory.

getStatusId

String. Identifier for the item’s status (none if no status selected).

hasStatus

Boolean. Indicates if a status is present.

getOptionId

Long. Returns the ID of the Option (If applicable, otherwise returns -1).

isOption

Boolean. Indicates if this item is an option (global item).

isDisabled

Boolean. Indicates if the linked option is disabled.

toJson

String. Returns JSON representation of the item.

setRank(Integer rank)

Void. Changes the rank of the item.

setStatusId(String statusId)

Void. Changes the status ID of the item.

setDiscretionary(Boolean discretionary)

Void. Changes the discretionary (not mandatory) state of the item. Setting false means mandatory.

setChecked(Boolean checked)

Void. Changes the checked state of the item.

ChecklistItem Json Representation

It is important to note that this Json structure slightly differs from the Json structure of the https://okapya.atlassian.net/wiki/spaces/CHKDOC/pages/270172389/Modifying+Checklists+using+a+REST+API article. Use the following structure when creating a ChecklistItem:

Json Property

Type / Description

Json Property

Type / Description

id

Number. Unique identifier. This can be ignored when creating items.

optionId

Number. Option Identifier. You only need to provide the Option ID if you want to modify an option.

name

String. Name of the item. This is the only mandatory property in order to create a ChecklistItem.

checked

Boolean. Indicates if the item is checked.

mandatory

Boolean. Indicates if the item is mandatory.

rank

Number. Indicates the order of the item.

statusId

String. Indicates the status identifier of the item. “none” means no status.

Creating your first groovy script

The first step is to have access to the Checklist classes in you script. To do so, simply add the following statements in the imports section:

1 2 3 import com.onresolve.scriptrunner.runner.customisers.WithPlugin; @WithPlugin("com.okapya.jira.checklist") import com.okapya.jira.customfields.*;

Then 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. The issue is taken from inside a Scriptrunner listener def issue = event.issue; def ArrayList<ChecklistItem> existingChecklistValue = (ArrayList<ChecklistItem>) issue.getCustomFieldValue(checklistCustomField);

Finally loop over the checklist item to find if any item has 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; } }

And now you have the basic blocks to programmatically access a Checklist.

Common Examples

We have compiled a list of common tasks related to checklists. These can be the foundation of more complex tasks.

The examples in this article have been built and tested with ScriptRunner but should still be applicable to other automation tools.