Configure Many-to-Many Relationships

Prerequisites

Before you begin, make sure you have:

An existing data model with at least two entity types defined in domainModelTypes
A Polarion link role created for the relationship (e.g., decomposes, verifies)
Access to Administration > Nextedy Powersheet > Data Models

How M:N Relationships Work

Many-to-many relationships in Powersheet use an association entity pattern. Unlike simpler cardinalities (N:1 or 1:N), the M:N relationship introduces an intermediate association layer between the two entity types. This affects how you configure sources and columns:

The source expand traverses two levels — first the association collection, then the target entity — and columns use two-level dot-notation to bind through the association to the target.

Define Both Entity Types

Ensure both sides of the relationship are defined in your data model under domainModelTypes. Each entity type must have a polarionType mapping to the corresponding Polarion work item type:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

Add the Many-to-Many Relationship

In the relationships section of your data model, add a relationship with cardinality: many-to-many. Define both the direct and back navigation property names:

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

Key properties:

Property	Purpose	Example
`from`	Source entity type (must match a `domainModelTypes` key)	`SystemRequirement`
`to`	Target entity type (must match a `domainModelTypes` key)	`UserNeed`
`cardinality`	Relationship multiplicity	`many-to-many`
`storage`	How links are persisted in Polarion	`linkedWorkItems`
`linkRole`	Polarion link role ID (must exist in project config)	`decomposes`
`direct.name`	Forward navigation property (from source to target)	`userNeeds`
`back.name`	Reverse navigation property (from target to source)	`systemRequirements`

Use plural camelCase names for M:N navigation properties (e.g., userNeeds, systemRequirements). The association entity Powersheet creates automatically derives its singular form from this name. If you use a singular name, the two-level dot-notation in columns will not resolve correctly.

Configure the Source Expansion

In your sheet configuration, set up a two-level expand in the sources section. The first level expands to the association collection, and the second level expands to the actual target entity:

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

This two-level expand is what distinguishes M:N from other cardinalities:

Level 1 (systemRequirements) — navigates to the association entity collection
Level 2 (systemRequirement) — navigates from each association to the actual target entity

The second-level expand name (systemRequirement, singular) is derived automatically from the navigation property name (systemRequirements, plural). You do not define this singular name in the data model — Powersheet generates it from the association entity pattern.

Configure Columns with Dot-Notation

In the columns section of your sheet configuration, use the two-level dot-notation to bind through the association entity to the target:

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

The column bindings follow this pattern:

systemRequirements.systemRequirement — a multi-item reference picker that lets users link and unlink target entities through the association
systemRequirements.systemRequirement.title — a read-only display of the linked entity’s title property (extend the dot-notation with any target property)

The list block on the reference picker column configures the search dialog:

search — which fields to search when filtering candidates
createNew: true — allows creating new target entities directly from the picker

When a sheet has two different entity types linked to the same parent (e.g., design outputs and design verifications both linked to system requirements), the second linked column must declare multiItem: true in the sheet configuration. Without this flag, only the first linked column renders correctly. This is a common first-time setup issue.

Verify the Configuration

After saving your data model and sheet configuration:

Open a Polarion LiveDoc or Wiki page that uses this sheet configuration
Expand a row in the sheet — you should see the linked entities appear as child items through the association
Click the reference picker cell to open the search dialog and verify you can link and unlink target entities
Confirm that read-only columns (e.g., systemRequirements.systemRequirement.title) display the correct values from linked entities

You should now see M:N relationships rendered in your sheet with a multi-item reference picker. Each source entity can link to multiple targets, and each target can be linked from multiple sources.

Cardinality Comparison

For reference, here is how M:N compares to other cardinality types across the three configuration layers:

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

Powersheet creates and manages the intermediate association entities for M:N relationships. When you unlink two entities, Powersheet removes the association but preserves both linked entities. Deleting an entity removes all its association links as well.

​Prerequisites

​How M:N Relationships Work

​Cardinality Comparison

​See Also

Prerequisites

How M:N Relationships Work

Cardinality Comparison

See Also