Hierarchy and Traceability - Nextedy Documentation

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 Data Model

The hierarchy displayed in a Powersheet sheet is defined by two configuration layers working together:

Data model — defines entity types (e.g., UserNeed, SystemRequirement, DesignRequirement) and the relationships between them, including cardinality, storage mechanism, and navigation property names
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 data model provides the structural skeleton. The sheet configuration decides which parts of that skeleton to display and how.

Row Levels and Expansion Paths

Work Items tree breadcrumb in the Powersheet toolbar showing the active row hierarchy: User Need, Design Input (selected, with open-in-form, unlink, delete, and add actions), and Design Output

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 data model relationships section.

Cardinality and Row Nesting

The cardinality of each relationship determines how many child rows appear beneath a parent:

Cardinality	Behavior in Sheet
`one-to-many`	Parent row expands to show multiple child rows
`many-to-one`	Multiple parent rows share a single child reference
`many-to-many`	Parent row expands to multiple children; children may appear under multiple parents
`one-to-one`	Parent 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

Relationships and Polarion Link Roles

Every relationship in the data 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
    direct:
      name: systemRequirements
    back:
      name: 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 data model, as constraint resolution follows a layered evaluation approach.

Navigation Properties — how traversal between entity types works
Entity Types and Relationships — defining the data model structure
Link Cardinality — understanding relationship multiplicity
Process Constraints — enforcing rules through data model constraints
Model-Driven Design — why the data model drives the sheet behavior

​The Traceability Challenge

​How Hierarchy Maps to the Data Model

​Row Levels and Expansion Paths

​Cardinality and Row Nesting

​Column Binding Paths Across Levels

​Relationships and Polarion Link Roles

​Constraints and Scoping

​Related Pages

The Traceability Challenge

How Hierarchy Maps to the Data Model

Row Levels and Expansion Paths

Cardinality and Row Nesting

Column Binding Paths Across Levels

Relationships and Polarion Link Roles

Constraints and Scoping

Related Pages