> ## 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.

# Read-Only Mode

> Lock checklists from editing using Polarion's field permissions and status-based configuration to protect completed checklists from accidental changes.

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 <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## 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.

| Method                           | Scope                | How It Works                                                      |
| -------------------------------- | -------------------- | ----------------------------------------------------------------- |
| Polarion read-only fields        | Per status, per role | Makes the custom field non-editable at specific workflow statuses |
| Polarion field-based permissions | Per role             | Restricts write access to the custom field by user role           |

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/guides/readonly-mode/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=35a07f83ffc33c23f1b991e49fc776d3" alt="diagram" style={{ maxWidth: "620px", width: "100%" }} width="620" height="220" data-path="checklist/diagrams/guides/readonly-mode/diagram-1.svg" />
</Frame>

<Steps>
  <Step title="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

    <Info title="Verify in application">
      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.
    </Info>
  </Step>

  <Step title="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.

    <Tip title="Combine status-based and role-based restrictions">
      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).
    </Tip>
  </Step>

  <Step title="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:

    ```properties theme={null}
    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](/checklist/guides/freeze-by-status) for complete freeze configuration.
  </Step>

  <Step title="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](/checklist/guides/permissions) for details on the admin permission model.

    <Warning title="Conditional status display in read-only mode">
      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.
    </Warning>
  </Step>
</Steps>

## Read-Only in Bulk Edit Mode

<Warning title="Mixed-type bulk edit restrictions">
  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.
</Warning>

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

* [Freezing Checklists by Status](/checklist/guides/freeze-by-status) -- disable template merging at specific statuses
* [Controlling Access and Permissions](/checklist/guides/permissions) -- role-based access control
* [Workflow Gates and Validation](/checklist/guides/workflow-gates) -- enforce completion before transitions
* [Baselines and Comparison](/checklist/guides/baselines) -- capture permanent records of checked states

<LastReviewed date="2026-07-02" />