Permissions

See also: Properties | Data Model Types | Relationships

Permission Architecture

Powersheet permissions operate at two distinct levels within the data model YAML:

Property-level — the readable and updatable flags on each property definition within an entity type
Navigation property-level — permission settings on the direct and back objects within relationship definitions

Both levels use the same two boolean flags to control access.

Property-Level Permissions

Individual properties on entity types support readable and updatable flags that control field-level access. These flags are set within the data model YAML under each entity type’s properties map.

Permission Flags

Name	Type	Default	Description
`readable`	`boolean`	`true`	Controls whether the property is visible. When set to `false`, the property is excluded from the data payload entirely — it is not loaded from the server and not transmitted to the client. This provides data-level security, not merely UI hiding.
`updatable`	`boolean`	`true`	Controls whether the property can be modified by users. When set to `false`, the property appears in the sheet as read-only. Users can view the value but cannot change it.

Setting readable: false does not simply hide a column in the UI. The property is completely excluded from the data payload sent to the client. This means the value is never loaded, never transmitted, and never available to column bindings, queries, or client-side logic. Use this for properties that contain sensitive data or internal identifiers that should not leave the server.

Permission Combinations

`readable`	`updatable`	Result
`true`	`true`	Property is visible and editable (default behavior).
`true`	`false`	Property is visible but read-only. Users can see the value but cannot modify it. Useful for computed fields, audit stamps, or reference data.
`false`	`true`	Property is hidden from the client entirely. The `updatable` flag has no practical effect since the property is not transmitted.
`false`	`false`	Property is hidden from the client entirely. Equivalent to `readable: false` alone.

The isReadOnly flag on a column definition controls whether a specific column is editable in the sheet UI. The updatable flag on a property controls whether the underlying data field can be modified at all. If updatable: false is set on the property, the field is read-only regardless of the column’s isReadOnly setting.

Configuring Property Permissions in YAML

Basic Example

Properties without explicit permission flags inherit the defaults (readable: true, updatable: true):

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:

All three properties above are visible and editable.

Mixed Permissions Example

Apply explicit permission flags to restrict individual properties:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      id:
        readable: true
        updatable: false
      title:
        readable: true
        updatable: true
      outlineNumber:
        readable: true
        updatable: false
      description:
      severity:

In this configuration:

id — visible but cannot be edited (system identifier)
title — explicitly set to visible and editable (same as default)
outlineNumber — explicitly declared and marked visible but read-only (managed automatically by Polarion)
description and severity — inherit defaults (visible and editable)

Hiding Sensitive Properties

To prevent a property from being transmitted to the client at all, set readable: false:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:
      internalClassification:
        readable: false

The internalClassification property is completely excluded from the data payload. No column binding can reference it, and it does not appear in query results returned to the client.

Built-in Property Permissions

Certain properties have inherent permission characteristics based on their role in the Polarion data model. The following table lists common built-in properties and their typical permission settings:

Property	Typical `readable`	Typical `updatable`	Notes
`id`	`true`	`false`	Work item identifier. System-managed, never user-editable.
`title`	`true`	`true`	Work item title. Usually editable.
`description`	`true`	`true`	Standard text property. Editable by default.
`severity`	`true`	`true`	Enumeration property. Editable by default.

Unlike id and title, outlineNumber is not an implicit built-in property of every entity type. To use it, you must explicitly declare it in the entity type’s properties map in your data model YAML. When declared, it is typically configured as readable: true, updatable: false because its value is managed automatically by Polarion based on the document hierarchy.

Built-in property behavior may vary depending on the Polarion version and project configuration. Verify the exact behavior of each built-in property in your environment.

Entity Types and Permission Scoping

Permission flags are scoped to each entity type independently. The same property name can have different permissions on different entity types:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      severity:
        readable: true
        updatable: true

  SystemRequirement:
    polarionType: sys_req
    properties:
      severity:
        readable: true
        updatable: false

In this example, severity is editable on UserNeed entities but read-only on SystemRequirement entities.

Special Entity Types

Entity Type	Purpose	Permission Notes
`Document`	Built-in entity for Polarion LiveDocs	Supports mixed permission settings on properties. Useful for controlling which document-level fields are editable.
`Chapter`	Entity type mapped to Polarion `heading` work item type	Properties are typically read-only since headings are structural elements.
`Project`	Built-in entity for Polarion project metadata	Minimal property definitions. Permissions rarely customized.

Relationships in the data model define navigation properties that allow traversal between entity types. Each relationship has a direct and optionally a back direction, and each direction can carry its own permission settings.

The navigation property permission system is under active development. The behavior described below reflects the current implementation, but changes are expected. Updated documentation will follow as the feature stabilizes.

Name	Type	Default	Description
`direct.name`	`string`	(required)	Name of the forward navigation property on the source entity.
`back.name`	`string`	(optional)	Name of the reverse navigation property on the target entity.
`createable`	`boolean`	See application	Controls whether new relationship instances can be created through this navigation property.
`readable`	`boolean`	See application	Controls whether the navigation property is visible in queries and data payloads.

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

