Skip to main content
In Powersheet, the YAML file defining entity types and relationships is called the domain model (not “data model”). “Entity type” refers to domain model concepts; “work item type” refers to the underlying Polarion type.

​
Domain Model Basics

​
What is a domain model and why do I need one?

The domain model is a YAML configuration file that defines the semantic layer between Polarion’s native work item types and Powersheet’s sheet views. It maps Polarion types, link roles, and custom fields into structured entity types and relationships that Powersheet uses for querying, displaying, and editing data. Without a domain model, Powersheet cannot understand which work items to load or how they relate to each other. See the Data Model Reference for the complete property reference.

​
Where do I manage domain models?

Domain models are managed through the Polarion administration interface at Administration > Nextedy POWERSHEET > Domain Models. You can create both global models (available to all projects) and project-specific models. Multiple models can coexist, and each sheet configuration references a specific model by name.

​
What is the relationship between domain model, sources, and columns?

The three configuration layers are connected through navigation property names:
  • Domain model defines entity types and relationships (with direct and back navigation names)
  • Sources define how to query and expand those relationships (using the navigation names)
  • Columns define how to display the resulting data (using dot-notation binding paths)
The cardinality of a relationship determines the expand pattern and column binding syntax. See the Sheet Configuration Reference for column binding details. diagram

​
Entity Types and Properties

​
How do I define entity types in the domain model?

Entity types are defined in the domainModelTypes section of the YAML file using map format only — each key is the entity type name, and the value contains its configuration. The polarionType property maps the entity type to a Polarion work item type. 
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
The domainModelTypes section must use map format (keyed by type name). Array format is not supported and will not work.

​
How do entity type properties work?

Each entry under properties defines a field exposed in the Powersheet sheet. Properties are listed as keys under the entity type. Key property attributes include:
AttributePurposeDefault
nameClient-facing property nameRequired
serverNamePolarion field name overrideSame as name
customFieldNamePolarion custom field ID—
readableCan be read by userstrue
updatableCan be modified by userstrue
scalarSingle value vs. collectiontrue
enumValuesValid enum option IDs—
Use serverName to alias Polarion field names to more user-friendly names, and customFieldName when a property maps to a Polarion custom field rather than a built-in field.

​
Relationships and Cardinality

​
What relationship cardinalities are supported?

Powersheet supports two relationship cardinality types in the domain model, plus the implicit reverse of many-to-one:
CardinalityDirectionNavigation PropertyUI Behavior
many-to-onedirectScalar (e.g., chapter)Single-value reference picker
One-to-manyback (reverse of N:1)Collection (e.g., userNeeds)Child rows (new sheet level)
many-to-manybackCollection via association (e.g., systemRequirements)Multi-item reference picker
Relationships are defined in the relationships array of the domain model and map to Polarion link roles via the linkRole property. Each relationship specifies a direct and back navigation property name.

​
How do I configure a many-to-one relationship?

A many-to-one relationship links multiple entities to a single target. Use the direct navigation property name in your source expand and column binding: 
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds
In the source, expand using the direct name. In columns, bind with chapter for a reference picker or chapter.title for a read-only display of the referenced entity’s title.

​
How do many-to-many relationships differ from many-to-one?

Many-to-many relationships use an association entity between the two types. This requires a two-level expand in the source configuration and dot-notation in column bindings: 
# Source: two-level expand
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

# Columns: dot-notation binding
columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
The first level (systemRequirements) reaches the association entity; the second level (systemRequirement) reaches the actual target entity. See the Data Model Guides for walkthrough examples.

​
Configuration Tips

​
Should I start with a complex or simple domain model?

Always start with the simplest possible configuration and extend incrementally. Begin with a single entity type and one or two properties, verify it works in a sheet, then add relationships and additional entity types one at a time. Jumping directly to a complex multi-entity model leads to hard-to-diagnose configuration errors.
Start with one entity type, add a source and a few columns, confirm the sheet loads. Then add a relationship and expand one level at a time. This makes it easy to identify which change introduced a problem.
The linkRole property in a relationship definition specifies the Polarion link role used to persist the connection. This must match a link role defined in your Polarion project’s link role configuration. The storage property determines how the relationship is persisted — linkedWorkItems is the only supported storage mechanism, using Polarion’s native linking to persist connections. The constraints section on an entity type restricts which items appear in picker dialogs. You can filter by document location, type, or component: 
domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: requirements_specification
          component: $context.source.document.component
The $context.source.document.component expression dynamically filters results based on the source entity’s document component, enforcing component-scoped relationships. See the Configuration FAQ for more on validation and constraints.
Support TicketsSource Code
  • DatabridgeConstants.java
  • DomainModelV2.java
  • whole_rtm.template.yaml