Think of the domain model as an architect’s blueprint. The blueprint defines which rooms exist (entity types) and how corridors connect them (relationships). The sheet then renders this blueprint as an interactive, navigable hierarchy where engineers can trace requirements to risks, link design decisions to test cases, and manage complex traceability chains — all within a single configurable view.
Entity Types: The Building Blocks
An entity type represents a category of work item in your engineering process. In the domain model YAML, entity types are declared under the domainModelTypes section. Each entity type maps to a Polarion work item type and declares which properties (fields) are visible in the sheet.
domainModelTypes:
UserNeed:
polarionType: user_need
properties:
description:
severity:
component:
UserNeed is the entity type name used throughout Powersheet configuration. It maps to the user_need Polarion work item type and exposes three properties for display and editing in the sheet.
Key aspects of entity types:
| Property | Purpose |
|---|
polarionType | Maps the domain entity to a Polarion work item type ID. If omitted, the entity type name itself is used as the Polarion type. |
properties | Declares which Polarion fields are exposed in the sheet. Each key maps to a work item custom field or built-in field. A null value means the property exists with default configuration. |
constraints | Optional rules for load, create, and pick behavior (see Process Constraints). |
Entity type names in domainModelTypes must be single words without spaces or special characters. Use PascalCase: UserNeed, SystemRequirement, DesignRequirement. These names become the identifiers used in relationships, queries, and expansion paths throughout your configuration.
Why Entity Types Matter
Entity types serve as the translation layer between Polarion’s flat work item storage and the structured domain model that Powersheet uses to build hierarchical views. Without entity types, Powersheet would have no way to know that a user_need work item type should appear as a top-level requirement, or that a hazard work item type represents a risk that traces back to a system requirement.
This translation layer is what enables Powersheet to present the same underlying Polarion data in fundamentally different ways. A requirements traceability matrix, a risk analysis sheet, and a design verification view can all draw from the same project data — the domain model defines which entity types participate and how they relate.
Multiple Polarion Types per Entity
A single entity type can map to multiple Polarion work item types. The polarionType property accepts either a single string or an array:
domainModelTypes:
Requirement:
polarionType:
- sys_req
- des_req
Requirement entity type.
Entity Type Properties
Properties declared on an entity type control which fields are visible and editable in the sheet. Each property key corresponds to a Polarion work item field (built-in or custom). When a property is declared with a null value, it uses default configuration:
domainModelTypes:
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
priority:
verificationMethod:
systemRequirements.systemRequirement.severity, you are navigating through relationships and accessing a declared property. If severity is not declared in the entity type’s properties, it will not be available in the sheet.
Relationships: The Connections
Relationships define how entity types connect to each other. Each relationship specifies a source and target entity type, a cardinality pattern, a storage mechanism, and navigation properties that enable traversal in both directions.
relationships:
- from: UserNeed
to: SystemRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: systemRequirements
back:
name: userNeeds
Every relationship has two sides:
direct — The forward navigation property, created on the from entity type. In the example above, navigating from UserNeed to its related SystemRequirement items uses the property named systemRequirements.back — The reverse navigation property, created on the to entity type. Navigating from SystemRequirement back to its originating UserNeed items uses the property named userNeeds.
This bidirectional design means you can build sheets that start from either end of a relationship. A requirements traceability matrix might start from UserNeed and expand into SystemRequirement items (using the direct navigation). A reverse traceability view might start from SystemRequirement and expand back to UserNeed items (using the back navigation).
By convention, singular names (like chapter) indicate many-to-one relationships (one target), while plural names (like systemRequirements) indicate one-to-many or many-to-many relationships (multiple targets). This naming convention is not enforced by the system but makes configurations easier to read and maintain.
Cardinality: How Many Can Connect
Cardinality defines the multiplicity of a relationship — how many instances of each entity type can participate. Powersheet supports three cardinality patterns, and each one determines how the relationship appears in the sheet, how sources expand data, and how columns bind to navigation properties.
Many-to-One (N:1)
Each instance of the from entity belongs to exactly one instance of the to entity. This is the simplest relationship pattern.
Example: Each UserNeed belongs to exactly one Chapter.
relationships:
- from: UserNeed
to: Chapter
cardinality: many-to-one
storage: linkedWorkItems
linkRole: parent
direct:
name: chapter
back:
name: userNeeds
chapter column shows one value and allows selecting a different Chapter entity. You can also display properties of the referenced entity using dot notation:
columns:
chapter:
title: Chapter
display: title
list:
search:
- title
chapter.title:
title: Chapter Title
isReadOnly: true
chapter provides a picker for selecting the parent chapter. The column chapter.title displays the title of the linked chapter as a read-only field.
One-to-Many (1:N)
Each instance of the to entity has multiple instances of the from entity. This is the reverse view of a many-to-one relationship — same underlying link, different perspective.
Example: Each Chapter has multiple child UserNeed items.
sources:
- id: chapters
query:
from: Chapter
expand:
- name: userNeeds
expand clause in the source configuration tells Powersheet to load the related items and nest them under their parent.
columns:
title:
title: Chapter
hasFocus: true
userNeeds:
title: User Need
hasFocus: true
userNeeds column represents the expanded child level. No dot notation is needed because the expand directly opens the child level in the sheet hierarchy.
Many-to-Many (M:N)
Both sides of the relationship can have multiple instances. This is the most complex pattern and uses an association entity as an intermediate layer.
Example: UserNeed items linked to multiple SystemRequirement items and vice versa.
sources:
- id: user_needs
query:
from: UserNeed
expand:
- name: systemRequirements
expand:
- name: systemRequirement
systemRequirements (the association collection), then systemRequirement (the actual target entity). Column bindings use dot notation to reach through the association:
columns:
title:
title: Title
hasFocus: true
systemRequirements.systemRequirement:
title: System Requirement
list:
search:
- objectId
- title
createNew: true
systemRequirements.systemRequirement.title:
title: SysReq Title
hasFocus: true
systemRequirements.systemRequirement acts as a multi-item reference picker, allowing users to link multiple system requirements to a single user need.
Cardinality Summary
| Cardinality | Source expand | Column binding | UI behavior |
|---|
| N:1 | - name: chapter | chapter, chapter.title | Single-value reference picker |
| 1:N | - name: userNeeds | userNeeds | Child rows (new hierarchy level) |
| M:N | - name: systemRequirements then - name: systemRequirement | systemRequirements.systemRequirement | Multi-item reference picker |
A common mistake is to use a single-level expand for many-to-many relationships. The association entity is an intermediate layer that must be expanded separately. If you write expand: [name: systemRequirements] without the nested expand to systemRequirement, the sheet will show the association objects rather than the target entities.
Storage Mechanisms
The storage property determines how Powersheet persists relationships in Polarion. The only supported storage mechanism is linkedWorkItems, which uses Polarion’s native link mechanism. The relationship is stored as a typed link between work items, identified by the linkRole property.
The linkRole must match a link role defined in the Polarion project configuration. Common link roles include parent, refines, decomposes, verifies, and mitigates.
The Three-Layer Connection
Entity types and relationships form just the first layer. Understanding how the three configuration layers connect is essential for building working sheets:
- Domain model — Defines entity types and relationships with navigation property names
- Sources — Define how to query and expand those relationships using the navigation property names
- Columns — Define how to display the resulting data using binding paths that follow the navigation property chain
The navigation property names defined in direct and back are the glue. The same name appears in the domain model relationship, the source expand clause, and the column binding path. If any layer uses a different name, the chain breaks.
For a deeper exploration of how sources connect to domain model navigation properties, see Source Configuration. For the reference of all relationship properties, see Data Model Reference.
A Complete Example
Bringing all concepts together, here is a minimal but complete domain model that demonstrates entity types, relationships across multiple cardinality patterns, and the standard RTM entities:
domainModelTypes:
Chapter:
polarionType: heading
UserNeed:
polarionType: user_need
properties:
description:
severity:
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
DesignRequirement:
polarionType: des_req
properties:
description:
relationships:
- from: UserNeed
to: Chapter
cardinality: many-to-one
storage: linkedWorkItems
linkRole: parent
direct:
name: chapter
back:
name: userNeeds
- from: SystemRequirement
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: userNeeds
back:
name: systemRequirements
Chapter entities group UserNeed items (many-to-one), while SystemRequirement and UserNeed share a many-to-many traceability link. Each relationship declares both direct and back navigation properties, enabling sheets to traverse the hierarchy from either direction.
New users should begin with a minimal single-entity configuration and extend gradually. Jumping straight to complex multi-entity models with multiple relationship types leads to hard-to-diagnose errors. Add one entity type and one relationship at a time, verifying each addition works correctly in the sheet before adding the next.
Common Misconceptions
“Every entity type needs properties” — Not true. An entity type can be declared with no properties at all. It will still participate in relationships and appear in the sheet hierarchy. Properties only need to be declared for fields you want to expose as columns.
“Relationships are always bidirectional” — While Powersheet creates navigation properties in both directions (direct and back), not every sheet needs to use both. A sheet starting from UserNeed may only use the direct navigation to SystemRequirement without ever traversing the back direction.
“The second linked column works the same as the first” — When a sheet has two different entity types linked to the same parent (for example, design outputs and design verifications both linked to system requirements), the second linked column must be declared with multiItem: true in the sheet configuration. This is a non-obvious requirement that frequently blocks new users during initial setup. See Multi-Item Columns for details.
Next Steps
