Skip to main content

​
When to Use Read-Only Mode

Read-only mode is typically applied after a checklist has been completed and verified through a workflow gate. Common scenarios include:
  • Approved work items where the Definition of Done (DoD) must remain unchanged
  • Reviewed documents where the review checklist serves as an audit record
  • Completed test runs where pre-/post-execution checklists should not be modified

​
Methods for Enabling Read-Only Mode

There are two primary approaches to making checklists read-only. You can use them independently or combine them for stronger protection.
MethodScopeHow It Works
Polarion read-only fieldsPer status, per roleMakes the custom field non-editable at specific workflow statuses
Polarion field-based permissionsPer roleRestricts write access to the custom field by user role
diagram

​
Step 1: Make a Field Read-Only at Specific Statuses

Polarion allows you to configure which custom fields are read-only at each workflow status.
  1. Navigate to Polarion Administration > Work Items > Workflow
  2. Select the work item type (for example, Requirement)
  3. Open the status where you want the checklist to be read-only (for example, “Approved”)
  4. In the status configuration, add the checklist custom field (for example, dod) to the list of read-only fields
The exact steps for configuring read-only fields depend on your Polarion version and custom workflow setup. Consult your Polarion administration guide for the read-only field configuration interface.

​
Step 2: Restrict Write Access by Role

Use Polarion’s field-based permissions to restrict which roles can edit the checklist custom field, regardless of workflow status.
  1. Navigate to Polarion Administration > Work Items > Custom Fields
  2. Locate the checklist custom field
  3. Configure write permissions to allow only specific roles (for example, Quality Engineer, Project Lead)
  4. Set read-only access for other roles (for example, Viewer, Reporter, Developer)
This approach locks the checklist for users in restricted roles at all statuses, not just specific ones.
Use status-based read-only for general workflow protection (everyone is locked out after approval) and role-based permissions for finer control (only quality engineers can edit checklists at any status).

​
Step 3: Combine with Checklist Freezing

Read-only mode works best when combined with the template merge freeze. Without freezing, template items could still be added to a read-only checklist when the template is updated: 
nextedy.checklist.dod.approved.mergeTemplate=false
This stops template merging at the “approved” status. Together with read-only field configuration, the checklist is fully protected:
  1. Freeze prevents template items from being inserted
  2. Read-only prevents users from changing result states or adding items
See Freezing Checklists by Status for complete freeze configuration.

​
Step 4: Protect the Clear/Reset Button

Even with read-only fields, users with checklist admin permissions may still have access to structural actions. The “Reset to template / Clear” button is automatically hidden from non-admin users. If you need additional control:
  • Ensure only administrators have checklist admin permissions
  • Use the skipForUsers parameter on ChecklistResetToTemplate workflow functions to exempt specific users
See Controlling Access and Permissions for details on the admin permission model.
In some versions, conditional result states may display as “none” when a checklist becomes read-only. The underlying data remains correct. Make the checklist editable to verify the actual status is preserved. This is a known display issue being addressed in a future release.

​
Read-Only in Bulk Edit Mode

As of version 24.9.0, checklists do not load when bulk-editing work items of mixed types. This is a data integrity protection — it prevents template corruption when different work item types share the same checklist field. Select work items of a single type for bulk edit operations.
When bulk editing work items of a single type, read-only field configurations still apply based on the items’ workflow statuses.

​
Read-Only for Documents

For document (LiveDoc) checklists, read-only mode can be configured using:
  • Document-level field permissions
  • The hideInPdf() builder option to exclude checklists from PDF exports entirely (if the checklist should not appear in printed output)

​
Verification

After configuring read-only mode:
  1. Open a work item in the protected status (for example, “Approved”)
  2. You should now see the checklist displayed but with all interaction disabled — no ability to change result states, add items, or modify notes
  3. Move the work item back to an editable status (for example, “In Progress”)
  4. Verify the checklist becomes editable again
  5. Log in as a restricted role user and confirm the checklist appears read-only regardless of status

​
See Also

KB ArticlesSupport TicketsSource Code
  • ChecklistService.java
  • ChecklistSetupService.java
  • DocumentChecklistView.java
  • ChecklistAdminServlet.java
  • checklist-form.vm