Guide · Jira

Checklist Flow with ScriptRunner for Jira Cloud: read checklist state in scripts

Q: Does ScriptRunner need access to Checklist Flow's storage?

No. Everything a script needs is in the issue property on the work item and in the JQL fields, which Jira serves to anyone who can browse the work item.

Q: How fresh is the issue property?

It is rewritten after every change to the checklist. A linked condition that changes in Jira (for example an approval) shows in it after the next change to the checklist; Checklist Flow's panel and validator always read it live.

Q: Can a script tick checklist items?

Not through the property. Use Checklist Flow's Jira Automation actions, which record the change in the checklist history under the rule actor.

Checklist Flow for Jira 3.1.1 is the production version (1 November 2026). Last updated 29 October 2026. On the Atlassian Marketplace.

By Bartosz Stankiewicz, founder, Stanki Guild.

Checklist Flow keeps checklists in Atlassian's own storage and publishes a summary of every checklist on the work item itself, where ScriptRunner, Jira Automation, JQL and any REST client can read it. You never need an API of ours: everything below goes through Jira's own REST API, with the permissions of the user or the ScriptRunner add-on user.

The examples are starting points. ScriptRunner's helpers and Jira's expression syntax change over time, so run each one on a test project before you rely on it.

What you can read

The issue property com.stankiguild.checklistflow.dod, on every work item that has a checklist. Checklist Flow rewrites it after every change to the checklist. It is a copy: Checklist Flow's own storage stays the source of truth. Its fields:

Field	Meaning
`dodMet`	true when the Definition of Done is met (what the workflow validator checks)
`openRequired`	items still blocking the Definition of Done
`total`	checkable items (sections not counted)
`done`	checked items
`progress`	percent resolved (checked or N/A)
`assignees`	account IDs owning an open item, only when there are any
`nextDue`	earliest due date of an open item, only when there is one
`openUnassigned`	open items with no assignee
`lists`	for named checklists: name, dodMet, open, done and total of each
`listsMet`, `listsNotMet`	names of the named checklists whose Definition of Done is met and not met, only when there are any
`templates`, `templateIds`	names and ids of the templates applied (the last 20), only when there are any
`dodOpenItems`	texts of the items that block the Definition of Done (up to 50), only when a Jira administrator turned on Item text in JQL
`chainHead`	the head of the work item's checklist history: block number and SHA-256

JQL fields indexed from that property: dodMet (searched as text, "true" or "false"), dodOpen, checklistTotal, checklistDone, checklistProgress, checklistAssignee (a user), checklistDue (a date), checklistUnassigned, checklistTemplate, checklistTemplateId, checklistMet, checklistNotMet and dodOpenItem. For example dodMet = "false" AND status = "In Review", checklistAssignee = currentUser() or checklistDue < now().

The Checklist progress field ("3/5, DoD met"), once your Jira administrator adds it to screens.

Example 1: a validator for one kind of work item (Jira expression)

Block Done unless the Definition of Done is met, but only for Bugs of priority Highest, as a ScriptRunner workflow validator with a Jira expression:

issue.issueType.name != "Bug" || issue.priority.name != "Highest"
  || issue.properties['com.stankiguild.checklistflow.dod']?.dodMet == true

Checklist Flow's own Checklist Definition of Done validator does the same without ScriptRunner, and reads the checklist itself rather than the copy: add it to the transition and set Enforce only when to issue.issueType.name == "Bug" && issue.priority.name == "Highest" (paid).

Example 2: a scheduled job that nudges owners of overdue checklist items

JQL: checklistDue < now() AND statusCategory != Done

def issues = get("/rest/api/3/search/jql")
    .queryString("jql", "checklistDue < now() AND statusCategory != Done")
    .queryString("fields", "summary")
    .asObject(Map).body.issues
issues.each { issue ->
    def dod = get("/rest/api/3/issue/${issue.key}/properties/com.stankiguild.checklistflow.dod")
        .asObject(Map).body.value
    post("/rest/api/3/issue/${issue.key}/comment")
        .header("Content-Type", "application/json")
        .body([body: [type: "doc", version: 1, content: [[type: "paragraph", content: [[type: "text",
            text: "Checklist item due ${dod.nextDue} is overdue (${dod.openRequired} required item(s) open)."]]]]]])
        .asString()
}

Example 3: a listener that labels work items whose Definition of Done is met

Event: Issue Updated (or run it on a schedule).

def key = issue.key
def resp = get("/rest/api/3/issue/${key}/properties/com.stankiguild.checklistflow.dod").asObject(Map)
if (resp.status == 200 && resp.body.value?.dodMet == true) {
    put("/rest/api/3/issue/${key}")
        .header("Content-Type", "application/json")
        .body([update: [labels: [[add: "dod-met"]]]])
        .asString()
}

Writing to checklists

Checklist Flow does not take writes through the issue property: it is overwritten after each change. To change a checklist from a rule, use Checklist Flow's Jira Automation actions: Add, Check, Uncheck and Remove checklist item, Set Required, Set N/A, Set due date, Set assignee, Set status, Check all, Add items from text, Apply checklist template, Apply checklist rules and Get checklist status.

How our app helps

Checklist Flow is our app: Definition of Done checklists with Required items, a workflow validator that blocks the transition, JQL fields and a hash-chained history. Pricing: free for up to 10 users with every feature, then from USD 0.80 per user per month for the first 100 users. See the documentation.

Common questions

Does ScriptRunner need access to Checklist Flow's storage?