Enhancing checklists using Groovy scripts
The Checklist custom field can be programmatically manipulated to extract and modify its data.
Preface
Groovy uses the Java classes directly. For Checklist, those classes are internal classes and were not built with public use in mind. This guide will provide standard methods to access and manipulate Checklist data using Groovy scripts and serve as a starting point for your custom scripts. If you want to dig deeper into the scripting mechanics and possibilities, you can read more on Java and ScriptRunner.
Since the Java classes are not meant for public use, they are subject to change without notice, although it happens very rarely.
The Java classes
Every custom field in Jira is based on a custom field type, which is represented by a Java class. For the Checklist fields, the Java class is the ChecklistCFType class, which extends Jira’s native Multi Custom Field Type. Checklists are obtained as a list of items, and the associated Java class for each item isChecklistItem.
Java class | Package |
|---|---|
|
|
|
|
While you can perform many operations directly from Jira’s native CustomField interface, some operations require access to the Checklist field’s type.
Here are a few tips for interacting with the Checklist custom field:
The data obtained from the custom field is a
Collection<ChecklistItem>object.When you update a Checklist field, you must provide the full list of items.
To find a specific checklist item, you must iterate through the collection and use in-code filtering.
To create a new
ChecklistItemobject, it is best to use thegetSingularObjectFromString(string)method of theChecklistCFTypeclass (defined below).
ChecklistCFType methods
This table does not represent all of the class’ methods. It only shows the most commonly used methods for most use cases.
Method | Return type | Description |
|---|---|---|
|
| This is the best way to create a new checklist item. The parameter is expected to be a JSON representation of the item. |
| Updates the checklist field’s value directly without dispatching any events or generating any change logs. |
ChecklistItem methods
The checklist item’s Java class methods are available here.
Examples and guides
We’ve built the examples on the following pages using one of the most popular Groovy scripting apps, ScriptRunner for Jira. The scripts should still function with other Groovy scripting tools and apps.