Skip to main content

​
How Expansion Works

When you define a source query with a from entity type, only that entity type’s properties are loaded by default. To include related entities (e.g., SystemRequirement items linked to a UserNeed), you define expansion paths that follow navigation properties from the domain model. Each expansion path tells the query engine to fetch related entities along a defined relationship and include them as nested rows in the sheet. diagram

​
Step 1: Add a Single-Level Expansion

In the sources section of your sheet configuration YAML, add an expand array to the source: 
sources:
  - id: main
    title: User Needs
    model: rtm-model
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
The name property must match a navigation property defined in your domain model for the UserNeed entity type. The title is displayed as a label in the sheet header for the expanded section.

​
Step 2: Add Nested (Multi-Level) Expansion

For deeper hierarchies, nest expand entries within each other: 
sources:
  - id: main
    title: RTM
    model: rtm-model
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
This creates a three-level hierarchy: UserNeed > SystemRequirement > DesignRequirement. Each level appears as nested rows in the sheet, with columns bound to the appropriate entity type at each level.

​
Step 3: Expand Many-to-Many Relationships

For many-to-many relationships that use association entities, use a two-level dot-notation path in your column bindings: 
columns:
  systemRequirements.systemRequirement.title:
    title: Linked Sys Req
    width: 200
    multiItem: true
The first segment (systemRequirements) navigates to the association entity, and the second segment (systemRequirement) navigates through to the target entity. Set multiItem: true on columns that display collections.
Every navigation property name in the expand configuration must exist in the domain model. If you reference a navigation property that is not defined (or misspell it), the expansion silently returns no related entities. Verify property names in Administration > Nextedy POWERSHEET > Models.

​
Step 4: Use Column Bindings with Expanded Entities

Columns that display properties from expanded entities use dot-notation binding paths: 
columns:
  title:
    title: User Need
    width: 250
  systemRequirements.systemRequirement.title:
    title: Sys Req Title
    width: 200
  systemRequirements.systemRequirement.severity:
    title: Severity
    width: 100
The binding path follows the same navigation structure as the expansion path. The column is displayed at the appropriate hierarchy level in the sheet.
For a column binding like systemRequirements.systemRequirement.title to display data, the source must include an expand entry with name: systemRequirements. Missing expansions result in empty columns.

​
Step 5: Apply Document-Scoped Expansion

You can constrain expanded entities to the current document by adding constraints to the source: 
sources:
  - id: main
    model: rtm-model
    query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: systemRequirements
        title: System Requirements
The applyCurrentDocumentTo constraint filters expanded SystemRequirement entities to only include those from the same Polarion document context.

​
Verification

After saving the configuration and opening the document:
  1. You should now see parent entities with expandable nested rows for each expanded navigation property
  2. Column bindings with dot-notation paths should display values from the related entity types
  3. Multi-level expansions should render as a hierarchical tree in the sheet

​
See Also

Source Code
  • PolarionQueryProcessor.java
  • ExpandClause.java
  • powersheet.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_composing.template.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml