Page Comparison

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.

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
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 collectionof ChecklistItem.
When you update a checklist, you also need to provide a collectionof 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
`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

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

colour	Red
title	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

Status

colour	Red
title	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 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

colour	Red
title	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 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

colour	Red
title	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 mandatoryproperty 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.

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");
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

language	java

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

root	Enhancing checklists using scripts

Status
title SERVER documentation
(On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Versions Compared

Old Version 1

New Version 2

Key

On this page:

Using Checklist classes and APIs

ChecklistCFType useful methods

ChecklistItem public methods

ChecklistItem JSON representation

Creating ChecklistItem objects using "getSingularObjectFromString"

Utility method

Creating your first Groovy script

Status
title SERVER documentation
(On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

On this page:

Using Checklist classes and APIs

ChecklistCFType useful methods

ChecklistItem public methods

ChecklistItem JSON representation

Creating ChecklistItem objects using "getSingularObjectFromString"

Utility method

Creating your first Groovy script

StatustitleSERVER documentation (On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Status
title SERVER documentation
(On Cloud? Go here.)