Skip to main content

​
The Traceability Challenge

Polarion stores traceability as individual links between work items. While each link is correct in isolation, understanding the full chain — from a user need through system requirements to design requirements to hazards to risk controls — requires mentally assembling dozens of separate work item views. This is like reading a book one sentence at a time from different chapters: technically possible, but practically unusable for analysis. Powersheet solves this by rendering the entire traceability chain as a single hierarchical sheet, where parent-child nesting shows the relationships and every level is editable in place.

​
How Hierarchy Maps to the Domain Model

The hierarchy displayed in a Powersheet sheet is defined by two configuration layers working together:
  1. Domain model — defines entity types (e.g., UserNeed, SystemRequirement, DesignRequirement) and the relationships between them, including cardinality, storage mechanism, and navigation property names
  2. Sheet configuration — defines which columns to show, how to sort and group rows, and which sources with expand clauses to use for loading related entities
The domain model provides the structural skeleton. The sheet configuration decides which parts of that skeleton to display and how. diagram

​
Row Levels and Expansion Paths

When a sheet loads data, it starts with a root entity type (defined by sources[].query.from) and follows expansion paths to load related entities. Each expansion creates a new row level in the hierarchy:
  • Level 0 (upstream) — the root entity (e.g., UserNeed). Always present, with no back reference.
  • Level 1 (downstream) — first-level related entities (e.g., SystemRequirement), loaded by expanding a navigation property.
  • Level 2+ — deeper related entities (e.g., DesignRequirement), loaded by nested expansions.
Each downstream level maintains a back reference to its parent navigation property, preserving the parent-child relationship for rendering and editing. 
sources:
  - id: rtm
    title: Requirements Traceability
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
The nested expand structure mirrors the hierarchy you want to see in the sheet. Each name must reference a navigation property defined in the domain model relationships section.

​
Cardinality and Row Nesting

The cardinality of each relationship determines how many child rows appear beneath a parent:
CardinalityBehavior in Sheet
one-to-manyParent row expands to show multiple child rows
many-to-oneMultiple parent rows share a single child reference
many-to-manyParent row expands to multiple children; children may appear under multiple parents
one-to-oneParent row has exactly one child row
Most traceability relationships use one-to-many or many-to-many, as requirements typically refine into multiple downstream items and can be traced to multiple upstream sources.
The one-to-many cardinality is the most common for traceability chains. A single UserNeed typically decomposes into multiple SystemRequirement items, each of which may decompose into multiple DesignRequirement items.

​
Column Binding Paths Across Levels

Columns in the sheet configuration use dot-separated binding paths that traverse navigation properties to reach properties on related entities. The binding path determines which row level the column belongs to: 
columns:
  # Level 0: UserNeed properties
  title:
    title: User Need
    width: 250
    hasFocus: true

  # Level 1: SystemRequirement properties
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 200

  # Level 2: DesignRequirement properties
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    width: 200
Every relationship in the domain model maps to a Polarion link role via the linkRole property. The link role must exist in your Polarion project configuration. The storage property (typically linkedWorkItems) specifies that the relationship is persisted using Polarion’s native work item linking mechanism. 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    fromNavPropName: systemRequirements
    toNavPropName: userNeed
The from and to values in relationships must reference domainModelTypes names — not Polarion work item type IDs. This is a common source of configuration errors.

​
Constraints and Scoping

Entity types can define constraints that scope which items appear at each level of the hierarchy. Constraints support three operations:
  • load — filters which entities are loaded and displayed
  • create — restricts where new entities can be created (by document folder, name, or type)
  • pick — filters which entities appear in relationship pickers
These constraints ensure that the traceability hierarchy reflects your process requirements — for example, ensuring that SystemRequirement items can only be picked from documents of a specific type.
The interaction between constraints defined at the entity type level and constraints defined on navigation properties should be verified against your specific domain model, as constraint resolution follows a layered evaluation approach.
Source Code
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints_pick_only.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/whole_rtm.template.yaml
  • rtm_model.yaml
  • powersheet.yaml
  • todosBig_model.yaml