Configure Read-Only Column - Nextedy Documentation

Prerequisites

Before configuring read-only columns, ensure you have:

A working sheet configuration YAML file
Access to the project’s sheet configuration in Administration > Nextedy Powersheet
Familiarity with the column properties available in Powersheet

A read-only formatter applies visual styling only (for example, a grey background). It does not prevent editing on its own. To actually enforce that a column cannot be changed, set isReadOnly: true on the column (UI-level) and/or updatable: false on the property in the data model (server-level). Use the formatter alongside these to signal read-only status to users — not in place of them.

Set isReadOnly on a Column

Add isReadOnly: true to any column definition in your sheet configuration to disable editing for that column:

columns:
  outlineNumber:
    title: "#"
    width: 80
    isReadOnly: true

  systemRequirements.systemRequirement.id:
    title: "Req ID"
    width: 120
    isReadOnly: true

The isReadOnly property accepts a boolean value and defaults to false. When set to true, cells in that column cannot be modified regardless of user permissions or formatter rules.

Property	Type	Default	Description
`isReadOnly`	boolean	`false`	Prevents user editing of this column

The isReadOnly value on a column can be overwritten by the user’s permission level or the global configuration of the document. If a user has read-only access to the entire document, all columns become read-only regardless of individual column settings.

Add Visual Feedback with a Read-Only Formatter

Setting isReadOnly: true prevents editing but does not change the column’s appearance. To add a visual cue so users can immediately see which columns are non-editable, combine the property with a formatter:

formatters:
  readOnlyFormat:
    - expression: "true"
      style: readOnlyStyle

styles:
  readOnlyStyle:
    backgroundColor: grey100

columns:
  outlineNumber:
    title: "#"
    width: 80
    isReadOnly: true
    formatter: readOnlyFormat

This approach provides both functional protection (the cell cannot be edited) and a visual indicator (the grey background signals read-only status to users).

grey100 is one of Powersheet’s built-in color tokens. For the full palette of valid token names (each color family runs from 100 lightest to 700 darkest) and the predefined style names, see the Styles reference.

Define a single readOnlyFormat formatter and reference it across all read-only columns. This keeps your configuration DRY and ensures a uniform appearance throughout the sheet.

Use Conditional Read-Only with Formatters

For columns that should be read-only only under certain conditions, use a formatter with a conditional expression instead of a static isReadOnly flag:

formatters:
  lockedWhenApproved:
    - expression: "context.item.Status === 'Approved'"
      style: readOnlyStyle

styles:
  readOnlyStyle:
    backgroundColor: grey100

columns:
  title:
    title: "Title"
    width: 300
    formatter: lockedWhenApproved

In this example, the title column becomes visually styled as read-only when the work item’s Status is Approved. The formatter expression has access to the context object, which provides:

context.item — the current entity (row data)
context.value — the current cell value
context.document — the document data

In client-side expressions, context.item.<Property> must match the property name as defined in your data model exactly, including case. The examples here use Status because that is the property name in the demo model; substitute your own model’s casing. This client-side accessor is distinct from the server-side Velocity form $item.status.id used in server-rendered templates — do not mix the two notations.

Conditional formatter expressions apply visual styling. To fully enforce editing restrictions based on status, combine formatters with data model constraints or document-level permissions.

How Read-Only Resolution Works

Powersheet evaluates multiple conditions to determine whether a column is editable. A column becomes read-only if any of these conditions are true:

Configuration flag — isReadOnly: true is set on the column in the sheet configuration YAML
Historical revision — The user is viewing a past revision of the document (all columns automatically become read-only)
User permission — The document access control grants the user only viewer (not editor) access

Because the conditions above are combined with OR, any single one makes the column read-only. Work backwards from the symptom:

Every column in the document is read-only — check conditions 2 and 3: you are most likely viewing a past revision, or your access to the document is viewer-only.
One specific column is always read-only — check condition 1 (isReadOnly: true on that column) and the data model (updatable: false, or a serverRender annotation, on the underlying property).
A formatter-styled column looks locked but still edits — that is expected: a formatter only styles, it does not enforce (see the warning at the top of this page).

Certain columns such as outlineNumber are inherently managed by Polarion and should always have isReadOnly: true. In addition — this is the canonical rule referenced from the server-rendering pages — any property that defines a serverRender annotation, or that has updatable: false in the data model, is automatically read-only regardless of the sheet configuration. For server-rendered properties this override cannot be disabled: even updatable: true is ignored, because the value is always recomputed from the template.

Complete Configuration Example

Here is a full sheet configuration excerpt showing multiple read-only patterns in a requirements traceability context:

formatters:
  readOnlyFormat:
    - expression: "true"
      style: readOnlyStyle
  lockedOnApproval:
    - expression: "context.item.Status === 'Approved'"
      style: readOnlyStyle

styles:
  readOnlyStyle:
    backgroundColor: grey100

columns:
  outlineNumber:
    title: "#"
    width: 80
    isReadOnly: true
    formatter: readOnlyFormat

  id:
    title: "ID"
    width: 100
    isReadOnly: true
    formatter: readOnlyFormat
    hasUrl: true

  title:
    title: "Title"
    width: 300
    hasFocus: true
    formatter: lockedOnApproval

  systemRequirements.systemRequirement.id:
    title: "Sys Req ID"
    width: 120
    isReadOnly: true
    formatter: readOnlyFormat

  systemRequirements.systemRequirement.title:
    title: "Sys Req Title"
    width: 250

In this example:

outlineNumber and id are always read-only with grey background styling
title becomes visually styled when the item status is Approved
The expanded systemRequirement.id column is read-only since IDs should not be user-editable
systemRequirement.title remains editable (no isReadOnly flag)

Property-Level Permissions in the Data Model

You can also control editability at the data model level using the readable and updatable properties on entity type definitions:

domainModelTypes:
  UserNeed:
    properties:
      id:
        readable: true
        updatable: false
      title:
        readable: true
        updatable: true

Property	Default	Description
`readable`	`true`	Controls whether the property is visible to users
`updatable`	`true`	Controls whether the property can be modified by users

When updatable is false, the column becomes read-only for that property regardless of the sheet configuration isReadOnly setting.

updatable defaults to true for ordinary properties. The one exception is a property with a serverRender annotation: there, Powersheet forces the effective value to false (see the Velocity Templates reference). So a false default documented on the server-rendering pages refers specifically to server-rendered properties, not to the general case.

Use isReadOnly in the sheet configuration for UI-level protection and updatable: false in the data model for server-level enforcement. This ensures data integrity even if a configuration is accidentally changed.

Verification

After saving your sheet configuration changes, reload the Powersheet document in Polarion:

Open the sheet and click on a cell in the read-only column — you should see that the cell does not enter edit mode and the selection marquee shows a read-only indicator
If you applied a formatter, verify the grey background (or your custom style) appears on the read-only cells
Try pasting into a read-only column — the paste operation should be blocked
Confirm that editable columns next to the read-only ones still accept input normally

You should now see that the configured columns are protected from editing, with visual styling distinguishing them from editable columns.

​Prerequisites

​How Read-Only Resolution Works

​Complete Configuration Example

​Property-Level Permissions in the Data Model

​Verification

​See Also

Prerequisites

How Read-Only Resolution Works

Complete Configuration Example

Property-Level Permissions in the Data Model

Verification

See Also