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

# Permission-Based Field Restrictions

> Configure and troubleshoot field-level edit restrictions in Nextedy RISKSHEET, including instance field permissions, read-only enforcement for approved work items, downstream item protection, and formula interactions.

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

## Symptoms

| Issue                                                                | Likely Cause                                                         | Fix                                                     |
| -------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- |
| Users edit fields that should be read-only based on work item status | `checkInstanceFieldPermissions` not enabled                          | [Fix 1](#fix-1-enable-instance-field-permissions)       |
| Save fails because formula values differ from stored values          | Formula-permission conflict (e.g., truncated titles after migration) | [Fix 3](#fix-3-resolve-formula-permission-conflicts)    |
| `You do not have permissions to create new items.` error             | Polarion project permissions deny item creation for this user        | [Fix 5](#fix-5-resolve-item-creation-permission-errors) |
| `You have read-only access only. (Reviewer License)` message         | User has a Reviewer license, not a Named User license                | [Fix 6](#fix-6-handle-reviewer-license-restrictions)    |
| Child document items appear editable but save is blocked             | Known bug with child document permission detection                   | [Fix 7](#fix-7-handle-the-child-document-bug)           |
| Downstream task cells are editable when they should not be           | `downstreamReadonly` not enabled                                     | [Fix 4](#fix-4-configure-downstream-item-permissions)   |

## Permission Enforcement Flow

Risksheet applies multiple layers of permission checking when a user attempts to edit a cell. Understanding this flow helps diagnose which layer is blocking (or failing to block) an edit:

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/t34k0QhMnn4JCqkc/risksheet/diagrams/troubleshooting/permission-errors/diagram-1.svg?fit=max&auto=format&n=t34k0QhMnn4JCqkc&q=85&s=7d712918f427a74b5ced487190e8935e" alt="diagram" style={{ maxWidth: "680px", width: "100%" }} width="680" height="820" data-path="risksheet/diagrams/troubleshooting/permission-errors/diagram-1.svg" />
</Frame>

## Fix 1: Enable Instance Field Permissions

By default, Risksheet does not enforce Polarion's per-instance field restrictions because the native "Read-only Fields" property has no API. To enable field-level permission checking based on Polarion's Permissions Management, set the following project property in Polarion administration:

```
nextedy.risksheet.checkInstanceFieldPermissions = true
```

This property tells Risksheet to query Polarion's Permissions Management rules for each field before allowing edits. When enabled, fields that are restricted in the current work item status (e.g., severity locked in "Approved" status) will appear as read-only cells in the grid.

**How to set the property:**

1. Open Polarion Administration for your project
2. Navigate to project properties or global administration
3. Add or modify the property `nextedy.risksheet.checkInstanceFieldPermissions`
4. Set the value to `true`
5. Reload the Risksheet page

<Warning title="Polarion Read-only Fields Property Not Supported">
  Risksheet **cannot** read Polarion's "Read-only Fields" UI property because no API exists for it. You must use Permissions Management with `checkInstanceFieldPermissions` instead. Without this property enabled, Risksheet allows editing fields that Polarion's native work item editor would restrict. This is the primary reason users report being able to edit fields on approved work items.
</Warning>

## Fix 2: Understand System Field Restrictions

Certain system fields are always read-only in Risksheet regardless of any permissions configuration. Save attempts to these fields are silently ignored:

| Field          | Binding         | Reason                                           |
| -------------- | --------------- | ------------------------------------------------ |
| Work Item ID   | `id`            | System-generated identifier, immutable           |
| Status         | `status`        | Controlled exclusively by workflow transitions   |
| Type           | `type`          | Work item type cannot change after creation      |
| Project        | `project`       | Project assignment is fixed                      |
| Outline Number | `outlineNumber` | Document structure position, managed by Polarion |
| Author         | `author`        | Auto-set on work item creation                   |
| Resolution     | `resolution`    | Tied to workflow status transitions              |
| Created Date   | `created`       | Auto-set timestamp, immutable                    |
| Updated Date   | `updated`       | Auto-set timestamp, managed by Polarion          |

Additionally, columns are automatically set to read-only in the following cases:

| Condition                    | Property                       | Behavior                                             |
| ---------------------------- | ------------------------------ | ---------------------------------------------------- |
| Column has a formula         | `formula` property is set      | Column becomes read-only automatically               |
| Column uses server rendering | `serverRender` property is set | Column becomes text type and read-only automatically |
| Column is a reference        | Reference column type          | Column becomes read-only automatically               |

You can also explicitly mark any column as read-only in the configuration:

```yaml theme={null}
columns:
  - id: rpn
    header: RPN
    bindings: customField_rpn
    readOnly: true
```

<Warning title="readOnly is Case-Sensitive">
  The `readOnly` property must use camelCase with an uppercase `O`. Writing `"readonly": false` will **not** work. This is one of the most common configuration mistakes.
</Warning>

## Fix 3: Resolve Formula-Permission Conflicts

When formula-generated fields interact with permission restrictions, unexpected save failures can occur. This is a subtle issue that typically surfaces after data migrations or Polarion upgrades.

**The conflict sequence:**

1. A formula recalculates a value (for example, auto-generating the `title` field from hazard + effect)
2. The recalculated value differs from the stored value (for example, titles were truncated to 80 characters during a Polarion migration, but the formula generates the full-length title)
3. Risksheet detects a change and marks the item as edited
4. On save, Risksheet attempts to write the recalculated value
5. Permissions block the save because the field is read-only in the current status (e.g., "Approved")
6. The save fails with a permission error, even though the user only changed a different field (e.g., status)

**Diagnosis steps:**

1. Open the browser developer console (`F12`)
2. Attempt the save operation
3. Look for error messages indicating which fields triggered the permission check failure
4. Compare the formula output with the stored value in Polarion's work item editor
5. If the values differ, the formula is regenerating a value that does not match what is stored

**Workarounds:**

* **Correct the stored values:** Update the stored values in Polarion to match the formula output (e.g., fix truncated titles by editing them in Polarion's native editor while the item is in a draft status)
* **Temporarily change status:** Move the work item to a status that allows editing, save the formula-recalculated values, then move back to the restricted status
* **Use Check Stored Formulas:** Navigate to **Menu > Rows > Check stored formulas** to identify all formula values that differ from stored values

<Warning title="Data Migration Can Trigger Permission Failures">
  If Polarion titles were truncated to 80 characters during a migration, formula-generated titles will differ from stored values. Risksheet tries to save the recalculated title, which is then blocked by permissions on non-draft statuses. Fix the stored data before enabling strict permission enforcement.
</Warning>

<Tip title="Formulas Require Visible Columns">
  Formulas only execute when their column is visible in the current sheet view. If you use saved views for export-specific layouts, formulas in hidden columns will not recalculate. Never set an export view as the default view, since formulas run on sheet load. See [Formula Functions](/risksheet/reference/formulas/formula-functions) for details.
</Tip>

## Fix 4: Configure Downstream Item Permissions

To prevent editing of downstream linked items (tasks from other documents or projects), use the `downstreamReadonly` configuration setting:

```yaml theme={null}
downstreamReadonly: true
```

When `downstreamReadonly` is set to `true`:

* Task cells linked from other documents appear as read-only
* Task creation is blocked for read-only items (the `canExecute` check prevents it)
* The context menu hides "Add Task" options for read-only downstream items

The `downstreamReadonly` property defaults to `false`.

Additionally, task-level read-only state is tracked separately from master item state. The system uses `systemTaskReadOnly` and `systemTaskReadOnlyFields` to control which specific task fields are editable, independent of the parent risk item's permissions.

## Fix 5: Resolve Item Creation Permission Errors

If you see the error message:

```
You do not have permissions to create new items.
```

This means the current user's Polarion account lacks work item creation permissions in the target project. To resolve:

1. Verify the user's project role in Polarion Administration
2. Ensure the role grants "Create Work Items" permission
3. Check if the user has write access to the specific document where the Risksheet is embedded
4. Verify the user is not using a Reviewer license (see Fix 6)

## Fix 6: Handle Reviewer License Restrictions

If you see the message:

```
You have read-only access only. (Reviewer License)
```

The user has a Polarion Reviewer license, which provides read-only access. Risksheet respects Polarion's licensing model:

* **Reviewer license:** Read-only access. The `reviewer` mode activates, restricting editing and showing review-specific UI controls
* **Named User license:** Full read-write access based on project permissions

To enable editing for this user, upgrade their Polarion license from Reviewer to Named User.

## Fix 7: Handle the Child Document Bug

There is a known issue where items from child documents may appear editable in the grid, but the save operation fails with a permission error. This happens because Risksheet cannot always detect the correct permission state for items inherited from child documents.

**Symptoms:**

* Cells for child document items show as editable (clicking activates the editor)
* Typing a new value works, but clicking Save produces an error
* The error indicates a permission denial for the specific field

<Info title="Verify in application">
  The child document editing bug fix status should be verified against the current Risksheet release notes. If you encounter cells that allow editing but block saves for items originating from child documents, this is the known issue. Future versions address the permission detection for child document items.
</Info>

## Verification

After applying the fixes above, you should now see:

* Fields correctly marked as read-only for work items in restricted statuses (cells display with the `readonly` CSS class)
* Clicking non-editable cells does not activate the cell editor
* Formula-generated fields no longer trigger save failures when stored values match formula output
* The `You do not have permissions to create new items.` error resolves after granting project permissions
* Downstream task cells respect the `downstreamReadonly` setting
* Permission-restricted fields are indicated visually in the grid (read-only cells have a distinct appearance)

## See Also

* [Cell Editing Issues](/risksheet/troubleshooting/cell-editing-issues) -- general editing problems and read-only cell behavior
* [Save Operation Failures](/risksheet/troubleshooting/save-failures) -- save-related errors and conflict resolution
* [Access Denied Errors](/risksheet/troubleshooting/access-denied) -- access control, project permissions, and licensing issues
* [License Validation Errors](/risksheet/troubleshooting/license-validation-errors) -- license activation and validation failures
* [Date Column Save Errors](/risksheet/troubleshooting/date-column-save-errors) -- date-specific save issues related to format property bug
* [Error Messages Reference](/risksheet/troubleshooting/error-messages) -- complete error message catalog

<LastReviewed date="2026-06-24" />