Skip to main content

​
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 one or more Polarion work item types and defines which properties (fields) are visible in the sheet. 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    properties:
      description: null
      severity: null
      component: null
Key aspects of entity types:
PropertyPurpose
polarionTypeMaps the domain entity to a Polarion work item type ID. If omitted, the entity type name is used as the Polarion type.
propertiesDeclares which Polarion fields are exposed. Each key maps to a work item custom field or built-in field. null values use default configuration.
constraintsOptional 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.

​
Built-in Entity Types

Powersheet automatically provides two built-in entity types that do not need to be explicitly declared:
  • Document — Represents Polarion documents (LiveDoc modules). Not a work item type, but a container for work items. Exposes properties like moduleName and title.
  • Chapter — Represents Polarion headings (document structure elements).
These built-in types are available for use in relationships and constraints without explicit definition.

​
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
When an entity maps to multiple types, the sheet handles type selection during creation and filtering during queries.

​
Relationships: The Connections

Relationships define how entity types connect to each other. Each relationship creates navigation properties on both the source and target entity types, enabling bidirectional traversal in the sheet. 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    fromNavPropName: systemRequirements
    toNavPropName: userNeed
diagram

​
Relationship Properties

PropertyTypeDescription
fromstringSource entity type name. Must match a key in domainModelTypes.
tostringTarget entity type name. Must match a key in domainModelTypes.
cardinalitystringMultiplicity: one-to-one, many-to-one, one-to-many, or many-to-many.
storagestringHow the link is persisted. Typically linkedWorkItems (Polarion native links).
linkRolestringPolarion link role ID used to store the relationship.
fromNavPropNamestringNavigation property name added to the source entity for forward traversal.
toNavPropNamestringNavigation property name added to the target entity for reverse traversal.
The from and to fields in relationships must reference domainModelTypes names (e.g., UserNeed), not Polarion work item type IDs (e.g., userNeed). Using the wrong identifier will cause errors. A “left error” typically indicates an invalid from entity, while a “right error” indicates an invalid to entity.

​
Alternative Relationship Syntax

Some domain model formats use direct and back objects instead of fromNavPropName and toNavPropName: 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeed
Both syntaxes are equivalent.

​
Relationships Enable Expansion Paths

Once relationships are defined, they enable expansion paths in the sheet configuration. Column binding paths traverse the relationship chain: 
systemRequirements.systemRequirement.title
This path follows the systemRequirements navigation property, enters the systemRequirement entity, and accesses its title field. For more on this, see Navigation Properties and Hierarchy and Traceability.
Source Code
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints_create_only.yaml
  • model.yaml
  • riskmanagement_model.yaml
  • rtm_model.yaml