Skip to main content
Think of a template the way you’d think of a form used in a paper-based audit process: the form itself (the questions, the order, which boxes are mandatory) is designed once by a process owner. Copies are then handed out to individual reviewers, who fill in their own answers, but nobody is allowed to change the questions on the form itself. Nextedy CHECKLIST templates work the same way — the template defines the shape of the checklist, and individual work items, documents, test runs, and plans hold their own progress against that shape.

​
Why templates exist

Without a template, a checklist is just free text typed directly into a custom field. That works for a one-off list, but it breaks down the moment you need the same review criteria applied consistently across dozens or hundreds of objects — which is exactly the situation in regulated environments where Definition of Done (DoD) and Definition of Ready (DoR) gates must be identical across a whole project or product line. Templates solve two distinct problems at once:
  • Consistency — every work item of a given type gets the same checklist items, in the same order, with the same mandatory items flagged.
  • Central maintenance — when the process changes (a new mandatory review step is added, for example), you edit the template once, and, depending on how the template is applied, that change can propagate outward instead of requiring you to hunt down and edit every individual work item.

​
Two ways templates are defined

The gathered context describes two distinct mechanisms for supplying a template, and they behave differently enough that mixing them up is a common source of confusion.

​
1. Configuration-property templates

The first — and generally preferred — approach points a checklist at a template work item (or template document) purely through a configuration property:
Here, _TYPEID_ is the work item type (for example requirement) and _FIELDID_ is the checklist ID — the ID of the custom field that holds the checklist (for example chkApproved). Both parts of the key are optional, which is what makes this mechanism hierarchical: you can scope a template narrowly to one type and one checklist, or broadly to any checklist of any type. This precedence behavior is covered in depth in Configuration Property Hierarchy — templates are simply one property that follows that same resolution pattern. For documents (LiveDocs), the equivalent property points at a document path instead of a work item ID:
The key phrase in the source material is that all changes to a checklist template are instantly promoted — because the checklist items themselves are not copied into the work item at creation time; they’re read from the template location, live, at parse time. This is a fundamentally different mental model from a “starter” or “seed” list: it is a live pointer, not a snapshot.
Global templates across projectsA template doesn’t have to live in the same project as the objects using it. Prefixing the template ID with a project ID (myOtherProject:WI-124) lets you centralize a template in one project and reuse it from any number of downstream projects — useful when a compliance team owns the canonical DoD/DoR definitions and product teams simply consume them.

​
2. Polarion built-in work item templates

The second approach uses Polarion’s own built-in work item templating (create a work item titled something like “TEMPLATE”, mark it resolved so it disappears from default views, and reference it from the workitem-type-enum). This piggybacks on a platform feature that predates the checklist product.
Known interaction with Polarion’s template copy behaviorThe gathered KB content documents a specific interaction issue: when Polarion’s built-in template mechanism copies data from the template into a newly created work item, it can change the checklist field’s format from Text to Richtext — which corrupts the checklist’s expected text syntax. The documented workaround is to add a ChecklistResetToTemplate workflow function to the type’s “init” workflow action, with a checklist parameter naming the affected custom field, so the checklist is re-parsed (and its format corrected) immediately after creation. This is described as a Polarion-side issue rather than a defect in Checklist itself.

​
The merge model: how a template’s items reach a work item

Understanding how a template’s items combine with an object’s own checklist field explains a lot of behavior that otherwise looks surprising. When a checklist is parsed, template items are merged into the object’s existing items using an ID-based match:
  • If an item ID from the template does not already exist on the object, it’s added as a new item (marked as originating from the template).
  • If an item ID does already exist, only its result is carried over from the stored content — its label, mandatory flag, and description are refreshed from the template. In other words, the template stays authoritative for the shape of each item (its wording and whether it’s mandatory), while the reviewer’s recorded result (checked / rejected / conditional / empty) is preserved.
A template's items merging into a work item's checklist field by item ID, with labels and mandatory flags carried over while recorded results are preserved
This merge-by-ID behavior is also what powers template re-sync: if the process owner adds a new mandatory item to the template, every work item that reads that template picks up the new item the next time its checklist is parsed — without disturbing results already recorded against the items that already existed.
Changing an item’s mandatory flag reaches existing objectsBecause label, mandatory flag, and description are always taken from the template on merge, changing whether an existing template item is mandatory (or editing its wording) does reach in-flight objects — the change is picked up the next time each object’s checklist is parsed. Only the recorded result stays with the object. This applies to already-existing items, not just newly-added ones.

​
Item-level template metadata: fromTemplate

Each checklist item internally tracks whether it originated from a template (as opposed to being added manually to that specific object). This distinction matters conceptually even where the UI doesn’t surface it directly to end users: a template-sourced item represents a process requirement handed down from a governing definition, while a manually-added item represents something a specific reviewer decided to track locally. Documentation and process design should treat these as different categories of checklist content — one is centrally governed, the other is ad hoc.

​
Object types that can carry a template

Template resolution is supported for all four object types that Checklist can attach to: Test runs and plans resolve their template from the object’s native “template” relationship rather than from a configuration property pointing at an arbitrary object — a subtle but important distinction from the work item and document cases.

​
Multiple templates for the same checklist

By default, the system picks a template based on the work item or document type alone. But the resolution can be made conditional on the value of another field — a control field — so that, for example, a requirementReady checklist loads a different template depending on whether a requirementType custom field is set to system or software:
This is the same dot-notation property hierarchy used everywhere else in Checklist configuration, just with the control field’s value substituted in place of the work item type segment. The equivalent mechanism exists for documents via nextedy.checklist.document._CHECKLISTID_.controlField.

​
Common misconceptions

A template is not a one-time starter listNew users sometimes assume that applying a template simply seeds a work item with an initial set of items that can then be freely edited without consequence, the way a code snippet inserts boilerplate text. In practice, template items remain linked by ID to the template’s own items, and re-parsing (or an explicit reset/apply-template workflow action) re-syncs against the template. Treat template items as governed content, not a one-time copy.
Editing the template does not retroactively fix already-corrupted fieldsIf a checklist field’s format was already corrupted by Polarion’s built-in template-copy bug (Text becoming Richtext), simply pointing to a correct configuration-property template afterward does not undo that corruption on existing objects. The ChecklistResetToTemplate workflow function is the documented remedy, and it must actually run against the affected object.

​
Where templates fit in the bigger picture

Templates are one of three pillars that make checklist enforcement possible in a regulated process: the template defines what must be checked, workflow gates enforce that it is checked before a transition is allowed, and baselines preserve historical proof of what was checked at a point in time. Templates answer the “what should this checklist contain” question; they say nothing on their own about whether completing it is required to proceed — that’s the workflow gate’s job.
KB Articles
  • How to create checklist template?
  • Checklist workflow functions and conditions
  • Multiple templates per one work item/document type
Support TicketsSource Code
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistItem.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/Checklist.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistFormExtension.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistProduct.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistAdminService.java
Last modified on August 31, 2026