The Five Result States
A checklist item always exists in exactly one of five result states. Think of them as traffic signals: some mean “go ahead,” some mean “stop,” and one means the light has not been turned on yet.| State | Storage Code | Icon | Meaning | Counts as Checked? |
|---|---|---|---|---|
| Checked | [X] | :fontawesome-regular-check-square: | The item is fully completed | Yes |
| Conditional | [+] | :fontawesome-regular-plus-square: | The item is completed with conditions | Yes |
| Rejected | [O] | :fontawesome-regular-minus-square: | The item is explicitly rejected or not applicable | No |
| Information | [i] | The item is informational only — no action needed | Excluded from counting | |
| None | [_] | :fontawesome-regular-square: | No decision has been made yet (default) | No |
Checked
The most common completion state. When a user marks an item as Checked ([X]), Checklist counts it toward the completion total. Both workflow conditions and summary fields treat Checked items as “done.”
Conditional
The Conditional state ([+]) represents an item that is completed with caveats or open conditions. This is a critical design choice: Conditional counts as checked for all completion tracking and workflow validation. This means a workflow gate configured with ChecklistAllChecked or ChecklistMandatoryChecked treats Conditional identically to Checked.
The Conditional state is disabled by default. To make it available, set the configuration property
nextedy.checklist.conditional_enabled to true. When disabled, users see only Checked, Rejected, and None in the UI.Rejected
Rejected ([O]) is an explicit “no” — the user has actively decided this item does not apply or has failed. Rejected items do not count as checked. If a workflow condition requires all items to be checked, any Rejected item blocks the transition just like a None item would.
Information
Information items ([i]) are non-actionable. They exist to provide context, instructions, or section headers within a checklist. The system excludes Information items from all counting: they do not appear in checked counts, unchecked counts, or mandatory counts. This keeps your completion percentages accurate even when checklists include explanatory text.
None
None ([_]) is the default state for every new checklist item before a user interacts with it. It signals that no decision has been made. None items count as unchecked.
How States Drive Completion Counting
Checklist maintains several counters that other features consume. Understanding what each counter includes and excludes prevents surprises when you read a summary field or wonder why a workflow gate blocked a transition.| Counter | Includes | Excludes |
|---|---|---|
| Checked count | Checked, Conditional | None, Rejected, Information |
| Unchecked count | None, Rejected | Checked, Conditional, Information |
| Rejected count | Rejected only | All others |
| Mandatory count | All items flagged mandatory | Information items |
| Unchecked mandatory count | Mandatory items in None or Rejected state | Checked/Conditional mandatory items, Information items |
| Checked mandatory count | Mandatory items in Checked or Conditional state | Unchecked mandatory items, Information items |
The Mandatory Flag
Any checklist item can be marked as mandatory. The mandatory flag is orthogonal to result states — it does not change what state an item is in, but it changes how workflow conditions evaluate the checklist. When a workflow condition usesChecklistMandatoryChecked, it examines only items where the mandatory flag is set. If every mandatory item has a result state of Checked or Conditional, the condition passes. Non-mandatory items are ignored entirely.
There is also a configuration property nextedy.checklist.allMandatory that, when set to true, treats every item as mandatory regardless of individual flags. When allMandatory is enabled, ChecklistMandatoryChecked behaves identically to ChecklistAllChecked — both require every active item to be checked.
The allMandatory configuration property follows the Configuration Property Hierarchy, so you can enable it globally, per work item type, per field, or per type-and-field combination.
States in Workflow Validation
Workflow functions and conditions rely on the state model to make pass/fail decisions. Two patterns are most common: All-checked validation — used by theChecklistAllChecked condition and the ChecklistFailIfAnyUnchecked function. These require every active (non-Information) item to be in the Checked or Conditional state. A single None or Rejected item causes the validation to fail.
Mandatory-checked validation — used by the ChecklistMandatoryChecked condition and the ChecklistFailIfMandatoryUnchecked function. These examine only mandatory items and pass if all of them are Checked or Conditional. Non-mandatory items in any state are ignored.
Both patterns apply AND logic when multiple checklist fields are specified (comma-separated). Every listed field must independently pass for the overall validation to succeed.
For a deeper look at how these connect to Polarion workflows, see Workflow Integration.
States in the Summary Field
The summary field aggregates checklist counters into a single text string. The format is controlled by thesummaryMessageFormat configuration, which supports placeholders:
| Placeholder | Value |
|---|---|
{checked} | Count of Checked + Conditional items |
{unchecked} | Count of None + Rejected items |
{rejected} | Count of Rejected items |
{NA} | Count of None items |
{mandatory} | Total mandatory items |
{uncheckedMandatory} | Mandatory items not yet checked |
{checkedMandatory} | Mandatory items that are checked |
{all} | Total active items (excludes Information) |
Storage Format
Checklist items store their result state as single-character codes inside a custom field of type Text (multi-line plain text). The codes are:[X]— Checked[+]— Conditional[O]— Rejected[i]— Information[_]— None
The custom field that stores checklist data must be of type Text (multi-line plain text). Other field types will produce a validation error when Checklist attempts to render the widget.
Practical Implications
For process engineers: Design your checklists so that every item has a clear expected outcome. Use Information items for section headers or explanatory notes, and set mandatory flags on items that are true compliance gates. This separation ensures that summary fields and workflow conditions reflect actual process status. For Polarion administrators: The Conditional state adds flexibility for edge cases where an item is “done, but…” Enable it vianextedy.checklist.conditional_enabled only if your process genuinely needs the distinction. Leaving it disabled simplifies the UI to three actionable states (Checked, Rejected, None) plus Information.
For auditors: Baselines freeze checklist states at a point in time. Because each item carries an explicit result state, a baseline comparison reveals exactly which items changed state between revisions — not just whether the checklist “passed” or “failed.”
See Also
- Template System — how templates define items and their default states
- Configuration Property Hierarchy — how
allMandatory,conditional_enabled, and other properties are resolved - Workflow Integration — how workflow functions and conditions use checklist states for gate enforcement
Sources
Sources
KB Articles
- How to create checklist template?
- Checklist workflow functions and conditions
- Checklist configuration properties
ChecklistService.javaChecklist.javaChecklistSettings.javaCheckItemResult.javaDocumentChecklistView.java