Skip to main content

​
Overview

Expansion paths are the mechanism that transforms normalized Polarion work item hierarchies into denormalized grid layouts. Each expansion level adds columns to the PowerSheet or Risksheet, enabling progressive disclosure of related entities while maintaining context. Key Characteristics:
  • Relationship-Based Navigation — Uses RTM link roles (verifies, validates, refines, mitigates, assesses) to traverse from source entity to target entities
  • Multi-Level Traversal — Supports chains of 2+ levels (requirement → test → evidence → attachment)
  • Entity-Scoped Filtering — Restricts expansion to specific entity types via document filters or entity factory constraints
  • Denormalized Output — Creates separate rows for each combination of parent + expanded entity
  • Progressive Disclosure — Column groups can collapse to key fields, hiding expanded detail until needed

​
Expansion Path Syntax

Expansion paths use dot notation to reference nested relationships: 
<EntityType>.<linkRole>.<TargetEntityType>
Or for multi-level expansions: 
<EntityType>.<linkRole1>.<IntermediateEntity>.<linkRole2>.<FinalEntity>
Example: DesignRequirement.verificationTestCases.VerificationTestCase.externalReferences.ExternalReference This expands design requirements through their verification test cases to show external evidence artifacts.

​
Single-Level Expansion Paths

A single-level expansion connects one entity type to another via a direct link role.
Path NotationSource EntityLink RoleTarget EntityUse Case
SystemRequirement.verifies.TestCaseSystemRequirementverifiesTestCaseShow test cases that verify each requirement
CustomerRequirement.refines.SystemRequirementCustomerRequirementrefinesSystemRequirementShow derived system requirements
Function.failureModes.FailureModeFunctionfailureModesFailureModeShow failure modes per function
Characteristic.assesses.FailureModeCharacteristicassessesFailureModeShow design characteristics that mitigate failure modes
FailureMode.mitigates.RiskControlFailureModemitigatesRiskControlShow risk controls linked to failure modes

​
Properties Table: Single-Level Expansion

PropertyTypeExampleDescription
sourceEntitystringSystemRequirementWork item type that serves as expansion starting point
linkRolestringverificationTestCasesRTM link role name connecting source to target
targetEntitystringVerificationTestCaseWork item type reached through the link role
cardinalityenum1:NRelationship multiplicity: 1:1 (single target) or 1:N (multiple targets per source)
documentFilterobject{module: "Testing/DesignVerificationSpecification"}Optional: restrict target entities to specific document path
collapsedbooleantrueWhether the expansion column group collapses by default in UI
collapseTostringtitleField name to show when column group is collapsed
colorSchemestringorangeVisual color for expanded columns: blue, orange, green, red, purple

​
Multi-Level Expansion Paths

Multi-level expansions chain 2+ link role traversals, enabling complex traceability chains across the V-model.

​
Two-Level Expansion Example

Path: DesignRequirement.verificationTestCases.VerificationTestCase.externalReferences.ExternalReference This creates three visual layers in PowerSheet:
  1. Design requirements (source)
  2. Linked verification test cases (first expansion)
  3. External evidence artifacts linked to test cases (second expansion)
Column Structure: 
[Design Req ID] [Design Req Title] | [Test Case ID] [Test Case Title] | [Evidence Type] [Evidence URL]
When users expand a design requirement row, they see all linked test cases. When they expand a test case sub-row, they see all evidence artifacts for that test case.

​
Three-Level Expansion Example

Path: SystemRequirement.verifies.TestCase.validates.ExternalReference.documents.Document This traverses through:
  1. System requirements (source)
  2. Test cases that verify requirements (level 1)
  3. External reference evidence (level 2)
  4. Related documents (level 3)
PowerSheet and Risksheet configurations support up to 3 expansion levels deep. Deeper chains impact performance and readability. For very deep traceability, use navigation or reports instead of nested expansions.

​
Multi-Level Expansion Configuration

When configuring multi-level expansions in PowerSheet YAML or Risksheet JSON: 
columnGroups:
  - id: design_reqs
    title: Design Requirements
    sourceEntity: DesignRequirement
    columns:
      - field: objectId
      - field: title
      - field: description
    
  - id: verification_tests
    title: Verification Test Cases
    sourceEntity: VerificationTestCase
    parentExpansion: design_reqs.verificationTestCases
    columns:
      - field: objectId
      - field: title
      - field: status
    collapseTo: title
    
  - id: evidence
    title: Evidence Artifacts
    sourceEntity: ExternalReference
    parentExpansion: verification_tests.externalReferences
    columns:
      - field: attachmentName
      - field: url
    collapseTo: attachmentName
Each column group specifies its parentExpansion to establish the chain. The system builds the complete traversal path by concatenating all parent relationships.

​
Expansion Path Architecture Diagram

diagram

​
Common Expansion Path Patterns

​
V-Model Verification Pattern

The V-model verification chain spans requirements through test cases to evidence:
PatternPathDocument TypesUse
System VerificationSystemRequirement.verifies.VerificationTestCase.externalReferences.ExternalReferenceSRS + System Verification Spec + EvidenceVerify system requirements are tested
Design VerificationDesignRequirement.verifies.VerificationTestCase.externalReferences.ExternalReferenceDRS + Design Verification Spec + EvidenceVerify design requirements are tested
ValidationCustomerRequirement.validates.ValidationTestCase.externalReferences.ExternalReferenceCRS + Validation Spec + EvidenceValidate customer needs with acceptance tests

​
Traceability Chain Pattern

Requirement decomposition and refinement chains:
PatternPathDirection
RefinementCustomerRequirement.refines.SystemRequirement.refines.DesignRequirementTop-down (decomposition)
VerificationDesignRequirement.verifiedBy.VerificationTestCaseReverse traceability
MitigationFailureMode.mitigates.RiskControl.implements.DesignRequirementRisk to design

