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).

Verify in applicationThis page documents the API surface as published in the product’s API documentation. 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)

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.

#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())
  <ul>
  [#if($i.checked)X#end]. $i.label
  <br>
  <i>$!i.note</i>
  </ul>
#end

IChecklistService API documentation illustration

LiveReport table fields and querying via Lucene are not confirmedNo documented mechanism adds checklist progress (for example 1/7 completed) as a LiveReport table field, or queries per-item checked-state via a Lucene-style query. The Velocity access pattern above — parsing the checklist field inside a script block — is the supported route. Treat a native LiveReport table column for a checklist as unsupported unless you confirm otherwise in your Polarion instance.

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). 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

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 overloadsThe published IChecklistService API article lists only the IWorkItem / WorkItem / IModule overloads of parse. The interface also declares parse 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

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 overloadsBoth the Checklist-typed and the raw-String-typed store overloads exist for ITestRun and IPlan, in addition to IWorkItem/WorkItem/IModule.

`applyTempate` — full signature list

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 — not destructiveEvery applyTempate overload behaves 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) 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

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 actionResetting 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

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 overloadsgetChecklistConf has dedicated ITestRun and IPlan overloads. Each derives readonly/adminPermission from whether the current user may modify that test run or plan, rather than from the Checklist licence authorisation used on the work item path.

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):

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 planChecklistUncheckAll (like the other workflow functions/conditions on the Workflow Functions and Conditions 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 functionsThe same shape works for custom use cases: 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

#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())
  <ul>
  [#if($i.checked)X#end]. $i.label
  <br>
  <i>$!i.note</i>
  </ul>
#end

This queries a single work item, parses its dor checklist field, and renders each item’s checked state, label, and note. 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 guideThe full <extension> 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, not repeated here to avoid duplication.

Known limitations

LiveReport table field / column integration for checklist progress is not confirmed as supported. There is no built-in field that shows progress (e.g., 1/7 completed) as a LiveReport table field without writing a Velocity script. 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. Whether the service can be reached from a JavaScript-based workflow condition — as opposed to Velocity (VTL) or Java — is unconfirmed. Only Java (via PlatformContext.getPlatform().lookupService) and Velocity (via $checklistService) access are confirmed. Verify JavaScript access in your Polarion instance before relying on it.

FAQ

IChecklistService and Velocity Rendering API

Overview

Accessing the service

From Java (workflow functions and conditions)

From Velocity (LiveReport / wiki pages)

Method reference — IChecklistService

`parse` — full signature list

`store` — full signature list

`applyTempate` — full signature list

`reset` — full signature list

`getChecklistConf` — full signature list

Worked example — Java workflow function

Worked example — Velocity on a LiveReport or wiki page

Known limitations

See also

​Overview

​Accessing the service

​From Java (workflow functions and conditions)

​From Velocity (LiveReport / wiki pages)

​Method reference — IChecklistService

​parse — full signature list

​store — full signature list

​applyTempate — full signature list

​reset — full signature list

​getChecklistConf — full signature list

​Worked example — Java workflow function

​Worked example — Velocity on a LiveReport or wiki page

​Related rendering entry point — checklist form extension

​Known limitations

​See also

Overview

Accessing the service

From Java (workflow functions and conditions)

From Velocity (LiveReport / wiki pages)

Method reference — IChecklistService

`parse` — full signature list

`store` — full signature list

`applyTempate` — full signature list

`reset` — full signature list

`getChecklistConf` — full signature list

Worked example — Java workflow function

Worked example — Velocity on a LiveReport or wiki page

Related rendering entry point — checklist form extension

Known limitations

See also