Skip to main content

​
Prerequisites

  • Both entity types must already exist in your domainModelTypes section
  • A Polarion link role must be configured in your project for the relationship
  • Access to the domain model YAML via Menu > Configuration > Edit Model

​
Step 1: Identify the Relationship

Determine the source and target entity types, the cardinality, and which Polarion link role to use.
DecisionQuestionExample
Source (from)Which entity owns the relationship?UserNeed
Target (to)Which entity is being referenced?SystemRequirement
CardinalityHow many targets per source?one-to-many
Link roleWhich Polarion link role stores this?relates_to
diagram

​
Step 2: Add the Relationship

Add an entry to the relationships array in your domain model YAML. 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: relates_to
    fromNavPropName: systemRequirements
    toNavPropName: userNeeds

​
Relationship Properties

PropertyTypeRequiredDescription
fromstringYesSource entity type name. Must match a domainModelTypes key exactly.
tostringYesTarget entity type name. Must match a domainModelTypes key exactly.
cardinalitystringYesMultiplicity: one-to-many, many-to-one, or many-to-many.
storagestringYesPersistence mechanism. Use linkedWorkItems for Polarion link-based relationships.
linkRolestringYesPolarion link role ID. Must exist in your project’s link role configuration.
fromNavPropNamestringYesNavigation property name on the source entity for forward traversal.
toNavPropNamestringYesNavigation property name on the target entity for reverse traversal.
The from and to values must be domain model entity type names (e.g., UserNeed), not Polarion work item type IDs (e.g., userNeed). Using the wrong name causes a “left error” (invalid from) or “right error” (invalid to).

​
Step 3: Choose Navigation Property Names

Navigation property names are used in sheet configuration binding paths and query expansion paths. Follow these naming conventions:
  • Forward (fromNavPropName): Use the plural form of the target entity in camelCase — e.g., systemRequirements
  • Reverse (toNavPropName): Use the plural form of the source entity in camelCase — e.g., userNeeds
These names appear in column binding paths: 
columns:
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250

​
Step 4: Update Sheet Sources

After adding the relationship, update the sources section in your sheet configuration to include the expansion path: 
sources:
  - id: rtm
    title: RTM
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
After configuring the relationship, use the Model Helper widget to visualize the model structure and verify that expansion paths are correct. Set startEntity to the source entity and depth to the number of relationship levels.

​
Step 5: Verify

  1. Save both the domain model and sheet configuration
  2. Reload the powersheet document
  3. You should now see the related entities loading in the sheet hierarchy
If the relationship is working correctly, expanding a source entity row will show the related target entities as child rows.

​
Alternative Format: direct/back Syntax

Some models use an alternative syntax with direct and back objects instead of fromNavPropName/toNavPropName: 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: relates_to
    direct:
      name: systemRequirements
    back:
      name: userNeeds
Both formats are functionally equivalent. The direct/back syntax allows additional per-direction configuration such as permissions.

​
Cardinality Options

CardinalityMeaningUse Case
one-to-manyOne source links to multiple targetsParent-child hierarchies
many-to-oneMultiple sources link to one targetLookup references
many-to-manyMultiple sources link to multiple targetsCross-references

​
See Also

KB ArticlesSupport TicketsSource Code
  • DomainModelV2.java
  • model.yaml
  • riskmanagement_model.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints_create_only.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml