> ## Documentation Index > Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt > Use this file to discover all available pages before exploring further. # Checklist, ChecklistItem, and CheckItemResult > Reference for the checklist data model classes returned by, and passed to, the checklist service API. export const LastReviewed = ({date}) => { if (!date) return null; const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" }); return

Last reviewed on {formatted}

; }; Reference for the checklist data model classes returned by, and passed to, the checklist service API. Checklist contains many ChecklistItem entries; each item's result links to a CheckItemResult value ## 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` | 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 | Documented as counting mandatory active items that are checked, but flagged as buggy/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 statistics** Any 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/undocumented** `getCheckedMandatoryCount()` is flagged internally as 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 application** The exact message-format syntax (e.g. positional `{0}`-style placeholders vs named tokens) is not shown in the gathered context — confirm the literal template syntax in the application 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 stays authoritative — **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 items** If 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. (In the source, the commented-out line `//existing.mandatory = item.mandatory` sits in the *stored → template* direction, so disabling it is what makes the template's mandatory flag win, not the object's.) ## 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 parameter** Source-level evidence confirms `setChecked` 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](/checklist/guides/item-notes) for the UI. | Assigning a note to a checklist item The **Reply** icon is used to add a note to an item, provided the checklist is editable: Using the Reply icon to add a note ## 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](/checklist/reference/configuration/appearance-and-feature-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 constants** `CheckItemResult` has five constants: `NONE`, `CHECKED`, `REJECTED`, `CONDITIONAL`, `INFORMATION` (confirmed directly from `CheckItemResult.java`). Other product material describes five UI-facing result states (`OK`, `NOK`, `N/A`, `Pending`, `Empty`) — a plausible reading is `Checked`→OK, `Rejected`→NOK, `None`→N/A/Empty, `Conditional`→Pending, but this exact UI-label-to-enum-constant mapping is not spelled out verbatim in any single source and should be confirmed in the running application before publishing it as authoritative end-user terminology. ## 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 (confirmed directly from `Checklist.toText()`/`ChecklistService.parseLine()`): * 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. ```text theme={null} [X]!Review requirements traceability /This item verifies all requirements have upstream links >Checked against baseline REQ-2024-03 [_]Sign off from safety engineer ``` **Not structured data** Because 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. ## See also * [IChecklistService and Velocity Rendering API](/checklist/reference/api-service) — the service that parses text into these objects and stores them back. * [Summary Field Reference](/checklist/reference/summary-field) — how `Checklist` counts feed into the `_summary` custom field. **KB Articles** * IChecklistService API Documentation * Checklist workflow functions and conditions * Assign notes to checklist items **Support Tickets** * [#6706](https://support.nextedy.com/helpdesk/tickets/6706) * [#187](https://support.nextedy.com/helpdesk/tickets/187) * [#51](https://support.nextedy.com/helpdesk/tickets/51) **Source Code** * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistFormExtension.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/Checklist.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistItem.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/CheckItemResult.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistService.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/IChecklistService.java`