Getting started with ScriptRunner

In this section, we will provide you with the necessary tools to build scripts with Checklist.

Import the Checklist Java classes

Import the Checklist Java classes using the following statements:

GROOVY

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

Interacting with checklist values

There are two main methods for getting checklist items. You may encounter a situation where one method doesn’t work well with your use case and the code you are writing. To get an idea of which method you should use, refer to the table below.

Method	Fetching data	Updating data
`Issue` / `Issue Manager`	Values are obtained from the database once and are then saved in the issue object in memory. For multiple calls, this method is more performant. Keeps track of multi-segmented changes, such as in post functions when the same issue object is passed from one function to the other.	An `Issue Updated` event is dispatched. A changelog is created. The custom field value is obtained from the issue.
`ChecklistCFType`	Values are always obtained from the database. Data is always the latest value saved. Encourages data accuracy but does not keep track of changes during a multi-segmented process like post functions.	No `Issue Updated` event is dispatched. No change log is created. The custom field value is obtained from the `ChecklistCFType`.

Choose wisely between these two methods based on your use case. For instance, you should not use the IssueManager to save data inside an Issue Updated event listener because it will likely create an infinite loop.

Getting items from issues

The following examples show how to get items from issues using the previously mentioned methods.

For both methods, start by getting the CustomFieldManager, which will help you get the CustomField object that represents the Checklist field that you want the items for.

From the issue

GROOVY

import com.onresolve.scriptrunner.runner.customisers.WithPlugin;
import com.atlassian.jira.component.ComponentAccessor;
@WithPlugin("com.okapya.jira.checklist")
import com.okapya.jira.customfields.*;

// The issue isn't defined in this example because it can come from many sources.
// See ScriptRunner's documentation to know where the issue object should come from: https://docs.adaptavist.com/sr4js/latest

def customFieldManager = ComponentAccessor.getCustomFieldManager();
// Change the ID to whatever ID your field has.
def checklistField = customFieldManager.getCustomFieldObject("customfield_10013");

Collection<ChecklistItem> items = (Collection<ChecklistItem>) issue.getCustomFieldValue(checklistField);

From the ChecklistCFType

GROOVY

import com.onresolve.scriptrunner.runner.customisers.WithPlugin;
import com.atlassian.jira.component.ComponentAccessor;
@WithPlugin("com.okapya.jira.checklist")
import com.okapya.jira.customfields.*;

// The issue isn't defined in this example because it can come from many sources.
// See ScriptRunner's documentation to know where the issue object should come from: https://docs.adaptavist.com/sr4js/latest

def customFieldManager = ComponentAccessor.getCustomFieldManager();
// Change the ID to whatever ID your field has.
def checklistField = customFieldManager.getCustomFieldObject("customfield_10013");
def checklistCFType = (ChecklistCFType) checklistField.getCustomFieldType();

Collection<ChecklistItem> items = (Collection<ChecklistItem>) checklistCFType.getValueFromIssue(checklistField, issue);

Updating items in issues

The following examples show how to update items in issues using the previously mentioned methods.

With IssueManager

GROOVY

import com.onresolve.scriptrunner.runner.customisers.WithPlugin;
import com.atlassian.jira.component.ComponentAccessor;
import com.atlassian.jira.event.type.EventDispatchOption;
@WithPlugin("com.okapya.jira.checklist")
import com.okapya.jira.customfields.*;

// The following script assumes you already have these objects on hand.
// def user --> currently logged in user or the event's user
// def issue --> the issue you want to update. It can come from an event, a JQL search, etc.

def customFieldManager = ComponentAccessor.getCustomFieldManager();
// Change the field ID to whatever ID your field has
def checklistField = customFieldManager.getCustomFieldObject("customfield_10001");

// We fetch the items from the issue
Collection<ChecklistItem> items = (Collection<ChecklistItem>) issue.getCustomFieldValue(checklistCustomField);

// Do whatever changes you need to do to the items
// [...]

def issueManager = ComponentAccessor.getIssueManager();
issue.setCustomFieldValue(checklistField, items.toList());
issueManager.updateIssue(user, issue, EventDispatchOption.ISSUE_UPDATED, false);

With ChecklistCFType

GROOVY

import com.onresolve.scriptrunner.runner.customisers.WithPlugin;
import com.atlassian.jira.component.ComponentAccessor
@WithPlugin("com.okapya.jira.checklist")
import com.okapya.jira.customfields.*;

// The following script assumes you already have this object on hand.
// def issue --> the issue you want to update. It can come from an event, a JQL search, etc.

def customFieldManager = ComponentAccessor.getCustomFieldManager();
// Change the field ID to whatever ID your field has
def checklistField = customFieldManager.getCustomFieldObject("customfield_10001");
def checklistCFType = (ChecklistCFType) checklistField.getCustomFieldType();

// We fetch the items from the checklistCFType
Collection<ChecklistItem> items = (Collection<ChecklistItem>) checklistCFType.getValueFromIssue(checklistField, issue);

// Do whatever changes you need to do to the items
// [...]

checklistCFType.updateValue(checklistField, issue, items);

Loop through checklist items

Once you have obtained your Checklist field’s items, you can loop through them to either update or validate them.

GROOVY

// Starting from the last example where we obtained the items from an issue.
// item is a Collection<ChecklistItem>
for (ChecklistItem item : items) {
    // Update the items based on a condition or keep track of a validation of your choice
}