Expand Navigation Properties - Nextedy Documentation

Prerequisites

Before configuring expansion paths, ensure you have:

A data model with entity types and relationships defined
A sheet configuration with at least one source
Familiarity with writing entity queries

How Expansion Connects Model, Source, and Columns

The three configuration layers — data model, sheet sources, and sheet columns — connect through navigation property names. The data 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.

Shared Data Model for Examples

All examples below use this data 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.

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

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

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.

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.

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

Cardinality	Model definition	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 grid level)
M:N	`cardinality: many-to-many`, `back.name: systemRequirements`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

Common Pitfalls

Property names must exactly match the direct.name or back.name values in your data 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:

Open the Polarion document that uses this sheet configuration
You should now see nested rows under each parent entity corresponding to the expanded navigation properties
For N:1 expansions, verify the reference picker column shows the correct related entity
For 1:N expansions, verify child rows appear beneath each parent
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 data model and confirm that linked work items exist in Polarion for the relationship.

​Prerequisites

​How Expansion Connects Model, Source, and Columns

​Shared Data Model for Examples

​Cardinality Quick Reference

​Common Pitfalls

​Verify Your Configuration

​See Also

Prerequisites

How Expansion Connects Model, Source, and Columns

Shared Data Model for Examples

Cardinality Quick Reference

Common Pitfalls

Verify Your Configuration

See Also