| FAQ Topic Areas | |
|---|
| Object Types | Configuration |
| & Setup | & Properties |
| Workflow Gates | API & Integration |
| & Conditions | |
What Polarion object types does Checklist support?
Checklist supports four Polarion object types: work items, documents (LiveDocs), test runs, and plans. Each object type stores checklist data in custom fields of type Text (multi-line plain text). Work items and documents have the broadest feature support including workflow gates, templates, baselines, and summary fields. Test runs and plans support checklist rendering, templates, and PDF export. See the Getting Started tutorials for setup instructions:
What are the five result states for checklist items?
Each checklist item can have one of five result states: OK (checked/passed), NOK (rejected/failed), N/A (not applicable), Pending (awaiting evaluation), and Empty (not yet evaluated). These result states determine whether workflow conditions pass and how summary fields are calculated.
What custom field type do I need for checklists?
Checklist fields must use the type Text (multi-line plain text). This is the most common configuration mistake. If you use the wrong field type, Checklist displays a validation error at render time explaining the type mismatch. Create custom fields with the correct type in Polarion Administration before configuring Checklist.
Using any field type other than Text (multi-line plain text) causes a render-time error. Double-check the field type in your Polarion custom field configuration if you see a type mismatch error.
How does the configuration property hierarchy work?
Checklist uses a 4-level configuration property hierarchy with increasing specificity:
- Global (
nextedy.checklist.*) — applies to all types and fields
- Type-specific (
nextedy.checklist._TYPEID.*) — applies to a specific work item type
- Field-specific (
nextedy.checklist._FIELDID.*) — applies to a specific checklist field
- Type+Field-specific (
nextedy.checklist._TYPEID._FIELDID.*) — applies to a specific type and field combination
A more specific property always overrides a more general one. For the full property listing, see Configuration Properties.
How do workflow gates enforce checklist completion?
Checklist provides workflow conditions that block state transitions until checklists are complete. The all items checked condition requires every checklist item to have result state OK. The mandatory items checked condition requires only mandatory items to be checked. Both conditions accept a checklist parameter with comma-separated field IDs. When multiple checklists are specified, all must satisfy the condition (AND logic). See Workflow Functions and Conditions for configuration details.
Can I count rejected (NOK) items or create workflow conditions for them?
There are no built-in workflow conditions that gate on rejected item counts. However, you can implement custom counting and conditions using the Checklist service API. The API provides a method to get the rejected item count from a parsed checklist, which you can use in custom workflow conditions or Velocity-based reports. See IChecklistService API for examples.
What is the difference between “reset to template” and “apply template”?
Reset to template discards all user changes and returns the checklist to a clean template state. Apply template merges missing template items into the existing checklist without removing user-added items or changing existing item states. Use reset when you need a fresh start (for example, when restarting a workflow). Use apply template when you want to add newly defined template items to existing checklists.
The reset to template workflow function supports a skipForUsers parameter that lets specified users bypass the reset. This is useful during data migration or bulk operations where administrators need to update work items without triggering automatic resets.
How do I access the Checklist service API?
You can access the Checklist service API from three contexts:
| Access Method | Context | How to Access |
|---|
| Velocity | Wiki pages, live reports | Use the $checklistService variable |
| Java | Workflow functions, extensions | Use the Polarion platform service lookup |
| JavaScript (Nashorn) | Scripted conditions, save hooks | Use the platform registry service pattern |
Do I need to clear the workspace cache after installation?
Yes. After installing or upgrading Checklist, you must delete the workspace configuration cache at [POLARION_INSTALL]/data/workspace/.config and restart Polarion. This step is critical and frequently missed. Skipping it can cause the plugin to fail silently or not appear in the UI. See Installation for the complete procedure.
Can I use multiple checklists on a single work item?
Yes. You can define multiple checklist custom fields on a single object type and configure each independently with its own template, workflow conditions, and configuration properties. For example, you might have a dod (Definition of Done) checklist and a dor (Definition of Ready) checklist on the same work item type. Workflow conditions support comma-separated field IDs to validate multiple checklists in a single transition.
How does template merging work?
When you parse a checklist with the API or render it in the UI, Checklist automatically merges items from the configured template into the existing checklist. You can control this behavior per type, field, and status using configuration properties:
nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate — enable or disable merging for a specific statusnextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved — control merging after a work item has a resolution set
Templates can be sourced from a static work item ID (workItemTemplateId), a dynamic field reference (workItemTemplateHolder), or document-level equivalents for LiveDoc checklists. See Configuration Properties for the full property reference.
