Skip to main content

​
Prerequisites

Before configuring expansion paths, ensure you have:

​
How Expansion Connects Model, Source, and Columns

The three configuration layers — domain model, sheet sources, and sheet columns — connect through navigation property names. The domain model defines entity types and relationships. Sources define how to query and expand those relationships. Columns define how to display the resulting data. The cardinality of a relationship determines the expand pattern and the column binding syntax. diagram

​
Shared Domain Model for Examples

All examples below use this domain model: 
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
Each relationship defines a direct and back navigation direction. The direct side navigates from the from entity toward the to entity. The back side navigates in reverse.

​
Step 1: Expand a Many-to-One Relationship (N:1)

Scenario: Each UserNeed belongs to exactly one Chapter. Use the direct direction — the navigation property chapter (singular, scalar). Add the expand to your source configuration: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
Then bind columns to the expanded entity: 
columns:
  title:
    title: Title
    hasFocus: true
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true
  • chapter — renders a single-value reference picker (scalar navigation property)
  • chapter.title — displays the referenced Chapter’s title as a read-only column

​
Step 2: Expand a One-to-Many Relationship (1:N)

Scenario: Each Chapter has multiple child UserNeed items. Use the back direction — the navigation property userNeeds (plural, collection). 
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: Title
    hasFocus: true
  • userNeeds — expands into child rows in the sheet, creating a new grid level
  • No dot-notation is needed; the expand directly opens the child level beneath each parent row

​
Step 3: Expand a Many-to-Many Relationship (M:N)

Scenario: UserNeed items are linked to multiple SystemRequirement items and vice versa. Many-to-many relationships use an association entity between the two types. The source expand requires two levels — first to the association entity, then through to the target entity: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
Column bindings use dot-notation to traverse both levels: 
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
  • systemRequirements — navigates to the association entity
  • systemRequirements.systemRequirement — navigates through to the target SystemRequirement entity, acting as a multi-item reference picker
  • systemRequirements.systemRequirement.title — displays the target entity’s title
A many-to-many relationship always uses an intermediate association entity. If you only expand one level (- name: systemRequirements without the nested - name: systemRequirement), you will see the association entities rather than the target items.

​
Step 4: Build Deep Multi-Level Hierarchies

You can nest expansion paths to any depth. For a full requirements traceability matrix (RTM), chain expansions across multiple entity types: 
sources:
  - id: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
Each nested level adds another tier of child rows in the sheet. Columns at each level bind to their respective entity type properties.
Each expansion level triggers additional queries to fetch related entities. For large datasets, limit expansion to 2-3 levels and consider using query optimization techniques to maintain performance.

​
Step 5: Apply Document-Scoped Expansion

Constrain expanded entities to the current document by adding constraints to the source: 
sources:
  - id: main
    query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
The applyCurrentDocumentTo constraint filters expanded SystemRequirement entities to only include those from the same Polarion document context. This is useful when your document contains a scoped subset of work items and you want expansions to respect that boundary.

​
Cardinality Quick Reference

CardinalityModel definitionSource 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 grid level)
M:Ncardinality: many-to-many, back.name: systemRequirements- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker

​
Common Pitfalls

Property names must exactly match the direct.name or back.name values in your domain model. A misspelled property name causes the expansion to silently return no related entities. Verify names in Administration > Nextedy POWERSHEET > Models.
The direct direction follows the relationship as declared (from the from type to the to type), while back reverses it. Using the wrong direction returns an empty result set. Check the relationship definition to confirm which navigation property name belongs to which direction.
When displaying properties from an expanded entity (e.g., chapter.title), set isReadOnly: true on the column. This prevents users from attempting to edit values that belong to a different entity type.
For a column binding like systemRequirements.systemRequirement.title to display data, the source must include a matching expand entry with name: systemRequirements and nested name: systemRequirement. Missing or mismatched expansions result in empty columns.

​
Verify Your Configuration

After saving your sheet configuration:
  1. Open the Polarion document that uses this sheet configuration
  2. You should now see nested rows under each parent entity corresponding to the expanded navigation properties
  3. For N:1 expansions, verify the reference picker column shows the correct related entity
  4. For 1:N expansions, verify child rows appear beneath each parent
  5. For M:N expansions, verify the dot-notation columns display target entity properties through both expand levels
If no expanded rows appear, check the navigation property names against your domain model and confirm that linked work items exist in Polarion for the relationship.

​
See Also

Source Code
  • PolarionQueryProcessor.java
  • DatabridgeMetadata.java
  • PowersheetConfig.d.ts