> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Templates
> A checklist template is the single source of truth for what a checklist *should* contain.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
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:
```text theme={null}
nextedy.checklist._TYPEID_._FIELDID_.workItemTemplateId=WI-124
```
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](/checklist/concepts/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:
```text theme={null}
nextedy.checklist.documentSpecification.documentReadyChecklist.documentTemplateId=Specification/Product Spec Template
```
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 projects**
A 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 behavior**
The 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.
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 objects**
Because 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:
| Object type | Template resolution source |
| ------------------ | ------------------------------------------------------------ |
| work item | linked template work item, resolved via `workItemTemplateId` |
| document (LiveDoc) | linked template document, resolved via `documentTemplateId` |
| test run | the test run's own template test run |
| plan | the plan's own template plan |
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`:
```text theme={null}
nextedy.checklist.workitem.requirementReady.controlField=requirementType
nextedy.checklist.system.requirementReady.workItemTemplateId=EL-120
nextedy.checklist.software.requirementReady.workItemTemplateId=EL-121
```
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 list**
New 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 fields**
If 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](/checklist/concepts/workflow-gates) enforce that it *is* checked before a transition is allowed, and [baselines](/checklist/concepts/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.
## Related guides
* [Your First Checklist](/checklist/getting-started/your-first-checklist)
* [Set Up a Plan Checklist (Tutorial)](/checklist/getting-started/setup-plan-checklist)
* [Set Up a Test Run Checklist (Tutorial)](/checklist/getting-started/setup-test-run-checklist)
**KB Articles**
* How to create checklist template?
* Checklist workflow functions and conditions
* Multiple templates per one work item/document type
**Support Tickets**
* [#235](https://support.nextedy.com/helpdesk/tickets/235)
* [#325](https://support.nextedy.com/helpdesk/tickets/325)
* [#114](https://support.nextedy.com/helpdesk/tickets/114)
**Source 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`