​
FMEA Integration Pattern

Failure mode expansion for analysis workflows:
PatternPathPurpose
Function FailuresFunction.failureModes.FailureMode.mitigates.RiskControlShow controls per failure mode
Characteristic FailuresCharacteristic.assesses.FailureModeDesign parameters affecting risks
Control PlanRiskControl.implements.Characteristic.measured.ControlPlanItemMeasurement and inspection

​
Entity Factory and Auto-Creation

Expansion paths often work with entity factory configurations to enable inline creation of linked entities. When a user creates a new item within an expanded column group, the system automatically:
  1. Creates the new work item in the specified module (via entityFactory.modulePath)
  2. Creates a link using the expansion’s link role
  3. Adds the new row to the expanded view
Example Configuration: 
columnGroups:
  - id: verification_tests
    title: Verification Test Cases
    parentExpansion: design_reqs.verificationTestCases
    entityFactory:
      workItemType: VerificationTestCase
      modulePath: Testing/DesignVerificationSpecification
      linkRole: verificationTestCases
      reverseLink: true
When a user creates a test in the verification_tests group, the system:
  • Creates a new VerificationTestCase work item in Testing/DesignVerificationSpecification
  • Links it to the parent design requirement via the verificationTestCases link role
  • Automatically includes the link in reverse (design requirement ← test case)

​
Document Filtering with Expansions

Expansion paths often include document constraints to limit which entities appear in expanded columns. This prevents expansion into unrelated documents or modules.

​
Filter Types

Filter TypeExampleEffect
Exact Module PathTesting/DesignVerificationSpecificationShow only test cases from this specific document
Module PrefixTesting/*Show test cases from any document under Testing/
Entity Type + ModuleVerificationTestCase @ Testing/SystemVerificationSpecExpand only to specific work item type in specific module
None (unrestricted)(empty)Show all linked entities of target type, any module

​
Document Filter Configuration

columnGroups:
  - id: verification_tests
    title: Verification Test Cases
    parentExpansion: system_reqs.verificationTestCases
    
    # This expansion shows only test cases from the specified module
    documentFilter:
      module: Testing/SystemVerificationSpecification
      entityType: VerificationTestCase
    
    # Entity factory ensures new tests are created in the same module
    entityFactory:
      workItemType: VerificationTestCase
      modulePath: Testing/SystemVerificationSpecification
      linkRole: verificationTestCases

​
Expansion Performance Considerations

Performance Factors
FactorImpactMitigation
Expansion Depth3 levels: fast; 4+ levels: slowLimit to 3 levels; use navigation for deeper chains
Link Cardinality1:N with N>20 items per parentUse document filters to reduce result set
Unfiltered QueriesExpansion across all modulesAlways apply document filter for target entities
Real-Time RecalcLarge denormalized gridsCache intermediate results; lazy-load expansions
Each expansion level multiplies the number of rows displayed. A requirement with 5 test cases that each have 3 evidence items creates 15 rows (1 requirement × 5 tests × 3 pieces of evidence). For large projects, use filters to limit expansion scope.

​
Configuring Expansions: YAML Example

This PowerSheet configuration shows a complete multi-level expansion setup: 
sourceEntity: DesignRequirement
columns:
  - field: objectId
    title: Req ID
    readOnly: true
  - field: title
    title: Requirement
    readOnly: true
    formatter: boldreadOnly

expansions:
  - id: verification_tests
    linkRole: verificationTestCases
    targetEntity: VerificationTestCase
    documentFilter:
      module: Testing/DesignVerificationSpecification
    collapsed: true
    collapseTo: title
    columns:
      - field: objectId
        title: Test ID
      - field: title
        title: Test Case
        formatter: bold
      - field: status
        title: Status
    
    # Second-level expansion from test cases to evidence
    expansions:
      - id: evidence_artifacts
        linkRole: externalReferences
        targetEntity: ExternalReference
        collapsed: true
        collapseTo: attachmentName
        columns:
          - field: attachmentName
            title: Evidence
          - field: description
            title: Description
          - field: url
            title: URL

​
Cross-Linking Between Expansion Paths

In complex projects, multiple PowerSheets or Risksheets may share expansion paths, enabling consistent traceability views across the project. Example: The System Verification, Design Verification, and Whole RTM sheets all use similar expansion patterns: diagram By standardizing link role names and entity types across these sheets, engineers can navigate consistently between views.

​
Relationship to RTM Model

Expansion paths are defined by the RTM domain model configuration. For an expansion to work:
  1. Source entity type must exist in .polarion/nextedy/models/*.yaml
  2. Link role must be defined and connect source to intermediate entity
  3. Target entity type must exist in the model
  4. For multi-level: each intermediate entity must support onward link roles
Example RTM Model Fragment: 
entityTypes:
  - name: DesignRequirement
    polarionType: DesignRequirement
    links:
      - role: verificationTestCases
        target: VerificationTestCase
        cardinality: 1:N
  
  - name: VerificationTestCase
    polarionType: TestCase
    links:
      - role: externalReferences
        target: ExternalReference
        cardinality: 1:N
  
  - name: ExternalReference
    polarionType: ExternalReference
This model definition enables the three-part expansion path shown above.

​
Relation to Constraints and Validation

Expansion paths interact with RTM constraints:
  • Required Link Constraints — If a link role is marked required, the expansion will show all source entities but highlight missing links
  • Cardinality Constraints — Defines whether expansion shows 0..1, 1..1, or N items per parent
  • Document Constraints — Expansion document filters respect constraint rules (e.g., test case must be in Testing module)
See Constraints and Validation for details on constraint configuration.

​
See Also