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

Java class

Package

ChecklistCFType

com.okapya.jira.customfields

ChecklistItem

com.okapya.jira.customfields

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:

  1. The data obtained from the custom field is a Collection<ChecklistItem> object.

  2. When you update a Checklist field, you must provide the full list of items.

  3. To find a specific checklist item, you must iterate through the collection and use in-code filtering.

  4. To create a new ChecklistItem object, it is best to use the getSingularObjectFromString(string) method of the ChecklistCFType class (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

Method

Return type

Description

getSingularObjectFromString(string)

ChecklistItem

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

The parameter is expected to be a JSON representation of the item.

updateValue(CustomField, Issue, Collection<ChecklistItem>)

 

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.


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