Skip to main content
See also: Properties | Domain Model Types | Relationships

​
Permission Architecture

diagram Powersheet permissions operate at two distinct levels within the domain model YAML:
  1. Property-level — the readable and updatable flags on each property definition within an entity type
  2. 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 domain model YAML under each entity type’s properties map.

​
Permission Flags

NameTypeDefaultDescription
readablebooleantrueControls 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.
updatablebooleantrueControls 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

readableupdatableResult
truetrueProperty is visible and editable (default behavior).
truefalseProperty is visible but read-only. Users can see the value but cannot modify it. Useful for computed fields, audit stamps, or reference data.
falsetrueProperty is hidden from the client entirely. The updatable flag has no practical effect since the property is not transmitted.
falsefalseProperty 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 — 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:
PropertyTypical readableTypical updatableNotes
idtruefalseWork item identifier. System-managed, never user-editable.
titletruetrueWork item title. Usually editable.
outlineNumbertruefalsePosition in document hierarchy. Automatically managed by Polarion.
descriptiontruetrueStandard text property. Editable by default.
severitytruetrueEnumeration property. Editable by default.
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 TypePurposePermission Notes
DocumentBuilt-in entity for Polarion LiveDocsSupports mixed permission settings on properties. Useful for controlling which document-level fields are editable.
ChapterEntity type mapped to Polarion heading work item typeProperties are typically read-only since headings are structural elements.
ProjectBuilt-in entity for Polarion project metadataMinimal property definitions. Permissions rarely customized.
Relationships in the domain 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.
NameTypeDefaultDescription
direct.namestring(required)Name of the forward navigation property on the source entity.
back.namestring(optional)Name of the reverse navigation property on the target entity.
createablebooleanSee applicationControls whether new relationship instances can be created through this navigation property.
readablebooleanSee applicationControls whether the navigation property is visible in queries and data payloads.

​
Relationship YAML with Navigation Directions

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.
ConditionEffect
Configuration isReadOnly is trueEntire sheet is read-only.
User is viewing a historical revisionSheet is read-only (revisions are immutable).
License status is INVALIDRestricted 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:
CheckConditionResult
1. Global read-onlyisReadOnly config, historical revision, or invalid licenseAll fields read-only
2. Property readablefalseProperty excluded from data payload
3. Property updatablefalseProperty visible but not editable
4. Column isReadOnlytrueColumn 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 domain 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 — visible but read-only (auto-managed by Polarion)
  • 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

PracticeRecommendation
Sensitive dataUse readable: false to prevent transmission to the client. Do not rely on column visibility alone.
Audit fieldsSet updatable: false on fields like id, outlineNumber, and timestamp fields that should not be manually edited.
Progressive disclosureUse Views to control which columns are visible in different analysis perspectives, rather than using readable: false which removes data access entirely.
Consistent namingKeep property names aligned across entity types when they serve the same purpose (e.g., severity on both UserNeed and SystemRequirement).
Testing permissionsVerify 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.
Sources: DomainModelTypeV2.java, Relationship.java, UserPermissions.d.ts, DomainModelV2.java