Skip to main content

Checklist Workflow Automation for Jira — User Guide

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​

  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).

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.
  • 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​

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)​

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​

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​

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 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 — 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 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​

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​

  • 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?