# Checklist Workflow Automation for Jira — User Guide

## Introduction[​](#introduction "Direct link to Introduction")

Checklist Workflow Automation for Jira adds a checklist to every issue — and, unlike a plain checkbox list, it can **enforce** your process: mark an item as `required`, and Jira blocks the workflow transition until every required item is exactly **Done**. No workflow-editor rules to maintain, no scripts — the enforcement rule lives on the checklist items themselves.

Everything runs natively in Jira Cloud (built 100% on Atlassian Forge). The checklist is stored on the issue itself, so it survives moves, shows up in JQL searches, and copies when you clone an issue.

## Quick start[​](#quick-start "Direct link to Quick start")

1. Install from the Atlassian Marketplace (try it free on your own site).
2. Open any issue — the checklist panel is on the issue's right side.
3. Type a task and press **Enter**. Keep typing to add more.
4. Toggle the flag on a row (or the header flag for the whole list) to mark items **required**.
5. Ask a Jira admin to attach the **validator** to your workflow's Done transition (see [Enforcement](#enforcement-blocking-transitions-until-required-items-are-done)).

## The checklist panel[​](#the-checklist-panel "Direct link to The checklist panel")

```
2/5  ▓▓▓▓▓▓░░░░░░░░░░░  40%  [ ⋯ ]

──────────────────────────────────────

⚑  ☐  Book venue                [date]

   ☐  Send invites     Waiting  [date]

   ☑  Reserve budget      Done

[ + Add a task, press Enter… ]
```

