Entity Types and Relationships - Nextedy Documentation

Think of the data 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 data 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:

In this example, 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 data 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 data 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

When an entity maps to multiple types, the sheet handles type selection during creation and filtering during queries. This is useful when you want to treat several related Polarion types as a single logical category in your data model — for example, grouping system requirements and design requirements under a unified 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:

Properties do more than expose fields. They become the vocabulary that columns, formatters, and queries use to reference data. When you configure a column with a binding path like 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

In the sheet, a many-to-one relationship renders as a single-value reference picker. The 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

The column 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

In the sheet, a one-to-many relationship creates child rows — a new hierarchy level that expands beneath the parent row. The 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

The 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

The source expand is two levels deep: first 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

The column 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:

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

This model defines four entity types and two relationships. 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

Navigation Properties — How navigation properties enable expansion paths and column bindings
Link Cardinality — Detailed cardinality rules and their impact on sheet behavior
Data Model vs Sheet Configuration — How data model and sheet configuration complement each other
Configure a Relationship — Step-by-step guide to adding relationships

​Entity Types: The Building Blocks

​Why Entity Types Matter

​Multiple Polarion Types per Entity

​Entity Type Properties

​Relationships: The Connections

​Cardinality: How Many Can Connect

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​Cardinality Summary

​Storage Mechanisms

​The Three-Layer Connection

​A Complete Example

​Common Misconceptions

​Next Steps

Entity Types: The Building Blocks

Why Entity Types Matter

Multiple Polarion Types per Entity

Entity Type Properties

Relationships: The Connections

Cardinality: How Many Can Connect

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

Cardinality Summary

Storage Mechanisms

The Three-Layer Connection

A Complete Example

Common Misconceptions

Next Steps