Checklist, ChecklistItem, and CheckItemResult

Reference for the checklist data model classes returned by, and passed to, the checklist service API.

Checklist

Represents a checklist instance: an ordered collection of ChecklistItem entries, providing counting, merging, summary text, and export/reset behaviors.

Name	Type	Default	Description
`Checklist(String summaryMessageFormat)`	Constructor	n/a	Constructs a `Checklist` configured with a message-format template used to render its summary text.
`DATEFORMAT`	Public static constant (String)	`"yyyy-MM-dd"`	Fixed date format used when serializing checklist data to JSON.
`getItems()`	Method — returns `Collection<ChecklistItem>`	n/a	Returns all checklist items currently held, including `Information`-type items (the full, unfiltered set).
`getActiveItems()`	Method — returns stream of `ChecklistItem`	n/a	Returns items excluding those with an `INFORMATION` result. This is the basis for all counting/completion logic below.
`mergeItemIn(ChecklistItem item)`	Method — returns `ChecklistItem`	n/a	Adds a new item, or — if an item with the same id already exists — updates the existing item’s result to match the incoming item’s result instead of duplicating it.
`isMandatoryChecked()`	Method — returns `boolean`	n/a	`true` only if every mandatory active item has a checked result (`Checked` or `Conditional`).
`isAllChecked()`	Method — returns `boolean`	n/a	`true` only if every active item, mandatory or not, has a checked result.
`getCheckedCount()`	Method — returns `int`	n/a	Number of active items whose result is a checked state (`Checked` or `Conditional`).
`getRejectedCount()`	Method — returns `int`	n/a	Number of active items whose result is `REJECTED`.
`getNACount()`	Method — returns `int`	n/a	Number of active items whose result is `NONE` (shown as “NA” in the summary text).
`getUncheckedCount()`	Method — returns `int`	See application	Broader than `getNACount()` — includes all unchecked active items, not only those in `NONE` state.
`getUncheckedMandatoryCount()`	Method — returns `int`	See application	Count of mandatory active items not yet checked.
`getMandatoryCount()`	Method — returns `int`	See application	Count of active items marked mandatory.
`getCheckedMandatoryCount()`	Method — returns `int`	See application	Intended to count mandatory active items that are checked, but known to be buggy and undocumented — see warning below.
`getAllCount()`	Method — returns `int`	See application	Count of all active items.
`getSummaryText()`	Method — returns `String`	n/a	Renders the checklist’s summary text using the `summaryMessageFormat` template supplied to the constructor.
`toText()`	Method — returns `Text`	n/a	Exports the checklist as its underlying stored text representation.
`toJSON()`	Method — returns `String`	n/a	Serializes all items (via `getItems()`, the unfiltered set) to a JSON string using `DATEFORMAT` for any dates. Used internally when rendering checklist data into the form extension/Velocity widget.
`uncheckAll()`	Method — returns `void`	n/a	Clears the result of every item, returning the checklist to an unchecked state. Used by the `ChecklistUncheckAll` workflow function.

Information items are excluded from all statisticsAny item with an INFORMATION result is excluded from every counting method (getCheckedCount, getMandatoryCount, isAllChecked, etc.) because they are drawn from getActiveItems(), not getItems(). This explains why an informational row does not affect the completion count shown in the checklist form extension.

Known limitation — getCheckedMandatoryCount is buggy/undocumentedgetCheckedMandatoryCount() is known to be buggy and undocumented. Do not rely on it for accurate counts in custom scripting or reporting; use getMandatoryCount() and getUncheckedMandatoryCount() together (mandatory total minus unchecked-mandatory) if a checked-mandatory count is needed.

`summaryMessageFormat` placeholder tokens

The message-format template passed to the Checklist constructor supports these placeholder tokens:

