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:
Table of Contents | ||
---|---|---|
|
On this page:
Table of Contents | ||||
---|---|---|---|---|
|
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. The class of the Checklist custom field type is ChecklistCFType
, 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. Besides the ChecklistCFType
class, another very important class is ChecklistItem
, which represents a checklist item.
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 can be performed on the custom field directly, such as extracting and updating checklist datadirectly from Jira’s native CustomField
interface, some operations require access to the custom field 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
ChecklistItem
Collection<ChecklistItem>
object.When you update a
Checklist field, you
ChecklistItem
must provide the full list of items.
To find a specific checklist item, you must iterate through the collection
ChecklistItem
and use in-code filtering.
To create a new
ChecklistItem
object,
it is best to use the
getSingularObjectFromString(string)
method of theChecklistCFType
class
ChecklistCFType useful methods
Method
(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. |
|
Void
Updates the |
checklist field’s value directly without dispatching any events or generating any change logs. |
ChecklistItem
publicmethods
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 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.
getOptionId
Long
Status | ||||
---|---|---|---|---|
|
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
Status | ||||
---|---|---|---|---|
|
Use isGlobalItem
instead.
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.
setDicretionary(Boolean discretionary)
Void
Status | ||||
---|---|---|---|---|
|
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 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.
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
id
Number
The unique identifier, which can be ignored when creating items.
optionId
Number
Status | ||||
---|---|---|---|---|
|
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
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.
Code Block | ||
---|---|---|
| ||
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.
Code Block | ||
---|---|---|
| ||
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
Get access to the Checklist classes in your script by adding the following statements in the import section:
Code Block language java import com.onresolve.scriptrunner.runner.customisers.WithPlugin; @WithPlugin("com.okapya.jira.checklist") import com.okapya.jira.customfields.*;
Access the Checklist custom field and use it to get the checklist items from the issue.
Code Block language java 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);
Loop over the checklist’s value to find out whether any items have been checked.
Code Block language java 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:
Page Tree
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.
Page Tree | ||||
---|---|---|---|---|
|
Status | ||
---|---|---|
|