* **All-in-place editing** — click a task's text to edit it right in the row; no modal. Press Enter to save, Esc to cancel.
* **Sub-tasks** — nest items under a parent; the progress bar tracks the parent.
* **Statuses** — six built-in statuses (To Do, In Progress, Blocked, Review, Done, Skipped) shown as colored lozenges. Projects can add their own — see [Project settings](#project-settings-the-checklist-admin-page).
* **Due dates** — click the date chip: Today / Tomorrow / In 7 days, or pick any date. Overdue items show a red lozenge; due-within-2-days shows amber.
* **Required flags** — the flag column marks items that gate the workflow. Blue flag = required and unfinished.
* **Markdown** — item text renders markdown: bold, links, code, and more.
* **Header controls** — the header checkbox completes/clears the whole list; the header flag marks everything required; the **⋯** menu holds templates, CSV import/export and more.

Completed items stay in place with a strike-through, so the list order never jumps.

## Enforcement: blocking transitions until required items are done[​](#enforcement-blocking-transitions-until-required-items-are-done "Direct link to Enforcement: blocking transitions until required items are done")

### The one rule[​](#the-one-rule "Direct link to The one rule")

> A transition is blocked ⟺ some item marked `required` is not exactly **Done**. **Skipped does not count** as done, and neither do any custom statuses.

The same rule drives the workflow validator, JQL search, and overdue reminders — there is one definition of "not finished" everywhere.

**Custom statuses never count as Done.** Projects can add their own statuses (e.g. *Waiting on vendor*) for bookkeeping; a required item sitting on a custom status still blocks the transition. Only exactly **Done** satisfies a requirement.

### Attaching enforcement to a workflow (Jira admin)[​](#attaching-enforcement-to-a-workflow-jira-admin "Direct link to Attaching enforcement to a workflow (Jira admin)")

The validator and post function are standard Jira workflow elements — add them once per workflow, no ongoing configuration:

**Validator — block the transition**

1. Go to **Project settings → Workflows** and edit your workflow.
2. On the transition that should be gated (typically the one into **Done**), choose **Validators → Add validator**.
3. Pick **Checklist required items complete** (category: *Forge apps*).

While any required item is unfinished, the transition is refused with: `Complete required checklist items before transitioning: "Book venue", …`

If the app cannot read a checklist (e.g. its data was deleted), the validator **fails open** — a broken app must never brick a workflow.

**Post function — auto-complete on transition**

1. On the same (or any) transition, choose **Post functions → Add post function**.
2. Pick **Complete required checklist items**.

After the transition runs, every **required** item is marked Done. Non-required items are never touched, and JQL counts refresh in the same step.

## Finding work with JQL[​](#finding-work-with-jql "Direct link to Finding work with JQL")

```
issue in hasIncompleteRequired()

cwaIncompleteRequired > 0

cwaOverdueRequired > 0

cwaIncompleteRequired > 0 AND assignee = currentUser() AND sprint in openSprints()
```

* `hasIncompleteRequired()` — issues with at least one unfinished required item.
* `cwaIncompleteRequired` / `cwaOverdueRequired` — indexed counters (support `ORDER BY`); they refresh on every panel edit and are self-corrected by the daily sweep.
* The negation `issue NOT IN hasIncompleteRequired()` includes issues without a checklist at all.

Save any of these as a filter for a **team QA board** or a dashboard gadget — e.g. "everything I still owe before Done".

## Overdue reminders[​](#overdue-reminders "Direct link to Overdue reminders")

A daily sweep finds unresolved issues where a **required** item is past its due date and posts a comment mentioning the assignee, listing the overdue items. Each issue is reminded at most once per **7 days**; resolving the issue or finishing the items stops reminders automatically.

## Cloning issues[​](#cloning-issues "Direct link to Cloning issues")

Cloning an issue copies the checklist — texts, required flags, sub-tasks, assignees, due dates — with every status reset to **To Do** (a clone means "do this work again"). Uses Jira's standard *Cloners* link; ordinary issue creation is unaffected.

## Templates and CSV[​](#templates-and-csv "Direct link to Templates and CSV")

* **Templates** — save a checklist as a reusable project template and apply it to any issue in that project (the ⋯ menu).
* **CSV import/export** — bulk-edit in a spreadsheet. Exported files round-trip: import restores texts, statuses (including custom ones), due dates and required flags. Unknown status values fall back to To Do on import.

## Project settings: the Checklist Admin page[​](#project-settings-the-checklist-admin-page "Direct link to Project settings: the Checklist Admin page")

Project admins open **Project settings → Checklist Admin**:

* **Settings tab**

  * *Display mode* — `Both` (checkboxes + status column, the default), `Status` (complete items via the status menu; checkbox column hidden), or `Checkbox` (plain done/not-done; status column hidden).
  * *Mark new items as required by default* — new rows start required.
  * *Custom statuses* — add up to 10 project-specific statuses (label + color). Values are stable across renames, and custom statuses never satisfy a required item. Removing one keeps the stored data; affected items display as To Do until re-statused.

* **Audit log tab** — an append-only record of who created, edited, completed, required or deleted items, and who applied templates or imports, with before/after detail. Entries are identified from Jira's server-side context, so they can't be spoofed from the client.

## FAQ[​](#faq "Direct link to FAQ")

**Do required items block issue creation or other transitions?** No. Only transitions with the validator attached are gated, and the validator only inspects checklist items — it never blocks issue creation.

**What happens to items when someone removes the app?** The checklist lives in a standard Jira issue property, so the data stays on the issue. Validators attached to workflows keep failing open (transitions pass).

**Can different projects behave differently?** Yes — display mode, required-by-default and custom statuses are all per-project settings.

**Does this work on team-managed projects?** Company-managed projects get the full enforcement flow (workflow validator / post function). Team-managed projects don't support Forge workflow rules, so there the app works as a checklist panel without transition gating.

**Which plan/tier do I need?** Any Jira Cloud plan; the app itself is free for small teams — see the Marketplace listing for current pricing tiers.

## Limitations & notes[​](#limitations--notes "Direct link to Limitations & notes")

* Overdue is evaluated against **UTC midnight** everywhere (validator, JQL, reminders); the panel's date label is browser-local.
* The daily reminder sweep caps at 500 issues per day; anything beyond waits for the next day's run.
* Mentions typed in item text are stored but rendered as plain identifiers; the reminder comment is a real Jira mention with a real notification.
* There is no board-card progress bar yet — Forge doesn't let issue-property apps render on cards.

Was this helpful?👍 Yes👎 No