Relationships - Nextedy Documentation

Structure

Relationships are defined as a top-level array in the data model YAML, alongside domainModelTypes:

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

Each entry connects a source entity type (from) to a target entity type (to), specifies a cardinality, a storage mechanism, a link role, and two navigation properties that allow traversal in both directions.

Relationship Properties

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`	`many-to-many`	Relationship multiplicity: `many-to-one` or `many-to-many`. See Cardinality. Not used by a `TestRecords` relationship.
`storage`	`string`	Required	Where the relationship is read from: `linkedWorkItems` for a work item link, `TestRecords` for the test records of a test case. See Storage.
`linkRole`	`string`	Required for `linkedWorkItems`	Polarion link role ID used to implement this relationship. Must exist in the project’s link role configuration. See Link Roles. A `TestRecords` relationship has no link role.
`direct`	`object`	Required	Forward navigation property configuration (from source to target). See Navigation Properties.
`direct.name`	`string`	Required	Navigation property name for forward traversal. Used in expansion paths and column bindings.
`back`	`object`	Optional	Reverse navigation property configuration (from target back to source). See Navigation Properties.
`back.name`	`string`	Required (if `back` provided)	Navigation property name for reverse traversal.

from/to reference entity type namesThe from and to fields must reference names defined in domainModelTypes — not Polarion work item type IDs. For example, use UserNeed (the entity type name), not user_need (the Polarion type ID).

Every relationship creates navigation properties on the participating entity types. These properties enable:

Expansion paths in sheet source configurations
Column bindings using dot-notation in sheet column definitions
Query traversal across related entity types

Navigation properties are defined using the direct and back objects:

Direction	Object	Created On	Purpose
Forward	`direct`	Source (`from`) entity	Navigate from source to target
Reverse	`back`	Target (`to`) entity	Navigate from target back to source

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

In this example:

UserNeed gains the navigation property chapter (forward, to the Chapter entity)
Chapter gains the navigation property userNeeds (reverse, back to UserNeed entities)

Naming Conventions

Cardinality	Direct Name	Back Name	Rationale
`many-to-one`	Singular (`chapter`)	Plural (`userNeeds`)	Direct points to one target; back returns many sources
`many-to-many`	Plural (`systemRequirements`)	Plural (`userNeeds`)	Both sides are collections

Use camelCase for navigation property namesNavigation property names follow camelCase convention. Use singular names for scalar references and plural names for collection references. This naming directly maps to source expand entries and column binding paths.

Cardinality Options

The cardinality property determines how many entities can participate on each side of the relationship:

Value	From Side	To Side	Direct Property	Back Property
`many-to-one`	Single reference	Collection	Scalar	Collection
`many-to-many`	Collection	Collection	Collection (via association)	Collection (via association)

Cardinality affects three layers of configuration:

Data model — determines navigation property type (scalar vs. collection)
Sheet sources — determines expand pattern (single-level vs. two-level for M:N)
Sheet columns — determines binding syntax and UI behavior (picker vs. child rows)

See Cardinality for complete documentation on each option.

Storage

The storage property specifies how the relationship is persisted in Polarion.

Value	Description
`linkedWorkItems`	Uses Polarion’s native work item link mechanism. Requires `linkRole` to specify which link role implements the association.
`TestRecords`	Reads the records Polarion test runs hold of a test case. Read-only, and takes no `linkRole`. See Test Records Storage.

linkedWorkItems is the storage for links between work itemsEvery relationship between two work item types uses linkedWorkItems. It leverages Polarion’s built-in linked work items infrastructure, which stores relationships as typed links between work items using the configured linkRole.

Link Role Mapping

The linkRole value must correspond to a link role defined in the Polarion project configuration. Common link roles used in data models:

Link Role	Typical Usage
`parent`	Hierarchical parent-child relationships (e.g., `Chapter` to `UserNeed`)
`decomposes`	Decomposition relationships (e.g., `SystemRequirement` to `UserNeed`)
`refines`	Refinement relationships (e.g., `DesignRequirement` to `SystemRequirement`)
`mitigates`	Risk relationships (e.g., `RiskControl` to `Hazard`)
`verifies`	Verification relationships (e.g., test cases to requirements)

See Link Roles for detailed documentation on configuring and using Polarion link roles.

Test Records Storage

storage: TestRecords relates a test record type to the type it is read beneath. It is not a link: no linkRole and no cardinality apply, and the relationship can be written from either end.

relationships:
  - from: TestCase
    to: TestRecord
    storage: TestRecords

Other end of the relationship	Navigation properties created
A work item type (the test case)	On the test case, a collection of its records. On the record, a reference to its test case. Unnamed, they take their names from the types: `testRecords` and `testCase` for types named `TestRecord` and `TestCase`.
A test run type	On the record, a reference to its test run, named after the test run type: `testRun` for a type named `TestRun`. A name for the test run’s end is rejected, because a test run does not list its records.

direct.name and back.name replace the derived names. The record’s key to the other end is the navigation name followed by Id, such as testRunId. As on any relationship, direct names the navigation on the from type and back the one on the to type.
One end must be a test record type and the other a work item type or a test run type. Any other pairing is rejected with an error that names both types.
If from or to names a type that domainModelTypes does not define, that name becomes the test record type, with all of its properties. A record type that the model relates to no test run is related to one automatically — the model’s own test run type, or a type named TestRun when it has none.

See Test Record and Test Run Types for the types and Test Records for which records a sheet loads.

Permission Control

Relationships support permission flags that control CRUD operations through the sheet:

Property	Type	Default	Description
`createable`	`boolean`	See application	Whether new relationship instances can be created through the sheet.
`readable`	`boolean`	See application	Whether relationship instances are visible in queries and the sheet UI.

Verify in applicationPermission flag behavior may depend on your Polarion project permissions and Powersheet version. Test in your environment to confirm the exact behavior.

Navigation property names created by relationships flow directly into sheet configuration. The three configuration layers — data model, sheet sources, and sheet columns — are connected through these navigation property names. The cardinality of the relationship determines the expand pattern and column binding syntax.

Many-to-One (N:1)

A scalar reference from source to a single target entity. Uses the direct navigation property. Data model:

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

Source configuration:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

Column bindings:

columns:
  title:
    title: Title
    hasFocus: true
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true

chapter — single-value reference picker (scalar navigation property, N:1)
chapter.title — read-only display of the referenced Chapter’s title via dot-notation

One-to-Many (1:N)

A collection of child entities accessible from a parent. Uses the back navigation property (reverse side of a many-to-one relationship). Source configuration:

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

Column bindings:

columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: Title
    hasFocus: true

userNeeds — expands into child rows, creating a new level in the sheet hierarchy
No dot-notation needed; the expand directly opens the child level

Many-to-Many (M:N)

Collections on both sides, navigated through an association entity. Uses a two-level expand. Data model:

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

Source configuration:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

Column bindings:

columns:
  title:
    title: Title
    hasFocus: true
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true

M:N relationships use an association entity between the two types
Source expand is two levels: systemRequirements (association) then systemRequirement (target entity)
Column binding uses dot-notation: systemRequirements.systemRequirement
Acts as a multi-item reference picker in the sheet UI

Cardinality Summary

Cardinality	Model	Source Expand	Column Binding	UI Behavior
N:1	`cardinality: many-to-one`, `direct.name: chapter`	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N	Reverse of N:1, `back.name: userNeeds`	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
M:N	`cardinality: many-to-many`, `back.name: systemRequirements`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

Complete YAML Example

A full data model demonstrating all relationship cardinalities across the standard RTM entity 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:

  Hazard:
    polarionType: hazard
    properties:
      description:

  RiskControl:
    polarionType: riskControl
    properties:
      description:

relationships:
  # N:1 -- each UserNeed belongs to one Chapter
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  # M:N -- UserNeeds decompose into SystemRequirements
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

  # M:N -- SystemRequirements refine into DesignRequirements
  - from: DesignRequirement
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: designRequirements

  # M:N -- Hazards linked to DesignRequirements
  - from: Hazard
    to: DesignRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: hazards

  # M:N -- RiskControls mitigate Hazards
  - from: RiskControl
    to: Hazard
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: hazards
    back:
      name: riskControls

This model creates a full traceability chain: Chapter > UserNeed > SystemRequirement > DesignRequirement > Hazard > RiskControl. Each relationship uses linkedWorkItems storage with an appropriate Polarion link role, and defines both direct and back navigation properties for bidirectional traversal.

Cardinality — detailed rules for each cardinality option
Link Roles — configuring Polarion link roles for relationships
Data Model Types — entity type definitions referenced by from and to
Navigation Directions — how direction properties work internally
Binding Syntax — using navigation properties in column bindings
Sources — configuring expand paths that use navigation properties
Constraints — filtering constraints applied to entity types in relationships
Test Records — how the TestRecords storage brings test results into a sheet

​Structure

​Relationship Properties

​Navigation Properties

​Naming Conventions

​Cardinality Options

​Storage

​Link Role Mapping

​Test Records Storage

​Permission Control

​Navigation Properties in Binding Paths

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​Cardinality Summary

​Complete YAML Example

​Related Pages

Structure

Relationship Properties

Navigation Properties

Naming Conventions

Cardinality Options

Storage

Link Role Mapping

Test Records Storage

Permission Control

Navigation Properties in Binding Paths

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

Cardinality Summary

Complete YAML Example

Related Pages