Token	Description
`checked`	Number of checked (active) items
`unchecked`	Number of unchecked (active) items
`rejected`	Number of rejected items
`NA`	Number of items in `NONE` state
`uncheckedMandatory`	Number of unchecked mandatory items
`mandatory`	Total number of mandatory items
`checkedMandatory`	Number of checked mandatory items
`all`	Total number of active items

Verify in applicationThe exact message-format syntax (e.g. positional {0}-style placeholders vs named tokens) is not confirmed — check the literal template syntax in your Polarion instance before authoring a custom summaryMessageFormat.

`mergeItemIn` — template re-sync behavior

Merging happens on every parse: the checklist is seeded from the template first (each item’s label, mandatory flag, and description come from the template), and then the stored field content is merged in, carrying over only the result of each matching item (matched by id). The practical consequence is that the template wins — label, mandatory flag, and description always refresh from the current template on re-parse, while a reviewer’s recorded result is preserved.

Template changes propagate to existing itemsIf a template’s mandatory flag, label, or description changes after items already exist on an object’s checklist, those changes do reach the existing items the next time the checklist is parsed — only the item’s result is kept from the stored content. The template’s mandatory flag wins over the one stored on the object.

ChecklistItem

Represents a single item (row) in a checklist: its label, result state, mandatory flag, description/note text, and template origin.

Name	Type	Default	Description
`ChecklistItem()`	Constructor	n/a	Default constructor.
`ChecklistItem(String label)`	Constructor	n/a	Constructs an item with the given label. The item’s `id` defaults to the same value as `label` when constructed this way.
`getResult()` / `setResult(CheckItemResult result)`	Accessor pair — `CheckItemResult`	`CheckItemResult.NONE`	Gets or sets the item’s current result. `getResult()` defaults to `NONE` if no result has been set.
`isChecked()`	Method — returns `boolean`	n/a	`true` if the item’s result is a checked state (`Checked` or `Conditional`); `false` if the result is `null` or any other state. An item with no result set is treated as unchecked.
`setChecked(boolean checked)`	Method — returns `void`	n/a	Forcibly marks the item’s result as `CHECKED`.
`isMandatory()` / `setMandatory(boolean mandatory)`	Accessor pair — `boolean`	See application	Gets or sets whether the item must be checked before the checklist (or a mandatory-gated workflow) is considered complete.
`isFromTemplate()` / `setFromTemplate(boolean fromTemplate)`	Accessor pair — `boolean`	See application	Gets or sets whether the item originated from a checklist template versus being added manually.
`getLabel()` / `setLabel(String label)`	Accessor pair — `String`	n/a	Gets or sets the item’s display text.
`getId()` / `setId(String id)`	Accessor pair — `String`	Same as `label` when using the single-arg constructor	Gets or sets the item’s unique identifier, used as the merge key in `Checklist.mergeItemIn`.
`getNote()` / `setNote(String note)`	Accessor pair — `String`	n/a	Gets or sets a free-text note attached to the item — reviewer-editable, rendered with a leading `>` in the underlying text format.
`getDescription()` / `setDescription(String description)`	Accessor pair — `String`	n/a	Gets or sets static, template-level guidance text for the item — rendered with a leading `/` in the underlying text format, distinct from the reviewer-editable note.

Known limitation — setChecked(boolean) ignores its parametersetChecked always sets the result to CHECKED regardless of the boolean value passed. There is no “uncheck a single item” behavior via this method — passing false still checks the item. To uncheck items, use Checklist.uncheckAll() or set the result explicitly via setResult(CheckItemResult.NONE).

Note vs. description

Field	Rendered with	Set by	Purpose
`description`	Leading `/`	Template author	Static guidance text explaining what the item means.
`note`	Leading `>`	Reviewer, at check time	Free-text detail added when checking/rejecting an item — see Assign notes to checklist items for the UI.

The Reply icon is used to add a note to an item, provided the checklist is editable:

CheckItemResult

An enum representing the possible result states of a ChecklistItem.

