Why a Hierarchy?
Consider a Polarion instance with dozens of work item types, each potentially hosting multiple checklist fields. Without a hierarchy, you would need to define every configuration property for every combination of type and field — a maintenance burden that scales quadratically. The hierarchy solves this by letting you declare a global default once and override it only where necessary. Think of it like CSS specificity: a broad rule covers everything, and increasingly specific rules override it for particular elements. The Checklist property hierarchy works the same way, with four levels of specificity.The Four Levels
All Checklist configuration properties follow the pattern:_TYPEID and _FIELDID segments are optional. Their presence or absence determines the specificity level:
| Level | Pattern | Scope |
|---|---|---|
| 1 — Global | nextedy.checklist.propertyName | All types, all fields |
| 2 — Type-specific | nextedy.checklist._TYPEID.propertyName | All fields on a specific work item type |
| 3 — Field-specific | nextedy.checklist._FIELDID.propertyName | A specific field on all work item types |
| 4 — Type + Field | nextedy.checklist._TYPEID._FIELDID.propertyName | A specific field on a specific work item type |
A Concrete Example
Suppose you want all checklist items to be mandatory across your organization, except for the “review” checklist field on “task” work items. You need exactly two properties:true value.
Without the hierarchy, you would need to set allMandatory = true individually for every type-and-field combination — and remember to add a new property every time someone creates a new work item type or checklist field.
Where Properties Are Defined
Configuration properties are set in Administration > Configuration Properties within Polarion. They can be defined at the global scope (system-wide) or within a specific project. Project-level properties override global ones, adding yet another layer of specificity on top of the four-level type-and-field hierarchy.Key Properties That Follow the Hierarchy
The following Checklist configuration properties all support the_TYPEID._FIELDID hierarchy pattern:
| Property | Purpose | Example Value |
|---|---|---|
workItemTemplateId | Work item ID used as the checklist template source | TPL-42 or shared:TPL-42 |
workItemTemplateHolder | Custom field that holds the template work item ID dynamically | templateRef |
documentTemplateId | Document location used as the checklist template source | _default/Templates/Review Checklist |
documentTemplateHolder | Custom field that holds the template document location dynamically | docTemplateRef |
allMandatory | Whether all checklist items are treated as mandatory | true or false |
mergeTemplateResolved | Whether template merging continues after work item resolution | true or false |
_STATUS.mergeTemplate | Whether template merging occurs in a specific workflow status | true or false |
_STATUS segment in mergeTemplate adds a fifth dimension beyond type and field — you can also key on the current workflow status. For example:
dod field of requirement work items when they are in the closed status.
Appearance Properties
Several properties control the visual appearance of checklist items and follow the same hierarchy:| Property | Purpose | Default Value |
|---|---|---|
nextedy.checklist.checked_sign | Icon for Checked items | far fa-check-square |
nextedy.checklist.unchecked_sign | Icon for Rejected items | far fa-minus-square |
nextedy.checklist.conditional_sign | Icon for Conditional items | far fa-plus-square |
nextedy.checklist.no_sign | Icon for None (unaddressed) items | far fa-square |
nextedy.checklist.conditional_enabled | Whether the Conditional state is available | false |
nextedy.checklist.debug | Enable debug logging | false |
These appearance properties use Font Awesome icon class names. You can override them per type or per field using the hierarchy. For instance, a “risk” checklist might use warning-themed icons while a “review” checklist uses standard checkboxes.
Common Misconceptions
“Level 2 (type-specific) overrides Level 3 (field-specific).” This is incorrect. The system tries Level 4 first, then Level 3 (field-specific), then Level 2 (type-specific), then Level 1 (global). Field-specific properties take precedence over type-specific ones. This can be surprising if you expect the type to be more specific than the field, but the resolution order is fixed. “I can use display names instead of IDs.” Property segments must use the technical IDs of work item types and custom fields, not their display names. For a work item type displayed as “User Story,” the technical ID might beuserstory. For a custom field displayed as “Definition of Done,” the ID might be dod. Check Polarion’s Administration pages to find the correct IDs.
“Properties are cached.” Configuration property values are read at parse time. Changes take effect the next time a checklist is loaded — you do not need to restart Polarion. However, already-open forms may need to be refreshed to pick up new values.
Designing Your Property Strategy
When planning your Checklist configuration, start from the top:- Set sensible global defaults (Level 1) for properties like
allMandatory,conditional_enabled, and icon appearance. - Override per type (Level 2) only where an entire type needs different behavior — for example, all checklists on “defect” work items might need different icons.
- Override per field (Level 3) when a specific checklist field has unique requirements regardless of the work item type it appears on — for example, a “dod” checklist might always require all items mandatory.
- Override per type + field (Level 4) only for truly exceptional cases where one specific combination needs its own configuration.
Baseline Configuration Properties
Baseline tracking introduces additional properties scoped to document contexts. These properties control how baselines are stored and retrieved:| Property | Purpose | Default |
|---|---|---|
| Baseline item type | The work item type used for storing baseline checklist data | btask |
| Baseline field | The custom field used to store baseline revision identifiers | baseline |
Baseline configuration properties are scoped per document context. The exact property names and configuration path depend on the document where baselines are enabled. Consult the baseline setup documentation for your project.
See Also
- Checklist States and Results — how
allMandatoryandconditional_enabledaffect state behavior - Template System — how
workItemTemplateIdand merge properties control template behavior - Workflow Integration — how workflow functions interact with configuration properties
- Reference — complete property reference
Sources
Sources
KB Articles
- How to create checklist template?
- Checklist configuration properties
- Multiple templates per one work item/document type
ChecklistService.javaChecklistFormExtension.javaDocumentChecklistView.javaChecklist.javaChecklistConf.java