Skip to main content

​
The checklist item: one row, several independent facts

A checklist item is not just a label and a checkbox. It’s a small record that carries several independent pieces of information at once:
  • Label — the visible text of the item, such as “Peer review completed.”
  • Result state — the current outcome recorded for this item: Empty (default), OK, NOK, or Pending (plus a separate, non-selectable Information row type).
  • Mandatory flag — whether this item must be checked for the checklist to be considered complete.
  • Description — static guidance text, typically written once by whoever authored the template, explaining what the reviewer should actually check.
  • Note — free text a reviewer adds while working the item, distinct from the description.
  • Template origin — whether the item was populated from a checklist template or added directly on this instance.
A useful analogy: the label and description are like the printed instructions on a paper form (“check that the fire extinguisher is present — see inspection guide §3”), while the note is what the inspector scribbles in the margin (“replaced 2024-03-01, next due 2025-03-01”). Both live on the same row, but they come from different authors and serve different purposes — the description doesn’t change reviewer to reviewer, the note does.
An item with no result set is still meaningfulAn item that has never been touched defaults to the Empty / none state rather than to some arbitrary value. This matters when you’re reasoning about “why does this checklist show as incomplete” — an item nobody has looked at yet is indistinguishable, at the data level, from one explicitly reset.

​
The result states

A plain checkbox collapses reality into two states: checked or not. A compliance-grade checklist needs more resolution than that, because “reviewed and accepted”, “reviewed and explicitly rejected”, and “nobody has looked at this yet” are materially different facts — and an audit needs to be able to tell them apart.
Common misconception: Pending is not the same as uncheckedBecause Pending sounds provisional, it’s tempting to assume it doesn’t count toward completion. In fact, an item accepted conditionally is treated the same as a fully checked item when a workflow gate evaluates whether mandatory items are satisfied. If your process needs conditional acceptances to be visibly flagged for later follow-up even though they pass the gate, that follow-up has to happen through the note field or a separate review step — the gate itself won’t distinguish OK from Pending.
Pending depends on a feature togglePending corresponds to the underlying “Conditional” result state, which is only offered to users when the nextedy.checklist.conditional_enabled configuration property is set to true — it defaults to false, so a fresh installation does not show Pending as an option until an administrator enables it. See Configuration Property Hierarchy for where this toggle fits among other checklist-wide properties, and Icon, Feature-Toggle, and Baseline Properties for the full reference entry, including the companion conditional_sign icon property.
There is also a separate, non-actionable row type used for annotations rather than review steps: an Information entry (stored char i) that carries guidance text but is excluded from every count and completion calculation. Think of it as a section header or a comment embedded in the checklist rather than a thing to check — it never blocks a mandatory-item gate and never appears in progress statistics, because it isn’t a decision anyone needs to make. For example, a checklist with two Information rows (“Section: Code Quality” and “Section: Documentation”) plus three actionable rows (one OK, one Empty, one Pending) counts only those three actionable rows toward completion — the two Information rows are excluded entirely.

​
Mandatory vs. “all checked”: two different gates

Two related but distinct questions get asked of a checklist, and conflating them is a frequent source of confusion when setting up workflow gates:
  • Is every mandatory item checked? — satisfied when all items flagged mandatory hold a checked-equivalent result (OK or Pending).
  • Is every item checked, mandatory or not? — a stricter requirement that only passes when nothing is left in NOK or Empty, regardless of the mandatory flag.
An administrator-level configuration property can force the stricter “all items” behavior even for a checklist that has no items individually flagged mandatory — effectively saying “treat this entire checklist as if every row were mandatory.” Which of the two gates is in effect determines what a reviewer is actually required to resolve before a transition becomes available. See Workflow Gates: Definition of Done and Definition of Ready for how these two evaluations map onto specific workflow functions and conditions.

​
The text syntax: why raw field content matters

Because a checklist is ultimately stored as text in a custom field, that text has a syntax — and understanding it explains why hand-editing a checklist field directly, or letting some other integration write to it, can silently corrupt the checklist:
  • Each item is one line that starts with its result state in square brackets — [_] Empty, [X] OK, [O] NOK, [+] Pending, [i] Information — followed by a tab and then the label.
  • A ! placed immediately after the closing bracket (before the tab) marks the item mandatory, e.g. [X]!⇥Label.
  • A leading / marks a description line, attached to the item above it.
  • A leading > marks a note line, attached to the item above it.
(The separator between the bracketed state and the label is a literal tab; it is shown as spaces above for readability.)
This is why field type mattersChecklist fields are set up as plain multi-line text, not rich text, precisely so this syntax round-trips reliably. When a checklist field’s type gets changed to rich text underneath it — which has been observed as a side effect of using certain built-in Polarion work item templates — the syntax can be mangled and items can appear duplicated. If you see duplicated checklist items right after a work item is created from a template, this text-syntax dependency is the place to start investigating; see Templates for the documented workaround.

​
Where items come from: manual entry vs. templates

An item’s fromTemplate flag records whether it arrived via a checklist template or was typed directly into this specific instance. This isn’t just metadata — it’s the hook that makes template-driven updates possible. When a checklist is re-parsed against its template, matching items are updated in place by identifier rather than duplicated, which is what allows a template author to add or reword a review step centrally and have it reflected everywhere the template is referenced, without wiping out notes or results reviewers have already recorded on other, unrelated items.
Template edits reach existing itemsOn a template-driven merge, an item’s label, mandatory flag, and description are refreshed from the template while only the recorded result is preserved. So editing a template to change which items are mandatory (or to reword an item) does propagate to already-existing checklists the next time each one is parsed — you can rely on template edits to retroactively change mandatory flags and labels.

​
Building the mental model

The pattern to hold onto: a checklist item is a small bundle of independent facts (label, result, mandatory, description, note, origin), the result states exist because binary checked/unchecked can’t represent “reviewed and rejected” or “accepted conditionally” versus “not yet reviewed,” and the whole structure is serialized to a specific text syntax that both the rendering UI and any workflow logic depend on being well-formed. Once that clicks, the behavior of workflow gates, template merges, and baseline comparisons (covered in Workflow Gates: Definition of Done and Definition of Ready, Templates, and Baseline Tracking) follows naturally from this underlying data model rather than needing to be memorized as separate rules. For a broader orientation to how these pieces fit into the product as a whole, see What Is Nextedy Checklist. For hands-on setup instead of concepts, start with Getting Started.
Last modified on August 31, 2026