Skip to main content
Think of a template as a rubber stamp for checklists. You carve the stamp once (define the items, set mandatory flags, add descriptions), and every time Checklist encounters an object that matches the template configuration, it presses that stamp onto the empty field. The result is a consistent starting point that users can then complete, and optionally extend with locally-added items.

​
How Templates Work

A template is not a separate entity in Polarion — it is simply a checklist that lives on a source object. For work items, the source is another work item whose checklist field contains the desired items. For documents, the source is another document. The template system reads the checklist content from this source and merges it into the target object’s checklist field. diagram This resolution happens every time the checklist is parsed — when a user opens the work item form, when a workflow function evaluates the checklist, or when the summary field is recalculated. The template is not copied once and forgotten; it is continuously merged according to the current configuration.

​
Template Sources by Object Type

Each of the four supported object types has its own template configuration mechanism:
Object TypeTemplate PropertyTemplate Source
Work itemnextedy.checklist._TYPEID._FIELDID.workItemTemplateIdAnother work item in the same or different project
Document (LiveDoc)nextedy.checklist._TYPEID._FIELDID.documentTemplateIdAnother document location
Test runTemplate configured via test run propertiesA test run template
PlanTemplate configured via plan propertiesA plan template
For work items, the template source is specified by work item ID. Cross-project references use the format projectId:workItemId. For example, shared-templates:TPL-42 refers to work item TPL-42 in the shared-templates project. For documents, the template source is specified by document location path.
If multiple projects need the same checklist, create a dedicated “templates” project that holds template work items. Reference them using the projectId:workItemId syntax in the workItemTemplateId configuration property. This centralizes maintenance — updating the template work item updates every project that references it.

​
Static Versus Dynamic Template Selection

The most common configuration is static — you set nextedy.checklist._TYPEID._FIELDID.workItemTemplateId to a fixed work item ID, and every matching object uses the same template. But Checklist also supports dynamic template selection through holder fields. Static selection: 
nextedy.checklist.requirement.dod.workItemTemplateId = TPL-42
Every requirement’s dod field uses the checklist from work item TPL-42. Dynamic selection: 
nextedy.checklist.requirement.dod.workItemTemplateHolder = templateRef
Here, each requirement has a custom field called templateRef. Checklist reads the value of that field at runtime and uses whatever work item ID it contains as the template source. This lets different instances of the same work item type use different templates. The dynamic holder takes priority over the static ID. If both workItemTemplateHolder and workItemTemplateId are configured, and the holder field on the work item contains a value, the holder value wins. If the holder field is empty, the static ID serves as a fallback. The same pattern applies to document checklists with nextedy.checklist._TYPEID._FIELDID.documentTemplateHolder and nextedy.checklist._TYPEID._FIELDID.documentTemplateId.

​
Template Merging

When Checklist loads a checklist instance, it merges the template content into the existing field data. This merge is not a simple overwrite — it is an intelligent combination:
  1. Items from the template that are not yet present in the instance are added.
  2. Items that the user has locally added (not from the template) are preserved.
  3. Items from the template that already exist in the instance retain their current result state.
This means the template can evolve over time. If an administrator adds a new item to the template, that item appears in every instance the next time the checklist is parsed. Users do not lose their existing progress. Each checklist item carries a fromTemplate flag that indicates whether it originated from the template or was manually added by the user. This flag matters during reset operations — resetting a checklist to template removes locally added items and restores template items to their default state.
Because template merging happens at parse time, changes to the source template work item immediately affect every checklist that references it. Adding or removing items in the template work item changes what appears on every matching work item, document, or test run the next time it is opened. Plan template changes carefully and communicate them to your team.

​
Controlling Template Merging

Not every checklist should always receive template updates. Checklist provides two properties to control when merging occurs:

​
Status-based merge control

The property nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate controls whether templates are merged when an object is in a specific workflow status. Set this to false for a given status to freeze the checklist at that point — template changes will no longer propagate. This is useful for “done” or “closed” statuses where the checklist should reflect what was actually checked at completion, not what the current template looks like.

​
Resolution-based merge control

The property nextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved controls whether template merging continues after a work item has a resolution set. When set to false, resolved work items stop receiving template updates regardless of their status.
Status-based control (mergeTemplate) is granular — you specify exact statuses where merging should stop. Resolution-based control (mergeTemplateResolved) is broader — it stops merging for any resolved item, regardless of which specific resolved status it is in. Use status-based control when different “done” statuses should behave differently; use resolution-based control as a catch-all for resolved items.

​
Template Application via Workflow

Templates can also be explicitly applied during workflow transitions using the ChecklistApplyTemplate workflow function. Unlike continuous merging, this function applies the template at the moment of the transition. It is typically used to initialize checklists when a work item enters a new phase. A related function, ChecklistResetToTemplate, goes further: it discards all user changes and locally added items, resetting the checklist to exactly what the template defines. This is useful for rework scenarios where the checklist must be completed again from scratch. Both functions accept a checklist parameter with the custom field ID (or comma-separated IDs for multiple checklists). They work across work items, documents, and test runs. For full details on workflow functions, see Workflow Integration.

​
Common Misconceptions

“Templates are stored separately.” They are not. A template is just a regular checklist on a regular Polarion object. The configuration property tells Checklist which object to read. There is no separate template repository. “Changing a template does not affect existing items.” It does. Because merging happens at parse time, template changes propagate immediately. To stop propagation, use status-based or resolution-based merge control. “I can embed a checklist template inside a document template.” The template system works through configuration properties, not through Polarion’s document template mechanism. When you create a document from a Polarion document template, the work items in it do not automatically get checklist templates applied. You need to configure the workItemTemplateId property so that checklists are merged when those work items are opened, or use the ChecklistApplyTemplate workflow function to apply templates during a transition.

​
Configuration Property Interaction

Template-related properties follow the same Configuration Property Hierarchy as all Checklist properties. This means you can configure templates at four levels of specificity:
LevelExample PropertyScope
Globalnextedy.checklist.workItemTemplateId=TPL-1All types, all fields
Type-specificnextedy.checklist.requirement.workItemTemplateId=TPL-2All fields on requirements
Field-specificnextedy.checklist.dod.workItemTemplateId=TPL-3The dod field on all types
Type + fieldnextedy.checklist.requirement.dod.workItemTemplateId=TPL-4Only dod on requirements
The system searches from most specific to least specific, using the first match. This lets you set a sensible default and override it where needed.

​
See Also

KB ArticlesSupport TicketsSource Code
  • ChecklistService.java
  • ChecklistSetupService.java
  • Checklist.java
  • ChecklistFormExtension.java
  • ChecklistApplyTemplate.java