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

# Controlling Access and Permissions

> Restrict who can view, edit, and manage checklists by combining Checklist admin permissions with Polarion's field-based permission system.

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>;
};

## Permission Layers

Checklist permission control operates at multiple levels. Understanding which layer applies helps you choose the right configuration approach.

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

## Step 1: Configure Field-Level Permissions

Polarion's field-based permission system controls who can read and write the checklist custom field. This is the most fundamental permission layer.

1. Navigate to **Polarion Administration > Work Items > Custom Fields**
2. Locate the checklist custom field (for example, `dod`)
3. Configure read/write permissions by role

You can restrict the checklist field to be:

* **Read-only** for specific roles (for example, Viewer, Reporter)
* **Editable** for other roles (for example, Project Lead, Quality Engineer)
* **Hidden** from roles that should not see the checklist at all

<Tip title="Use field permissions for role-based access">
  Field-level permissions are the recommended way to control who can edit checklists. They integrate with Polarion's existing role model and are enforced consistently across the UI, API, and bulk operations.
</Tip>

## Step 2: Understand Checklist Admin Permissions

Checklist distinguishes between regular editing (changing result states on individual items) and structural modification (clearing the entire checklist or resetting to template).

The **Reset to template / Clear** button in the checklist UI requires checklist admin permissions. Users without admin access will not see this button.

| Action                                  | Permission Required        |
| --------------------------------------- | -------------------------- |
| Change item result state (OK, NOK, N/A) | Field write access         |
| Add a note to an item                   | Field write access         |
| Add/remove checklist items              | Field write access         |
| Reset to template / Clear checklist     | Checklist admin permission |

<Warning title="Non-admin users cannot clear checklists">
  The Clear button (renamed "Reset to template / Clear" in v25.7.0) is hidden from users without checklist admin permissions. This prevents accidental or unauthorized deletion of checklist data.
</Warning>

## Step 3: Configure Read-Only by Status

To lock the checklist at specific workflow statuses, combine field permissions with the freeze configuration:

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false
```

Additionally, use Polarion's read-only field configuration to make the custom field non-editable at those statuses. This provides two-layer protection:

1. **Freeze** prevents template items from being added
2. **Read-only** prevents users from changing result states

See [Read-Only Mode](/checklist/guides/readonly-mode) and [Freezing Checklists by Status](/checklist/guides/freeze-by-status) for detailed configuration.

## Step 4: Restrict Workflow Function Access

Workflow functions like `ChecklistResetToTemplate` have a `skipForUsers` parameter that allows specific users to bypass the reset operation:

```
checklist = dod
skipForUsers = admin,migrationUser
```

This is primarily designed for data migration scenarios, but it also serves as a permission mechanism -- only listed users are exempted from the reset.

<Warning title="Bulk edit permission model differs from single-item edits">
  Checklist permission restrictions configured per template may not apply consistently during bulk edit operations. As of version 24.9.0, mixed-type bulk edits are explicitly blocked to prevent data corruption across different checklist templates. When performing bulk edits, select work items of a single type.
</Warning>

## Permission Decision Matrix

Use this matrix to determine which configuration to apply based on your requirement:

| Requirement                                | Configuration                                          |
| ------------------------------------------ | ------------------------------------------------------ |
| Restrict who can edit checklist items      | Polarion field permissions (read/write by role)        |
| Prevent non-admins from clearing/resetting | Checklist admin permissions (automatic)                |
| Lock checklist at a workflow status        | `mergeTemplate=false` + read-only field config         |
| Exempt users from workflow resets          | `skipForUsers` parameter on `ChecklistResetToTemplate` |
| Hide checklist from certain roles          | Polarion field permissions (hide field)                |
| Block mixed-type bulk edits                | Automatic in v24.9.0+ (no configuration needed)        |

## Step 5: Verify Permission Configuration

Test each permission layer to confirm it works as expected.

**Test field permissions:**

1. Log in as a user with the restricted role
2. Open a work item with a checklist
3. You should now see the checklist in read-only mode (no ability to change result states)

**Test admin permissions:**

1. Log in as a non-admin user
2. Open a work item with a checklist
3. You should now see the checklist without the "Reset to template / Clear" button

**Test bulk edit restrictions:**

1. Select work items of mixed types in a table view
2. Open the bulk edit panel
3. You should now see a notification that checklists are not supported for mixed-type bulk edits (v24.9.0+)

## See Also

* [Read-Only Mode](/checklist/guides/readonly-mode) -- lock checklists from editing by configuration
* [Freezing Checklists by Status](/checklist/guides/freeze-by-status) -- stop template merging at specific statuses
* [Workflow Gates and Validation](/checklist/guides/workflow-gates) -- enforce completion before transitions
* [Troubleshooting](/checklist/guides/troubleshooting) -- common permission-related issues

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