Name	Type	Default	Description
`NONE`	Enum constant	—	Character `_`, label `"None"`. The default/unset state.
`CHECKED`	Enum constant	—	Character `X`, label `"Checked"`.
`REJECTED`	Enum constant	—	Character `O`, label `"Rejected"`.
`CONDITIONAL`	Enum constant	—	Character `+`, label `"Conditional"`. Counts as a checked state everywhere `isChecked()` is evaluated (see `Checklist.isMandatoryChecked()`, `isAllChecked()`, `getCheckedCount()` above). Only reachable in the UI when `nextedy.checklist.conditional_enabled=true` (see Icon, Feature-Toggle, and Baseline Properties).
`INFORMATION`	Enum constant	—	Character `i`, label `"Information"`. Marks a non-actionable annotation row; `Checklist.getActiveItems()` filters out items in this state, which is why they are excluded from every counting method (see the note above `getActiveItems()`).
`getCharacter()`	Method — returns `String`	n/a	Returns the single-character code (`_`, `X`, `O`, `+`, or `i`) used in the underlying stored text representation.
`getLabel()`	Method — returns `String`	n/a	Returns the human-readable label (`"None"`, `"Checked"`, `"Rejected"`, `"Conditional"`, or `"Information"`).
`equalsToString(String v)`	Method — returns `boolean`	n/a	Compares the enum’s `label` (not its character code) against a given string for an exact match.
`isChecked()`	Method — returns `boolean`	n/a	`true` for `CHECKED` or `CONDITIONAL`.
`parse(String str)`	Static method — returns `CheckItemResult`	n/a	Matches a bracketed prefix (`[X]`, `[O]`, `[+]`, `[i]`) at the start of the string to `CHECKED`, `REJECTED`, `CONDITIONAL`, or `INFORMATION` respectively; returns `NONE` for any string that doesn’t start with one of those four prefixes (including `[_]` and unrecognized input).

UI-facing state names vs. enum constantsCheckItemResult has five constants, and each corresponds to one state a reader sees in the rendered checklist: NONE is Empty, CHECKED is OK, REJECTED is NOK, CONDITIONAL is Pending (offered only when the conditional state is enabled), and INFORMATION is the non-selectable Information row that carries no result and is excluded from completion counts. The four selectable states are the full set — there is no “not applicable” state.

Underlying text storage format

Checklist state is persisted as plain text in the underlying custom field (not as structured JSON), using this line-based syntax:

Each item line starts with its result character in square brackets — [X], [O], [+], [i], or [_] for CHECKED, REJECTED, CONDITIONAL, INFORMATION, or NONE respectively.
An optional ! immediately follows the closing bracket (before the tab) to mark the item mandatory — for example [X]!, not a trailing ! at the end of the line.
A tab separates the bracketed result/mandatory marker from the item label text.
A leading / (on its own line, indented under the item) marks a description line.
A leading > (on its own line, indented under the item) marks a note line.

[X]!<TAB>Review requirements traceability
   /This item verifies all requirements have upstream links
        >Checked against baseline REQ-2024-03
[_]<TAB>Sign off from safety engineer

Not structured dataBecause checklist state is plain text in a rich-text/text field, any external tool reading the field directly (rather than through IChecklistService.parse) must replicate this exact syntax, including the brackets around the result character, the mandatory marker’s position immediately after the bracket (not at the end of the line), and the tab separator.

FAQ

Checklist, ChecklistItem, and CheckItemResult

Checklist

`summaryMessageFormat` placeholder tokens

`mergeItemIn` — template re-sync behavior

ChecklistItem

Note vs. description

CheckItemResult

Underlying text storage format

See also

​Checklist

​summaryMessageFormat placeholder tokens

​mergeItemIn — template re-sync behavior

​ChecklistItem

​Note vs. description

​CheckItemResult

​Underlying text storage format

​See also

Checklist

`summaryMessageFormat` placeholder tokens

`mergeItemIn` — template re-sync behavior

ChecklistItem

Note vs. description

CheckItemResult

Underlying text storage format

See also