The direct object defines the forward navigation property (from source to target), while the back object defines the reverse navigation property (from target back to source). Each can have independent permission settings that control whether the navigation path is available and whether new links can be created through it.

Read-Only Mode

The sheet can enter a global read-only mode through several mechanisms. When read-only mode is active, all properties behave as if updatable: false regardless of their individual settings.

Condition	Effect
Configuration `isReadOnly` is `true`	Entire sheet is read-only.
User is viewing a historical revision	Sheet is read-only (revisions are immutable).
License status is `INVALID`	Restricted access; sheet is read-only.

When any of the conditions above is met, the sheet enters read-only mode. Individual updatable: true settings on properties are overridden. The sheet displays all readable properties but prevents any modifications.

Permission Decision Flow

The following table summarizes how the final editability of a field is determined:

Check	Condition	Result
1. Global read-only	`isReadOnly` config, historical revision, or invalid license	All fields read-only
2. Property `readable`	`false`	Property excluded from data payload
3. Property `updatable`	`false`	Property visible but not editable
4. Column `isReadOnly`	`true`	Column display is read-only in the sheet UI
5. All checks pass	—	Field is visible and editable

Checks are evaluated in order. A false result at any step short-circuits subsequent checks for that field.

Complete YAML Example

A data model demonstrating permission controls across multiple entity types with varied access levels:

domainModelTypes:
  Chapter:
    polarionType: heading
    properties:
      title:
        readable: true
        updatable: false

  UserNeed:
    polarionType: user_need
    properties:
      id:
        readable: true
        updatable: false
      title:
        readable: true
        updatable: true
      outlineNumber:
        readable: true
        updatable: false
      description:
      severity:
      internalNotes:
        readable: false

  SystemRequirement:
    polarionType: sys_req
    properties:
      id:
        readable: true
        updatable: false
      title:
      description:
      severity:
        readable: true
        updatable: false

  DesignRequirement:
    polarionType: des_req
    properties:
      title:
      description:

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

This example demonstrates:

Chapter.title — visible but read-only (structural headings should not be edited through the sheet)
UserNeed.id — visible but read-only (system identifier)
UserNeed.outlineNumber — explicitly declared as visible but read-only (auto-managed by Polarion; this property must be declared explicitly to appear in the model)
UserNeed.internalNotes — hidden entirely (readable: false); never transmitted to the client
SystemRequirement.severity — visible but read-only (locked for this entity type)
DesignRequirement properties — all defaults (visible and editable)

Best Practices

Practice	Recommendation
Sensitive data	Use `readable: false` to prevent transmission to the client. Do not rely on column visibility alone.
Audit fields	Set `updatable: false` on explicitly declared fields like `id`, `outlineNumber`, and timestamp fields that should not be manually edited.
Progressive disclosure	Use Views to control which columns are visible in different analysis perspectives, rather than using `readable: false` which removes data access entirely.
Consistent naming	Keep property names aligned across entity types when they serve the same purpose (e.g., `severity` on both `UserNeed` and `SystemRequirement`).
Testing permissions	Verify permission behavior in a test project before deploying to production. Check that hidden properties are truly absent from server responses.

Use Views when you want to show or hide columns for different user workflows — the data is still loaded but specific columns are toggled. Use readable: false when the data itself must not leave the server.

Permission Architecture

Property-Level Permissions

Permission Flags

Permission Combinations

Configuring Property Permissions in YAML

Basic Example

Mixed Permissions Example

Hiding Sensitive Properties

Built-in Property Permissions

Entity Types and Permission Scoping

Special Entity Types

Navigation Property Permissions

Navigation Direction Properties

Relationship YAML with Navigation Directions

Read-Only Mode

Permission Decision Flow

Complete YAML Example

Best Practices

​Permission Architecture

​Property-Level Permissions

​Permission Flags

​Permission Combinations

​Configuring Property Permissions in YAML

​Basic Example

​Mixed Permissions Example

​Hiding Sensitive Properties

​Built-in Property Permissions

​Entity Types and Permission Scoping

​Special Entity Types

​Navigation Property Permissions

​Navigation Direction Properties

​Relationship YAML with Navigation Directions

​Read-Only Mode

​Permission Decision Flow

​Complete YAML Example

​Best Practices

Permission Architecture

Property-Level Permissions

Permission Flags

Permission Combinations

Configuring Property Permissions in YAML

Basic Example

Mixed Permissions Example

Hiding Sensitive Properties

Built-in Property Permissions

Entity Types and Permission Scoping

Special Entity Types

Navigation Property Permissions

Navigation Direction Properties

Relationship YAML with Navigation Directions

Read-Only Mode

Permission Decision Flow

Complete YAML Example

Best Practices