Skip to main content
1

Identify which read-only cause applies

A checklist can appear read-only for three distinct reasons, and they require different fixes. Work through them in order.
Decision tree for diagnosing a read-only checklist: field permissions, form extension setup, or a status/type freeze
2

Rule out standard Polarion permissions

This is expected behavior, not a defect. The checklist custom field can be made read-only the same way any other custom field can:
  • Administration > Work Items > Readonly Fields
  • Field-based permissions in Administration > User Management > Permissions Management
If either of these marks the checklist’s custom field as read-only, the checklist form extension correctly reflects that — there is nothing to fix in the checklist configuration itself.
Distinguish checklist-level control from field-level permissionsA checklist can look read-only in the checklist UI while the same underlying custom field still appears editable when displayed elsewhere (for example, in document columns). If you see that mismatch, don’t assume the checklist configuration is broken — check both layers separately: the field’s Polarion permissions/read-only-fields setting, and the checklist configuration properties described in Step 4.
3

Fix a misconfigured checklist form extension

If the work item extension responsible for rendering the checklist editor isn’t configured correctly, it can’t locate the editor on the work item form, and the field renders as if it were read-only even though no permission is blocking it.Confirm the checklist form extension is set up correctly by following the object-type setup guide for the item you’re working with:
Verify in applicationThe exact form-layout XML that wires the checklist form extension into a given work item type isn’t covered in this article — confirm your form layout against the relevant setup guide above rather than assuming the extension is present by default.
4

Check for a status-based or type-based freeze

If Steps 2 and 3 don’t explain what you’re seeing, the checklist may be intentionally frozen through configuration properties rather than through Polarion permissions.

​
Freeze on workflow status

You can freeze the checklist definition so that, once a work item or document reaches a given status, the template is no longer reapplied and the checklist keeps whatever content it already has:
Example — freezing the dod checklist once a work item reaches status reviewed:
The checklist must be initialized before you freeze itOnce frozen, the checklist shows only the data stored so far. If you add new template items but never trigger a save that touches the checklist status, those new items will not appear — the work item still has the old, unsynchronized data. Make sure the checklist template has been applied (synchronized into the work item) before the status transition that freezes it, for example by attaching the ChecklistApplyTemplate workflow function to the transition (see Configure Gate Enforcement (DoD / DoR) and Freeze on Status).

​
Restrict who can change the checklist structure

Separately from freezing on status, you can restrict who is allowed to add, remove, or edit checklist items (as opposed to simply checking/unchecking them) using:
Accepted values are @none, @all, or a comma-separated list of user roles (including project roles).Example — dod checklist manageable by admin and project_developer, but locked once a userstory reaches verified; dor checklist locked except while the userstory is in draft:
When adminPermission evaluates to @none for the current context, users lose the controls to add or delete checklist items, but — unless the field itself is also read-only per Step 2 — they can still mark existing items as checked.The system evaluates adminPermission using the full 4-level precedence, most specific first (shown here for type userstory, checklist dod, status accepted):
  1. nextedy.checklist.userstory.dod.accepted.adminPermission
  2. nextedy.checklist.dod.accepted.adminPermission
  3. nextedy.checklist.userstory.dod.adminPermission
  4. nextedy.checklist.dod.adminPermission
  5. nextedy.checklist.userstory.accepted.adminPermission
  6. nextedy.checklist.accepted.adminPermission
  7. nextedy.checklist.userstory.adminPermission
  8. nextedy.checklist.adminPermission
Starting with version 25.7.0Regular users without admin permission for the evaluated context can no longer clear the checklist structure — the Clear action is removed from the gear menu icon in that case.
For the full picture of how these properties combine with Polarion permissions, see Control Who Can Change the Checklist.

​
Known limitation: type change can leave the checklist stuck read-only

Changing a work item or document type after creation can leave the checklist permanently read-onlySupport tickets describe a recurring case: a work item or document is created from scratch (or created with the wrong type, e.g. a generic type) and its type is later changed to the correct one. After the type change — sometimes triggered by a subsequent status transition such as moving from Draft to InReview — the checklist can remain stuck in read-only mode even though other fields on the same item remain editable. This has been reported more than once, including as a reopened ticket, and does not currently have a confirmed fix. If you hit this, first rule out Steps 2–4 above (field permissions, form extension setup, and adminPermission/mergeTemplate properties) — if none of those explain it, treat it as this known limitation rather than a new configuration issue, and capture the exact type-change sequence for support.

​
Verification

You should now see one of the following:
  • The checklist field is intentionally read-only per Readonly Fields or field-based permissions, and this is expected — no further action needed.
  • The checklist form extension correctly locates the editor and renders an editable checklist on the work item, document, test run, or plan form.
  • The checklist behaves according to your mergeTemplate / mergeTemplateResolved and adminPermission configuration properties — editable when the evaluated context allows it, and frozen only where you intended.
If the checklist is still unexpectedly read-only after working through all four steps, and no type change is involved, continue with Save Errors and Version Compatibility.

​
See also

KB Articles
  • Checklist is marked as readonly.
  • Freeze the checklist on some statuses
  • How to control who can change the list and when ?
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/wf/ChecklistResetToTemplate.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/IChecklistService.java
  • proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistService.java
Last modified on August 31, 2026