Define a relationship between two entity types in your Nextedy POWERSHEET domain model to enable hierarchical navigation and traceability in Siemens Polarion ALM.
Add an entry to the relationships array in your domain model YAML. Each relationship uses direct and back objects to define the forward and reverse navigation property names.
Source entity type name. Must match a domainModelTypes key exactly.
to
string
Yes
Target entity type name. Must match a domainModelTypes key exactly.
cardinality
string
Yes
Multiplicity: one-to-one, many-to-one, one-to-many, or many-to-many.
storage
string
Yes
Persistence mechanism. Use linkedWorkItems for Polarion link-based relationships.
linkRole
string
Yes
Polarion link role ID. Must exist in your project’s link role configuration.
direct
object
Yes
Forward navigation property. Contains a name field used to traverse from source to target.
back
object
Yes
Reverse navigation property. Contains a name field used to traverse from target back to source.
The from and to values must be domain model entity type names (e.g., UserNeed), not Polarion work item type IDs (e.g., user_need). Using the Polarion type ID instead of the entity type name causes connection errors that are difficult to diagnose.
The direct.name and back.name values define how you traverse the relationship in sheet configurations, expansion paths, and column bindings. Follow these naming conventions:
Forward (direct.name): Use the plural camelCase form of the target entity — e.g., systemRequirements when the target is SystemRequirement
Reverse (back.name): Use the plural camelCase form of the source entity — e.g., userNeeds when the source is UserNeed
For many-to-one relationships, the forward navigation property should be singular (scalar), since it references exactly one target:
# many-to-one: each UserNeed belongs to one Chapter- from: UserNeed to: Chapter cardinality: many-to-one storage: linkedWorkItems linkRole: parent direct: name: chapter # singular -- scalar reference back: name: userNeeds # plural -- collection of children
The cardinality and navigation property name together determine what the sheet renders. A singular direct.name like chapter produces a single-value reference picker. A plural back.name like userNeeds produces expandable child rows or a multi-item picker, depending on how you bind columns.
When a sheet has two entity types linked to the same parent (e.g., design outputs and design verifications both linked to system requirements), the second linked column must be declared with multiItem: true in the sheet configuration. Omitting this property causes the second column to silently fail during initial setup.
Expand the source entity to confirm child rows or linked items appear
Check that column bindings resolve correctly — the referenced entity properties should display their values
If the sheet does not load or shows errors, verify:
The from and to values match entity type names in domainModelTypes exactly (case-sensitive)
The linkRole value exists in your Polarion project’s link role configuration
The sources.model property in your sheet configuration matches your custom domain model name
You should now see the related entities navigable through expansion paths in your sheet, with columns displaying the linked entity properties.
The sources.model property in your sheet configuration must match the domain model name — not the default rtm. This is a common first-time setup mistake that causes model connection errors.
