Skip to main content

​
Prerequisites

  • Polarion administrator access (to create configuration properties)
  • A custom field of type Text (multi-line plain text) already configured on the target work item type (see Work Items Checklist)
  • Checklist installed and licensed (see Installation)

​
Create the Template Work Item

A checklist template is simply a work item whose checklist field contains the items you want to reuse. There is no special “template” object — any work item can serve as a template source.
  1. Create a new work item in your project (or in a dedicated templates project). The work item type does not need to match the target type.
  2. Open the checklist field on that work item and add the items you want in the template. For each item, set:
    • The label (display text)
    • The mandatory flag if the item should be required for workflow validation
    • An optional description for additional guidance
  3. Save the work item and note its work item ID (for example, TPL-1).
Changes to the template work item’s checklist propagate to every work item that references it. Adding or removing items in the template affects all linked checklists the next time they are loaded. Plan changes carefully and communicate them to affected teams.

​
Configure the Template Property

Navigate to Administration > Configuration Properties and create a property that points to your template work item. The property follows the Configuration Property Hierarchy pattern: 
nextedy.checklist._TYPEID._FIELDID.workItemTemplateId = TPL-1
Replace _TYPEID with the work item type ID (or omit for all types) and _FIELDID with the custom field ID (or omit for all fields). Examples for a “dod” (Definition of Done) checklist on user stories:
PropertyScope
nextedy.checklist.userstory.dod.workItemTemplateId = TPL-1Only dod field on userstory items
nextedy.checklist.dod.workItemTemplateId = TPL-1The dod field on all work item types
nextedy.checklist.userstory.workItemTemplateId = TPL-1All checklist fields on userstory items
nextedy.checklist.workItemTemplateId = TPL-1All checklists everywhere
diagram

​
Cross-Project Templates

To reference a template work item from a different project, use the projectId:workItemId format: 
nextedy.checklist.dod.workItemTemplateId = shared-templates:TPL-42
This reads the checklist from work item TPL-42 in the shared-templates project. Cross-project references are useful when multiple projects share the same compliance checklists.
Create a dedicated project (for example, shared-templates) that holds all template work items. Reference them from any project using the cross-project syntax. This centralizes maintenance — updating a template in one place updates every project that references it.

​
Document Templates

For document-level (LiveDoc) checklists, use the document template properties instead: 
nextedy.checklist._TYPEID._FIELDID.documentTemplateId = _default/Templates/Review Checklist
The value is the document location path. For dynamic selection, use documentTemplateHolder to specify a custom field that holds the document location at runtime.

​
Dynamic Template Selection

If different work items of the same type need different templates, use a template holder field: 
nextedy.checklist.requirement.dod.workItemTemplateHolder = templateRef
This tells Checklist to read the work item’s templateRef custom field at runtime and use its value as the template work item ID. Each requirement can point to a different template by setting a different value in templateRef. The holder field takes priority over the static workItemTemplateId. If the holder field is empty, the static ID serves as a fallback.

​
Control Template Merging

By default, templates merge continuously — every time the checklist is loaded, new template items are added. To stop merging after a work item is resolved: 
nextedy.checklist.dod.mergeTemplateResolved = false
To stop merging at a specific workflow status: 
nextedy.checklist.requirement.dod.closed.mergeTemplate = false
For details on merge control, see Template System and Freezing Checklists by Status.
If you do not configure mergeTemplateResolved or status-based mergeTemplate, template changes continue to propagate even to completed work items. For compliance scenarios where historical checklists must be immutable, always disable merging for resolved or closed statuses.

​
Verify the Configuration

After setting the template property:
  1. Open a work item that matches the configured type and field.
  2. You should see the template items populated in the checklist field.
  3. The items should display the labels, mandatory flags, and descriptions from the template work item.
  4. Try adding a local item — it should appear alongside the template items.
  5. Modify the template work item and reload the target — the change should propagate.
If the checklist field is empty, check:
  • The workItemTemplateId property value matches the template work item ID exactly
  • The custom field ID in the property matches the field on the work item form
  • The work item type ID in the property matches the target work item’s type

​
See Also

  • Template System — Conceptual overview of how template merging, inheritance, and dynamic selection work across all object types
  • Configuration Property Hierarchy — Understanding the four-level property resolution order from global defaults to type+field-specific overrides
  • Multiple Templates per Type — Assigning different checklist templates to different work item types using type-specific configuration properties
  • Workflow Gates and Validation — Enforcing checklist completion before workflow transitions using conditions and functions
  • Freezing Checklists by Status — Stopping template merging at specific workflow statuses to preserve checklist state for compliance and auditing
KB ArticlesSupport TicketsSource Code
  • ChecklistService.java
  • ChecklistSetupService.java
  • ChecklistResetToTemplate.java
  • ChecklistFormExtension.java
  • checklist-form.vm