Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • An existing domain 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 > Domain 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: diagram 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.

​
Step 1: Define Both Entity Types

Ensure both sides of the relationship are defined in your domain 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:

​
Step 2: Add the Many-to-Many Relationship

In the relationships section of your domain 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:
PropertyPurposeExample
fromSource entity type (must match a domainModelTypes key)SystemRequirement
toTarget entity type (must match a domainModelTypes key)UserNeed
cardinalityRelationship multiplicitymany-to-many
storageHow links are persisted in PolarionlinkedWorkItems
linkRolePolarion link role ID (must exist in project config)decomposes
direct.nameForward navigation property (from source to target)userNeeds
back.nameReverse 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.

​
Step 3: 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
    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 domain model — Powersheet generates it from the association entity pattern.

​
Step 4: 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.

​
Step 5: Verify the Configuration

After saving your domain model and sheet configuration:
  1. Open a Polarion LiveDoc or Wiki page that uses this sheet configuration
  2. Expand a row in the sheet — you should see the linked entities appear as child items through the association
  3. Click the reference picker cell to open the search dialog and verify you can link and unlink target entities
  4. 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:
CardinalityModelSource expandColumn bindingUI behavior
N:1cardinality: many-to-one, direct.name: chapter- name: chapterchapter, chapter.titleSingle-value reference picker
1:NReverse of N:1, back.name: userNeeds- name: userNeedsuserNeedsChild rows (new sheet level)
M:Ncardinality: many-to-many, back.name: systemRequirements- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-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.

​
See Also

Sources: Relationship.java, DomainModelV2.java, whole_rtm.template.yaml