IChecklistService API - Nextedy Documentation

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

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

Example: Display checklist summary counts

#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

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

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

#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

#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

#set( $summaryFields = $checklistService.getChecklistsIdsForSummary( $wi ) )
#foreach( $fieldId in $summaryFields )
  #set( $cList = $checklistService.parse( $wi, $fieldId ) )
  Checklist "$fieldId": $cList.getCheckedCount() / $cList.getAllCount()
#end

Configuration Properties for template and merge configuration
Workflow Functions and Conditions for built-in workflow integrations
Compatibility and Versions for supported Polarion versions

Sources

KB Articles

IChecklistService API Documentation

Support Tickets

#5903
#5912

Source Code

ChecklistView.java
ChecklistAllChecked.java
ChecklistApplyTemplate.java
ChecklistResetToTemplate.java
ChecklistFormExtension.java

​Service Methods

​parse

​store

​reset

​applyTemplate

​getChecklistConf

​getChecklistsIdsForSummary

​getDocumentChecklistView

​Checklist Object

​Constructor

​Query Methods

​Mutation Methods

​Checklist Item Object

​Properties

​Methods

​Result State Enum

​Enum Methods

​Document Checklist View Builder

​Builder Methods

​Test Run and Plan Checklist View

​Accessing the API

​From Velocity (Wiki Pages and Live Reports)

​From Java (Workflow Functions and Conditions)

​From JavaScript / Nashorn (Scripted Conditions and Hooks)

​Common API Patterns

​Counting Rejected Items for Review Workflows

​Checking Mandatory Item Completion

​Working with Multiple Checklists

​Related Pages

Service Methods

parse

store

reset

applyTemplate

getChecklistConf

getChecklistsIdsForSummary

getDocumentChecklistView

Checklist Object

Constructor

Query Methods

Mutation Methods

Checklist Item Object

Properties

Methods

Result State Enum

Enum Methods

Document Checklist View Builder

Builder Methods

Test Run and Plan Checklist View

Accessing the API

From Velocity (Wiki Pages and Live Reports)

From Java (Workflow Functions and Conditions)

From JavaScript / Nashorn (Scripted Conditions and Hooks)

Common API Patterns

Counting Rejected Items for Review Workflows

Checking Mandatory Item Completion

Working with Multiple Checklists

Related Pages