Polarion link role ID that implements the relationship. Must exactly match a link role defined in the Polarion project configuration. Required when storage is linkedWorkItems.
The linkRole value must exactly match a link role ID defined in your Polarion project under Administration > Work Item Link Roles. A mismatch causes the relationship to fail silently — no linked items will appear in the sheet, and no error is displayed to the user.
How Link Roles Bridge the Domain Model and Polarion
The link role is the bridge between the domain model’s abstract relationship definition and Polarion’s concrete work item linking infrastructure. At runtime:
Read operations: Powersheet queries Polarion for work items connected via the specified link role, then populates the sheet with the results.
Write operations: When users create or remove links in the sheet, Powersheet uses the same link role to persist changes to Polarion.
The linkRole property is specified on each entry in the relationships array of the domain model YAML. It sits alongside the structural properties (from, to, cardinality, storage) and the navigation direction definitions (direct, back).
A Polarion link role is inherently directional: it has a “from” side and a “to” side. The domain model’s from/to entity types and direct/back navigation properties align with this directionality.
Aspect
direct Direction
back Direction
Navigation property placed on
from entity type
to entity type
Traversal direction
Source to target
Target back to source
Polarion link side
Forward link
Reverse (backlink)
The isBacklink flag is managed internally by the system. When Powersheet processes a back direction, it internally flags the reverse traversal so that Polarion queries use the correct link direction.
A single linkRole value serves both the direct and back navigation properties. You do not need to define separate link roles for forward and reverse traversal. Powersheet handles the directionality automatically based on the direct/back configuration.
The linkRole itself does not encode cardinality — it is a simple identifier pointing to a Polarion link role. Cardinality is controlled separately by the cardinality property. However, the combination of linkRole and cardinality determines the runtime behavior:
Cardinality
Direct Property
Back Property
Source Expand Pattern
Column Binding
many-to-one
Scalar (single entity)
Collection
- name: chapter
chapter, chapter.title
one-to-many
Collection
Scalar
- name: userNeeds
userNeeds (child rows)
many-to-many
Collection (via association)
Collection (via association)
Two levels: - name: systemRequirements then - name: systemRequirement
systemRequirements.systemRequirement
See Cardinality for the full reference on each value and its effects across model, source, and column layers.
A single Polarion link role can appear in multiple relationships. This is common when the same semantic relationship type applies to different entity type pairs.
relationships: # decomposes links UserNeed to SystemRequirement - from: SystemRequirement to: UserNeed cardinality: many-to-many storage: linkedWorkItems linkRole: decomposes direct: name: userNeeds back: name: systemRequirements # decomposes also links SystemRequirement to DesignRequirement - from: DesignRequirement to: SystemRequirement cardinality: many-to-many storage: linkedWorkItems linkRole: decomposes direct: name: systemRequirements back: name: designRequirements
In this example, the decomposes link role is reused across two relationship definitions. Each relationship has its own from/to pairing and its own navigation property names, but they share the same underlying Polarion link role.
When reusing a link role across multiple relationships, ensure the navigation property names (direct.name and back.name) do not collide on the same entity type. Each entity type must have uniquely named navigation properties.
Relationships support permission flags that control whether the link role’s operations are available through the sheet:
Property
Type
Default
Description
createable
boolean
See application
Controls whether new links using this role can be created through the sheet.
readable
boolean
See application
Controls whether links using this role are visible in queries and the sheet UI.
Individual navigation properties (direct and back) can also have independent permission settings, allowing fine-grained control over which direction of a link role is editable or visible.
Powersheet enforces specific rules when processing linkRole values:
Rule
Detail
Required
Every relationship with storage: linkedWorkItems must have a linkRole value.
String match
The value must exactly match a link role ID in the Polarion project configuration. The match is case-sensitive.
Entity type references
The from and to fields must reference entity type names defined in domainModelTypes, not Polarion work item type IDs.
Navigation property uniqueness
Within a single entity type, no two navigation properties can share the same name. This applies even when different link roles are used.
Link role IDs in Polarion are case-sensitive. A linkRole: Refines value will not match a Polarion link role with ID refines. Always verify the exact casing in Administration > Work Item Link Roles.
