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

Formatters style only — they do not enforceA 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

Document-level overrideThe 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.

Use a shared formatter for consistencyDefine 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.entity.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.entity — the current entity (row data)
context.value — the current cell value
context.document — the document data

Property names are case-sensitiveIn client-side expressions, context.entity.<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.

Verify in applicationConditional 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
Computed column — The column declares a value expression, so its content comes from the expression rather than from input

Troubleshooting: a column is read-only when you did not expect itBecause 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), condition 4 (a value expression 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).

Computed columns are read-only by definitionA column with a value expression takes its content from that expression, so declaring isReadOnly: true on it is redundant. A column whose binding key is $-prefixed goes further: it is unbound, stores nothing, and is forced read-only — not only in the editing UI but on every write path, so paste and fill cannot change it either. See Add a Computed Column.

System-managed and server-rendered columns are always read-onlyCertain 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.entity.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`	`false`	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 false for every property, ordinary ones included — a property is read-only unless you explicitly set updatable: true. A property with a serverRender annotation is read-only too, but for a different reason: Powersheet forces its effective value to false and ignores any updatable: true you set (see the Velocity Templates reference) — unlike an ordinary property, an explicit override can never make it editable.

Combine approaches for defense in depthUse 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