Skip to main content

​
Reset a checklist automatically on work item type change

By default, when a work item’s type is changed, its previously saved checklist state can linger even though the new type may use a different template. Nextedy CHECKLIST includes a save hook that resets checklist values automatically when it detects a type change — but only for checklist IDs you’ve explicitly opted in.
  1. Open Administration > Configuration Properties.
  2. Add the checklist IDs (custom field IDs) that should be monitored for type changes (available from Checklist version 25.1.0):
  1. Configure a type-specific template for each work item type that uses the same checklist ID:
  1. Change the work item’s type (for example, from Userstory to Requirement).
If the monitored checklist is not empty and the type actually changes on a persisted item, the checklist automatically resets to the template configured for the new type.
Only checklist IDs you list are affectedOnly checklist IDs listed in nextedy.checklist.checklistsIdsForTypeChanges are watched for type-change resets. If a checklist isn’t listed, it keeps its content across a type change even if the new type has its own template configured.
Decision flow for resetting a checklist on work item type change
Verify in applicationgetChecklistsIdsForTypeChanges is documented in the service API as only available for work items (not modules, test runs, or plans) — confirm document-level type-change behavior separately if you rely on it there.

​
Known limitation: checklist stuck read-only after type change

A recurring, reopened issue affects documents (and work items) created from scratch and then converted to a different type afterward: the checklist can remain permanently read-only even though the rest of the item’s fields stay editable.
Known limitation — no confirmed fixCreating a document or work item from scratch and then changing its type afterward can leave the checklist stuck in read-only mode indefinitely, while other text fields on the same item remain editable. This has been reported and reopened without a resolution. If you hit this, do not assume it’s a permissions misconfiguration on your side — check whether the item was created with its final type from the start (via the correct template) as a workaround, since items created directly with the correct type have not shown the same symptom as reliably.
Related workflow-status interaction: a document created with the wrong type (for example, a generic type) and later switched to the correct type can also become read-only specifically when its status advances (for example, from Draft to InReview), even though a document created correctly from the template from the start is expected to behave the same way at that status.
Read-only can stem from status, type, or field permissions — check all threeWhen a checklist unexpectedly goes read-only, the cause can be any combination of: the document/work item’s current workflow status, whether its type was set correctly from creation or changed later, and standard Polarion field-level permissions (Administration > Work Items > Readonly Fields or role-based field permissions). Treat all three as suspects before concluding it’s a defect. For general read-only diagnosis steps, see Checklist Is Marked Read-Only.

​
Checklist-level read-only vs. field-level editability

A checklist can show as read-only in its own widget while the identical underlying custom field appears editable elsewhere, such as in a document’s column view. This is a real, documented mismatch rather than a bug in every case.
  1. Confirm the checklist ID and the custom field ID actually refer to the same field you’re comparing across views.
  2. Recall that the checklist form extension’s read-only state and the raw field’s Polarion-level editability are controlled independently — a checklist can be locked down via adminPermission-style configuration properties (see Property Hierarchy and Precedence Reference) while the field itself has no Polarion-level read-only flag set, or vice versa.
  3. Check both layers separately: the checklist’s own admin/edit permission configuration, and the field’s Polarion read-only/field-permission settings.
Don’t assume a single causeIf a checklist is read-only in its widget but the same field is editable in a document column, don’t jump straight to “bug.” Check the checklist-specific permission configuration first — it’s a separate control surface from standard Polarion field permissions, and the two can diverge by design or by misconfiguration.

​
Checklist merge preserves recorded results but refreshes other fields on re-sync

When a checklist template is re-applied and merged into an existing checklist, only a matching item’s result (its checked/unchecked/N-A state) is carried over and preserved from the existing, stored item. Other fields on that item — label, mandatory flag, description — are refreshed from the incoming template. See Template Merge Behavior for the authoritative description of this behavior. If checklist items appear to keep a stale label or mandatory flag after a template update while the previously recorded result stays exactly as it was, that’s expected merge behavior, not a defect — re-apply the template as a fresh reset (rather than a merge) if you need every field, including previously recorded results, replaced, understanding that a reset discards any progress already recorded.

​
Verify

You should now see the expected outcome for each scenario:
  • A work item whose checklist ID is listed in nextedy.checklist.checklistsIdsForTypeChanges resets cleanly to the new type’s template after a type change, instead of carrying over stale items.
  • A checklist that’s stuck read-only after a type change is recognized as a known limitation, with document/work item creation order and workflow status checked as likely contributing factors.
  • A mismatch between a checklist’s read-only state and the underlying field’s editability elsewhere is diagnosed by checking checklist permission configuration and Polarion field permissions as two separate layers.
  • A checklist re-synced from its template preserves each item’s previously recorded result state, while labels, mandatory flags, and descriptions on matching items refresh to match the template — understood as expected merge behavior rather than a save failure.

​
See also

KB Articles
  • Checklist is marked as readonly.
  • Freeze the checklist on some statuses
  • How to reset Checklist to the Template on WI type change
Support TicketsSource Code
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistConf.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/hook/SaveHandler.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistResetToTemplate.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/IChecklistService.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistService.java
Last modified on August 31, 2026