> ## 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. # IChecklistService API > The Checklist service API provides programmatic access to checklist operations on work items, documents, test runs, and plans. 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}

; }; diagram ## Service Methods The Checklist service exposes the following operations for working with checklists across all supported Polarion object types. ### parse Reads and parses checklist data from a custom field on a Polarion object. Returns a `Checklist` object containing all checklist items, their states, and metadata. If a template is configured, the parsed checklist merges template items automatically. | Parameter | Type | Description | | ---------- | ---------------- | ----------------------------------------------------- | | `workItem` | Work item object | The Polarion work item containing the checklist field | | `module` | Document object | The Polarion LiveDoc containing the checklist field | | `testRun` | Test run object | The Polarion test run containing the checklist field | | `plan` | Plan object | The Polarion plan containing the checklist field | | `field` | `String` | The custom field ID that stores the checklist data | **Supported object types:** work items, documents (LiveDocs), test runs, plans. **Returns:** A Checklist object with all items and their current states. When you call `parse()`, the service automatically merges items from a configured template into the checklist. You can control this behavior with the `nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate` configuration property. Template merging can also be disabled after resolution using `nextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved`. See [Configuration Properties](/checklist/reference/configuration-properties) for details. ### store Saves checklist data back to a custom field on a Polarion object. You can pass either a Checklist object or raw string data. | Parameter | Type | Description | | ----------- | ---------------- | ---------------------------------------------------------------- | | `checklist` | Checklist object | The checklist data to save | | `data` | `String` | Raw checklist data as a string (alternative to Checklist object) | | `workItem` | Work item object | The target work item | | `module` | Document object | The target LiveDoc | | `field` | `String` | The custom field ID to write to | **Supported object types:** work items, documents (LiveDocs). The `store` method writes directly to the custom field. Make sure you call `save()` on the Polarion object afterward to persist the change to the repository. ### reset Resets a checklist field back to its configured template state, discarding all user changes. This is the same operation that the `ChecklistResetToTemplate` workflow function performs. | Parameter | Type | Description | | ---------- | ---------------- | -------------------------------------- | | `workItem` | Work item object | The work item whose checklist to reset | | `module` | Document object | The document whose checklist to reset | | `field` | `String` | The custom field ID to reset | **Supported object types:** work items, documents (LiveDocs). ### applyTemplate Applies the configured template to a checklist field. Unlike `reset`, this merges template items into the existing checklist rather than replacing it entirely. | Parameter | Type | Description | | ---------- | ---------------- | -------------------------------------------- | | `workItem` | Work item object | The work item to apply the template to | | `module` | Document object | The document to apply the template to | | `field` | `String` | The custom field ID to apply the template to | **Supported object types:** work items, documents (LiveDocs). Use `reset` when you want to discard all user changes and return to a clean template state. Use `applyTemplate` when you want to add missing template items into an existing checklist without removing user-added items. ### getChecklistConf Retrieves the resolved configuration for a specific checklist field on a Polarion object. The returned configuration reflects the full [4-level property hierarchy](/checklist/reference/configuration-properties) (global, type-specific, field-specific, type+field-specific). | Parameter | Type | Description | | ---------- | ---------------- | ------------------------------------------ | | `workItem` | Work item object | The work item to resolve configuration for | | `module` | Document object | The document to resolve configuration for | | `field` | `String` | The custom field ID | **Returns:** The resolved checklist configuration object. ### getChecklistsIdsForSummary Returns the list of checklist field IDs that contribute to the summary field for a given Polarion object. Use this to determine which checklists are aggregated in summary reporting. | Parameter | Type | Description | | ---------- | ---------------- | ---------------------- | | `workItem` | Work item object | The work item to query | | `module` | Document object | The document to query | **Returns:** An array of custom field ID strings. ### getDocumentChecklistView Returns a builder object for rendering checklist widgets in documents and work items. The builder supports interactive editing mode and PDF export mode. **Returns:** A document checklist view builder. *** ## Checklist Object The Checklist object represents a parsed checklist with all its items and provides methods for querying checklist state. ### Constructor | Parameter | Type | Description | | ---------------------- | -------- | --------------------------------------------- | | `summaryMessageFormat` | `String` | Format string for generating the summary text | ### Query Methods | Method | Return Type | Description | | ------------------------------ | ----------------------------- | ------------------------------------------------------------ | | `getItems()` | Collection of checklist items | Returns all checklist items | | `isAllChecked()` | `boolean` | Returns `true` if every item has result state OK | | `isMandatoryChecked()` | `boolean` | Returns `true` if all mandatory items have result state OK | | `getCheckedCount()` | `int` | Number of items with result state OK | | `getRejectedCount()` | `int` | Number of items with result state NOK | | `getNACount()` | `int` | Number of items with result state N/A | | `getUncheckedCount()` | `int` | Number of items with result state Empty or Pending | | `getUncheckedMandatoryCount()` | `int` | Number of mandatory items not yet checked | | `getMandatoryCount()` | `int` | Total number of mandatory items | | `getCheckedMandatoryCount()` | `int` | Number of mandatory items with result state OK | | `getAllCount()` | `int` | Total number of checklist items | | `getSummaryText()` | `String` | Formatted summary text based on the summary message format | | `toText()` | `Text` | Converts the checklist to a Polarion Text object for storage | ### Mutation Methods | Method | Return Type | Description | | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | `mergeItemIn(item)` | Checklist item | Merges a checklist item into the list. If an item with the same ID exists, it is updated; otherwise, the item is appended | | `uncheckAll()` | `void` | Resets all items to the Empty result state | To count rejected (NOK) items, use `getRejectedCount()`. There are no built-in workflow conditions that gate on rejected item counts. You can implement custom workflow conditions using this method through the API. See the [Workflow Functions and Conditions](/checklist/reference/workflow-functions) reference for the built-in conditions available. *** ## Checklist Item Object Each checklist item represents a single entry in a checklist with its result state, label, and metadata. ### Properties | Property | Type | Default | Description | | -------------- | ----------------- | --------------- | ----------------------------------------------------- | | `result` | Result state enum | `Empty` | Current result state: OK, NOK, N/A, Pending, or Empty | | `checked` | `boolean` | `false` | Whether the item is checked (result state is OK) | | `mandatory` | `boolean` | `false` | Whether the item is a mandatory item | | `fromTemplate` | `boolean` | `false` | Whether the item originated from a template | | `label` | `String` | `""` | Display text for the checklist item | | `id` | `String` | See application | Unique identifier for the item | | `note` | `String` | `""` | Optional note text attached to the item | | `description` | `String` | `""` | Optional extended description for the item | ### Methods | Method | Description | | ---------------------------------------------------- | ---------------------------------------- | | `getResult()` / `setResult(result)` | Get or set the result state | | `isChecked()` / `setChecked(checked)` | Get or set the checked status | | `isMandatory()` / `setMandatory(mandatory)` | Get or set whether the item is mandatory | | `isFromTemplate()` / `setFromTemplate(fromTemplate)` | Get or set the template origin flag | | `getLabel()` / `setLabel(label)` | Get or set the item label | | `getId()` / `setId(id)` | Get or set the item identifier | | `getNote()` / `setNote(note)` | Get or set the item note | | `getDescription()` / `setDescription(description)` | Get or set the item description | *** ## Result State Enum The result state enum defines the possible states for each checklist item. | Value | Character | Label | Description | | ------- | --------- | -------- | ----------------------------- | | `Empty` | `_` | None | Item has not been evaluated | | `OK` | `X` | Checked | Item has passed / is complete | | `NOK` | `O` | Rejected | Item has failed / is rejected | The N/A and Pending result states are supported in the UI but the enum values shown above reflect the core code states. The full 5-state model (OK, NOK, N/A, Pending, Empty) may map to these base enum values with additional UI-level handling. ### Enum Methods | Method | Return Type | Description | | ----------------------- | ------------ | -------------------------------------------------------------- | | `getCharacter()` | `String` | Returns the single-character representation (`_`, `X`, or `O`) | | `getLabel()` | `String` | Returns the human-readable label | | `equalsToString(value)` | `boolean` | Compares the enum value against a string | | `isChecked()` | `boolean` | Returns `true` if the state represents a checked item | | `parse(str)` | Result state | Parses a string into the corresponding result state | *** ## Document Checklist View Builder The document checklist view builder renders checklist widgets in LiveDocs and work items with support for interactive editing and PDF export. ### Builder Methods | Method | Parameter | Description | | -------------------- | ---------------- | -------------------------------------------------------------------------- | | `document(module)` | Document object | Sets the LiveDoc context for the checklist view | | `workitem(workItem)` | Work item object | Sets the work item context for the checklist view | | `checklist(fieldId)` | `String` | Specifies the custom field ID containing the checklist data. **Required.** | | `title(heading)` | `String` | Adds a heading above the checklist widget | | `hideInPdf()` | None | Hides the checklist in PDF exports | | `view(context)` | Object | Sets the rendering context for PDF detection | | `render()` | None | Generates the final HTML output. **Call last.** | The custom field specified in `checklist()` must be of type **Text (multi-line plain text)**. Using any other field type causes a validation error with a message explaining the type mismatch. ### Test Run and Plan Checklist View A separate view builder handles test runs and plans with the same builder pattern. | Method | Parameter | Description | | -------------------- | --------------- | ----------------------------------------------- | | `testRun(testRun)` | Test run object | Sets the test run context | | `plan(plan)` | Plan object | Sets the plan context | | `checklist(fieldId)` | `String` | Specifies the custom field ID. **Required.** | | `title(heading)` | `String` | Adds a heading above the checklist widget | | `hideInPdf()` | None | Hides the checklist in PDF exports | | `render()` | None | Generates the final HTML output. **Call last.** | *** ## Accessing the API ### From Velocity (Wiki Pages and Live Reports) The Checklist service is available as `$checklistService` in Velocity templates on wiki pages and live reports. **Example: Display checklist items on a wiki page** ```velocity theme={null} #set( $wi = $trackerService.queryWorkItems("project.id:myproject AND id:WI-101", "id").iterator().next() ) #set( $cList = $checklistService.parse( $wi, "dor") ) #foreach($i in $cList.getItems()) #end ``` **Example: Display checklist summary counts** ```velocity theme={null} #set( $wi = $trackerService.queryWorkItems("project.id:myproject AND id:WI-101", "id").iterator().next() ) #set( $cList = $checklistService.parse( $wi, "dod") ) Checked: $cList.getCheckedCount() / $cList.getAllCount() Mandatory checked: $cList.getCheckedMandatoryCount() / $cList.getMandatoryCount() Rejected: $cList.getRejectedCount() ``` ### From Java (Workflow Functions and Conditions) Access the Checklist service through the Polarion platform service registry. **Example: Uncheck all items in a workflow function** ```java theme={null} // Obtain the service from the platform registry IChecklistService checklistService = PlatformContext.getPlatform().lookupService(IChecklistService.class); // In a workflow function execute() method: String fieldId = arguments.getAsString("checklist"); String[] fields = fieldId.split(","); for (int i = 0; i < fields.length; i++) { IWorkItem wi = context.getWorkItem(); Checklist chl = checklistService.parse(wi, fields[i]); chl.uncheckAll(); checklistService.store(chl, wi, fields[i]); } ``` ### From JavaScript / Nashorn (Scripted Conditions and Hooks) Nashorn-based access to the Checklist service is supported. Use the platform registry service pattern to obtain the service instance in scripted workflow conditions and save hooks. ```javascript theme={null} // Access the service via the platform registry var checklistService = PlatformContext.getPlatform() .getRegistry().getService(); ``` You can access the Checklist service from scripted workflow conditions, save hooks, and other Nashorn-based integration points in Polarion. The platform registry pattern is the standard way to obtain any Polarion extension service from script code. *** ## Common API Patterns ### Counting Rejected Items for Review Workflows Rejected (NOK) item counts are not available through built-in workflow conditions. Use the API to implement custom counting logic: ```velocity theme={null} #set( $cList = $checklistService.parse( $wi, "review") ) #set( $rejectedCount = $cList.getRejectedCount() ) #if( $rejectedCount > 0 ) WARNING: $rejectedCount item(s) rejected in review checklist. #end ``` ### Checking Mandatory Item Completion ```velocity theme={null} #set( $cList = $checklistService.parse( $wi, "dod") ) #if( $cList.isMandatoryChecked() ) All mandatory items are complete. #else $cList.getUncheckedMandatoryCount() mandatory item(s) remaining. #end ``` ### Working with Multiple Checklists ```velocity theme={null} #set( $summaryFields = $checklistService.getChecklistsIdsForSummary( $wi ) ) #foreach( $fieldId in $summaryFields ) #set( $cList = $checklistService.parse( $wi, $fieldId ) ) Checklist "$fieldId": $cList.getCheckedCount() / $cList.getAllCount() #end ``` *** ## Related Pages * [Configuration Properties](/checklist/reference/configuration-properties) for template and merge configuration * [Workflow Functions and Conditions](/checklist/reference/workflow-functions) for built-in workflow integrations * [Polarion Version Support](/overview/resources/polarion-version-support) for supported Polarion versions * [Compatibility](/checklist/reference/compatibility) for supported object types and the feature matrix