Link Roles - Nextedy Documentation

Link Role Property Reference

Name	Type	Default	Description
`linkRole`	`string`	None (required)	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 Data Model and Polarion

The link role is the bridge between the data 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.

Where `linkRole` Appears in Configuration

The linkRole property is specified on each entry in the relationships array of the data model YAML. It sits alongside the structural properties (from, to, cardinality, storage) and the navigation direction definitions (direct, back).

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

Context Within the Relationship

Property	Type	Default	Description
`from`	`string`	Required	Source entity type name. Must match a key in `domainModelTypes`.
`to`	`string`	Required	Target entity type name. Must match a key in `domainModelTypes`.
`cardinality`	`string`	Required	Relationship multiplicity. See Cardinality.
`storage`	`string`	Required	Must be `linkedWorkItems` when using `linkRole`.
`linkRole`	`string`	Required	Polarion link role ID.
`direct`	`object`	Required	Forward navigation property definition. See Navigation Directions.
`direct.name`	`string`	Required	Name of the navigation property on the `from` entity.
`back`	`object`	Optional	Reverse navigation property definition.
`back.name`	`string`	Required (if `back` provided)	Name of the navigation property on the `to` entity.

Link Role and Relationship Direction

A Polarion link role is inherently directional: it has a “from” side and a “to” side. The data 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.

Link Role and Cardinality Interaction

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.

Reusing the Same Link Role

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.

Permission Control on Relationships

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.

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

For detailed property-level permission configuration, see Permissions.

Validation Rules

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.

Complete YAML Example

A minimal data model demonstrating linkRole across different relationship types:

domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      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 model demonstrates two different link roles:

parent for the hierarchical UserNeed to Chapter relationship (many-to-one)
decomposes for the traceability SystemRequirement to UserNeed relationship (many-to-many)

Each relationship uses storage: linkedWorkItems and defines both direct and back navigation properties for bidirectional traversal.

Relationships — complete relationship definition reference
Cardinality — relationship multiplicity options and their effects
Navigation Directions — direct and back navigation property definitions
Constraints — filtering constraints on navigation directions
Permissions — CRUD permission controls on relationships and properties
Polarion Type Mapping — entity type to work item type mapping
Binding Syntax — using navigation properties in column bindings
Sources — configuring expand paths that reference navigation properties

​Link Role Property Reference

​How Link Roles Bridge the Data Model and Polarion

​Where linkRole Appears in Configuration

​Context Within the Relationship

​Link Role and Relationship Direction

​Link Role and Cardinality Interaction

​Reusing the Same Link Role

​Permission Control on Relationships

​Validation Rules

​Complete YAML Example

​Related Pages

Link Role Property Reference

How Link Roles Bridge the Data Model and Polarion

Where `linkRole` Appears in Configuration

Context Within the Relationship

Link Role and Relationship Direction

Link Role and Cardinality Interaction

Reusing the Same Link Role

Permission Control on Relationships

Validation Rules

Complete YAML Example

Related Pages