Configure a Relationship - Nextedy Documentation

Prerequisites

Both entity types must already exist in your domainModelTypes section
A Polarion link role must be configured in your project for the relationship
Access to the data model YAML file in your project’s SVN repository

Identify the Relationship

Determine the source and target entity types, the cardinality, and which Polarion link role to use.

Decision	Question	Example
Source (`from`)	Which entity initiates the relationship?	`UserNeed`
Target (`to`)	Which entity is being referenced?	`SystemRequirement`
Cardinality	How many targets per source?	`many-to-many`
Link role	Which Polarion link role stores this?	`decomposes`

Add the Relationship to Your Data Model

Add an entry to the relationships array in your data model YAML. Each relationship uses direct and back objects to define the forward and reverse navigation property names.

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

Relationship Properties

Property	Type	Required	Description
`from`	string	Yes	Source entity type name. Must match a `domainModelTypes` key exactly.
`to`	string	Yes	Target entity type name. Must match a `domainModelTypes` key exactly.
`cardinality`	string	Yes	Multiplicity: `many-to-one`, `one-to-many`, or `many-to-many`. See the Cardinality reference for supported values.
`storage`	string	Yes	Persistence mechanism. Use `linkedWorkItems` for Polarion link-based relationships.
`linkRole`	string	Yes	Polarion link role ID. Must exist in your project’s link role configuration.
`direct`	object	Yes	Forward navigation property. Contains a `name` field used to traverse from source to target.
`back`	object	Yes	Reverse navigation property. Contains a `name` field used to traverse from target back to source.

The from and to values must be data model entity type names (e.g., UserNeed), not Polarion work item type IDs (e.g., user_need). Using the Polarion type ID instead of the entity type name causes connection errors that are difficult to diagnose.

Choose Navigation Property Names

The direct.name and back.name values define how you traverse the relationship in sheet configurations, expansion paths, and column bindings. Follow these naming conventions:

Forward (direct.name): Use the plural camelCase form of the target entity — e.g., systemRequirements when the target is SystemRequirement
Reverse (back.name): Use the plural camelCase form of the source entity — e.g., userNeeds when the source is UserNeed

For many-to-one relationships, the forward navigation property should be singular (scalar), since it references exactly one target:

# many-to-one: each UserNeed belongs to one Chapter
- from: UserNeed
  to: Chapter
  cardinality: many-to-one
  storage: linkedWorkItems
  linkRole: parent
  direct:
    name: chapter          # singular -- scalar reference
  back:
    name: userNeeds        # plural -- collection of children

The cardinality and navigation property name together determine what the sheet renders. A singular direct.name like chapter produces a single-value reference picker. A plural back.name like userNeeds produces expandable child rows or a multi-item picker, depending on how you bind columns.

Configure by Cardinality

The cardinality you choose affects how sources expand and how columns bind. Use the following patterns.

Many-to-One (N:1)

Each source entity references exactly one target. The direct.name is singular.

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

# Sheet source -- expand the scalar reference
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

# Sheet columns -- dot-notation for target properties
columns:
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true

One-to-Many (1:N)

Each source entity has multiple children. This is the reverse side of a many-to-one relationship, using the back.name collection property.

# Sheet source -- expand the collection
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

# Sheet columns -- collection expands into child rows
columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: User Need
    hasFocus: true

Many-to-Many (M:N)

Both sides can reference multiple entities. The expand uses an association entity pattern with two levels of expansion.

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

# Sheet source -- two-level expand through association
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

# Sheet columns -- dot-notation through association
columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true

When a sheet has two entity types linked to the same parent (e.g., design outputs and design verifications both linked to system requirements), the second linked column must be declared with multiItem: true in the sheet configuration. Omitting this property causes the second column to silently fail during initial setup.

Verify the Relationship

After saving the data model YAML:

Open a Powersheet that uses this data model
Expand the source entity to confirm child rows or linked items appear
Check that column bindings resolve correctly — the referenced entity properties should display their values

If the sheet does not load or shows errors, verify:

The from and to values match entity type names in domainModelTypes exactly (case-sensitive)
The linkRole value exists in your Polarion project’s link role configuration
The sources.model property in your sheet configuration matches your custom data model name

You should now see the related entities navigable through expansion paths in your sheet, with columns displaying the linked entity properties.

The sources.model property in your sheet configuration must match the data model name — not the default rtm. This is a common first-time setup mistake that causes model connection errors.

Quick Reference

Cardinality	`direct.name`	`back.name`	Source Expand	Column Binding	UI Behavior
N:1	`chapter` (singular)	`userNeeds` (plural)	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N	reverse of N:1	`userNeeds` (plural)	`- name: userNeeds`	`userNeeds`	Expandable child rows
M:N	`userNeeds` (plural)	`systemRequirements` (plural)	Two-level: `systemRequirements` then `systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

​Prerequisites

​Relationship Properties

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​Quick Reference

​See Also

Prerequisites

Relationship Properties

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

Quick Reference

See Also