> ## 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 and Velocity Rendering API > Reference for the checklist service API surface — the entry point for reading, storing, resetting, and applying templates to checklists from Java workflow functions/conditions and from Velocity (LiveReport / wiki pages). 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 service API surface — the entry point for reading, storing, resetting, and applying templates to checklists from Java workflow functions/conditions and from Velocity (LiveReport / wiki pages). **Verify in application** This page documents the API surface as captured in the product's API documentation and source. Method behavior for edge cases not explicitly described below should be verified in the application. ## Overview IChecklistService accessed via a Java PlatformContext lookup from workflow functions/conditions, and via the Velocity $checklistService binding from LiveReport/wiki pages and the checklist form extension ## Accessing the service ### From Java (workflow functions and conditions) ```java theme={null} private static IChecklistService checklistService = PlatformContext.getPlatform().lookupService(IChecklistService.class); ``` This is the pattern used internally by the `ChecklistUncheckAll` workflow function. Use the same lookup in custom workflow `IFunction` or `ICondition` implementations that need programmatic access to checklist state. ### From Velocity (LiveReport / wiki pages) The service is exposed directly in the Velocity context as `$checklistService` — no lookup call is required. ```velocity theme={null} #set( $wi = $trackerService.queryWorkItems("project.id:chldemo AND id:EL-191", "id").iterator().next() ) #set( $cList = $checklistService.parse( $wi, "dor")) #foreach($i in $cList.getItems()) #end ``` IChecklistService API documentation illustration **LiveReport table fields and querying via Lucene are not confirmed** Ticket evidence shows users have asked to add checklist progress (for example `1/7 completed`) directly as a LiveReport table field, or to query per-item checked-state via a Lucene-style query, and found no direct way to do so. The Velocity access pattern above (parsing the checklist field manually inside a script block) is the confirmed mechanism. Whether checklists can be surfaced as a native LiveReport table column is **not currently supported** based on available evidence — treat it as a limitation until confirmed otherwise. ## Method reference — IChecklistService All methods below are declared on the `IChecklistService` interface. Overloads exist per target object type: work item, document (module), test run, and plan — although not every method has an overload for every type (see notes). | Name | Type | Default | Description | | -------------------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `parse` | Method — returns `Checklist` | n/a | Parses the checklist markup stored in a field into a `Checklist` object. Overloaded for `IWorkItem`, `WorkItem`, `IModule`, `ITestRun`, and `IPlan` targets. | | `store` | Method — returns `void` | n/a | Persists a `Checklist` object, or a raw checklist data `String`, back into a field. Overloaded across `IModule`, `IWorkItem`, `WorkItem`, `ITestRun`, and `IPlan`. | | `reset` | Method — returns `void` | n/a | Resets/clears the checklist stored on a work item, module, test run, or plan field. | | `applyTempate` | Method — returns `void` | n/a | Re-syncs a field against its configured checklist template and immediately saves the result (parse-then-store; see the merge-semantics note below — existing progress is preserved, not discarded). **Note the exact method spelling `applyTempate`** (not `applyTemplate`) — this is how it appears in the interface and must be called exactly as spelled. | | `getChecklistConf` | Method — returns `ChecklistConf` | n/a | Retrieves the configuration object governing the checklist's behavior/appearance for a given field. Overloaded for `WorkItem`, `IWorkItem`, `IModule`, `ITestRun`, and `IPlan`. | | `getChecklistsIdsForSummary` | Method — returns `String[]` | n/a | Returns the checklist field IDs configured for summary computation on the given target, via `nextedy.checklist._TYPEID_.checklistsIdsForSummary` (see [Summary Field Reference](/checklist/reference/summary-field)). Overloaded for `IWorkItem`, `IModule`, `ITestRun`, and `IPlan`. | | `getChecklistsIdsForTypeChanges` | Method — returns `String[]` | n/a | Returns the checklist IDs relevant when a work item's type changes. Available only for `IWorkItem` — no module/test run/plan overload. | | `getDocumentChecklistView` | Method — returns `DocumentChecklistView` | n/a | Returns a fluent Velocity-rendering builder scoped to a **document or work item**: chain `.document(IModule)` or `.workitem(IWorkItem)`, then `.checklist(String)`, optionally `.hideInPdf()`/`.title(String)`, then `.render()`. A LiveReport/wiki-page rendering path, distinct from the checklist form extension (which renders directly on the work item form and does not go through this builder). | | `getChecklistView` | Method — returns `ChecklistView` | n/a | Returns a fluent Velocity-rendering builder scoped to a **test run or plan**: chain `.testRun(ITestRun)` or `.plan(IPlan)`, then `.checklist(String)`, optionally `.hideInPdf()`/`.title(String)`, then `.render()` — e.g. `$checklistService.getChecklistView().testRun($testRun).checklist("testDone").render()` on a Test Run/Plan Report page. Also a LiveReport/wiki-page rendering path, distinct from the checklist form extension. | | `getDocumentBaselinesView` | Method — returns `BaselinesView` | n/a | Returns the view used to display checklist baselines (historical/revision comparisons) within a document. | ### `parse` — full signature list ```java theme={null} Checklist parse(IWorkItem workItem, String field); Checklist parse(WorkItem workItem, String field); Checklist parse(IModule module, String field); Checklist parse(ITestRun testRun, String field); Checklist parse(IPlan plan, String field); ``` **Test run and plan overloads confirmed directly in the interface source** The published IChecklistService API article lists only the `IWorkItem` / `WorkItem` / `IModule` overloads of `parse`. Confirmed directly from `IChecklistService.java`: `parse` also exists for `ITestRun` and `IPlan` targets, each merging in the target's own template (test run template via the test run's template test run; plan template via the plan's template plan). The `field` parameter identifies which field on the target stores the checklist markup. ### `store` — full signature list ```java theme={null} void store(Checklist checklist, WorkItem workItem, String field); void store(Checklist checklist, IWorkItem workItem, String field); void store(Checklist checklist, IModule module, String field); void store(Checklist checklist, ITestRun testRun, String field); void store(Checklist checklist, IPlan plan, String field); void store(String data, IModule module, String field); void store(String data, IWorkItem workItem, String field); void store(String data, ITestRun testRun, String field); void store(String data, IPlan plan, String field); ``` **Test run and plan overloads confirmed directly in the interface source** Confirmed directly from `IChecklistService.java`: both the `Checklist`-typed and raw-`String`-typed `store` overloads exist for `ITestRun` and `IPlan`, in addition to `IWorkItem`/`WorkItem`/`IModule`. ### `applyTempate` — full signature list ```java theme={null} void applyTempate( IWorkItem workItem, String field); void applyTempate( WorkItem workItem, String field); void applyTempate( IModule module, String field); void applyTempate( ITestRun testRun, String field); void applyTempate( IPlan plan, String field); ``` **Merge semantics confirmed — not destructive** Confirmed directly from `ChecklistService.java`: every `applyTempate` overload is implemented as `store(parse(target, field), target, field)` — it re-parses the field (which merges the template into the currently stored content, exactly like a normal `parse` call — see [Template Merge Behavior](/checklist/reference/configuration/template-properties)) and immediately persists the merged result. Calling `applyTempate` on a field that already has data does **not** discard existing progress: items matched by id keep their recorded result, while label/mandatory/description are refreshed from the template. This is different from `reset` below, which discards all existing content unconditionally. ### `reset` — full signature list ```java theme={null} void reset( IWorkItem workItem, String field); void reset( WorkItem workItem, String field); void reset( IModule module, String field); void reset( ITestRun testRun, String field); void reset( IPlan plan, String field); ``` **Destructive action** Resetting a checklist re-parses the template content and saves it, discarding any current checklist progress on that field. There is no undo. ### `getChecklistConf` — full signature list ```java theme={null} ChecklistConf getChecklistConf(WorkItem workItem, String field); ChecklistConf getChecklistConf(IWorkItem workItem, String field); ChecklistConf getChecklistConf(IModule module, String field); ChecklistConf getChecklistConf(ITestRun testRun, String field); ChecklistConf getChecklistConf(IPlan plan, String field); ``` **Test run and plan overloads confirmed directly in the interface source** Confirmed directly from `IChecklistService.java` and `ChecklistService.java`: `getChecklistConf` has dedicated `ITestRun` and `IPlan` overloads, each computing `readonly`/`adminPermission` from that target's own permission check (`testRun.can().modify()` / `plan.can().modify()`) rather than the work item path's license-authorization check. ## Worked example — Java workflow function The `ChecklistUncheckAll` workflow function demonstrates the full lookup → parse → mutate → store cycle. Its target resolution — `context.getTarget()` plus an `instanceof` branch per type — is the same pattern used by every checklist workflow function/condition (see [Workflow Functions and Conditions](/checklist/reference/workflow)): ```java theme={null} private static IChecklistService checklistService = PlatformContext.getPlatform().lookupService(IChecklistService.class); public void execute(ICallContext context, IArguments arguments) { String chlField = arguments.getAsString("checklist"); if (chlField == null) { throw new RuntimeException("checklist attribute missing for wf function: ChecklistUncheckAll "); } IWorkflowObject workflowObject = context.getTarget(); if (workflowObject instanceof IWorkItem) { IWorkItem wi = (IWorkItem) workflowObject; String[] fields = chlField.split(","); for (int i = 0; i < fields.length; i++) { Checklist chl = checklistService.parse(wi, fields[i]); chl.uncheckAll(); checklistService.store(chl, wi, fields[i]); } } if (workflowObject instanceof IModule) { IModule module = (IModule) workflowObject; String[] fields = chlField.split(","); for (int i = 0; i < fields.length; i++) { Checklist chl = checklistService.parse(module, fields[i]); chl.uncheckAll(); checklistService.store(chl, module, fields[i]); } } if (workflowObject instanceof ITestRun) { ITestRun testRun = (ITestRun) workflowObject; String[] fields = chlField.split(","); for (int i = 0; i < fields.length; i++) { Checklist chl = checklistService.parse(testRun, fields[i]); chl.uncheckAll(); checklistService.store(chl, testRun, fields[i]); } } } ``` **Work item, document, and test run — not plan** `ChecklistUncheckAll` (like the other workflow functions/conditions on the [Workflow Functions and Conditions](/checklist/reference/workflow) page) branches on `IWorkItem`, `IModule`, and `ITestRun` only — there is no `IPlan` branch, so it is not available as a workflow action on plan transitions. **Pattern to reuse in custom workflow functions** Ticket evidence confirms a similar pattern for a custom use case: call `checklistService.parse(wi, "dod")` to get a `Checklist` object, iterate `ChecklistItem.checked` and `ChecklistItem.label` on its items (for example to create follow-up tasks from checked items), then call `checklistService.reset()` on the work item or module when the checklist needs clearing as part of the same function. ## Worked example — Velocity on a LiveReport or wiki page ```velocity theme={null} #set( $wi = $trackerService.queryWorkItems("project.id:chldemo AND id:EL-191", "id").iterator().next() ) #set( $cList = $checklistService.parse( $wi, "dor")) #foreach($i in $cList.getItems()) #end ``` This queries a single work item, parses its `dor` checklist field, and renders each item's checked state, label, and note. ## Related rendering entry point — checklist form extension The checklist form extension (the form widget shown on a work item) is wired to `IChecklistService` internally: it calls `parse` to read the current checklist state, and `getChecklistConf` to read the configuration that controls how the widget behaves and renders. The form extension always reflects the current stored checklist state on render — it is a live read, not a cached snapshot. | Name | Type | Default | Description | | ------------------ | ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `checklistId` | Form-layout attribute (String) | See application | Identifies which checklist field on the work item the form extension renders. Required — omitting it produces the runtime error `Checklist ID not set for extension.` | | `checklistService` | Velocity context binding | n/a | The `IChecklistService` instance itself, exposed in the form extension's rendering context under the key `checklistService`, enabling the template to make further service calls (for example reset or apply-template) directly from the form template. | **Full extension-tag attributes documented in the setup guide** The full `` tag — including the `id` (extension implementation ID, e.g. `ChecklistFormExtension`) and `label` (display heading) attributes alongside `checklistId` — is documented with a worked example in [Set Up a Work Item Checklist](/checklist/guides/setup/work-items), not repeated here to avoid duplication. ## Known limitations * **LiveReport table field / column integration for checklist progress is not confirmed as supported.** Users have asked for a way to show progress (e.g., `1/7 completed`) as a LiveReport table field without writing a Velocity script; no such built-in field is evidenced in the gathered context. The Velocity scripting approach shown above is the confirmed workaround. * **Direct Lucene-style querying of individual checklist item checked-state is not confirmed as supported.** Per-item state must be read by parsing the field via `IChecklistService.parse` in a script, not via a query filter. * **Access to `IChecklistService` from scripted JavaScript workflow conditions is not confirmed.** Ticket evidence shows a user asking specifically whether the service can be reached from a JavaScript-based workflow condition (as opposed to VTL or Java). Only Java (via `PlatformContext.getPlatform().lookupService`) and Velocity (via `$checklistService`) access are confirmed by the gathered context. ## See also * [Checklist, ChecklistItem, and CheckItemResult](/checklist/reference/api-model) — the data model classes returned by and passed to this service. * [Summary Field Reference](/checklist/reference/summary-field) — how checklist state is surfaced into a queryable summary field, as an alternative to scripting. * [Workflow Functions and Conditions](/checklist/reference/workflow) — workflow-level gate enforcement built on top of this service. **KB Articles** * IChecklistService API Documentation * Assign notes to checklist items * How to create checklist template? **Support Tickets** * [#6706](https://support.nextedy.com/helpdesk/tickets/6706) * [#187](https://support.nextedy.com/helpdesk/tickets/187) * [#415](https://support.nextedy.com/helpdesk/tickets/415) **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/internal/ChecklistService.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/baselines/BaselinesView.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/IChecklistService.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistView.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/DocumentChecklistView.java` * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistUncheckAll.java`