Skip to main content

​
Top-Level Structure

domainModelTypes is defined as a map where each key is the entity type name and the value is the type definition object: 
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      component:
The map key becomes the entity type name automatically. When the domain model is loaded, Powersheet copies each map key into the corresponding type object so the name is consistently available regardless of how the type is accessed.
domainModelTypes must be a YAML map. Array format is not supported.

​
Entity Type Diagram

diagram

​
Entity Type Configuration Properties

PropertyTypeDefaultDescription
namestringDerived from map keyUnique identifier for the entity type. Set automatically from the YAML map key. Referenced by relationships[].from and relationships[].to.
pluralNamestringAuto-generated from namePlural form of the entity type name. Auto-generated using standard English pluralization if not specified.
polarionTypestring or string[]See applicationMaps this entity to one or more Polarion work item type IDs. Accepts a single string or a list for multi-type entities.
polarionProtostringIWorkItem.PROTOSpecifies the Polarion prototype (object type) this entity maps to. Determines which Polarion object class this entity can represent.
propertiesmap{}Map of property definitions that define the fields available on this entity type. See Properties.
constraintsobjectNoneOptional data scoping rules. See Constraints.
Entity type names must be single words without spaces or special characters. Relationship from and to fields reference these entity type names — not Polarion work item type IDs. Using an invalid name causes configuration errors.
PascalCase (e.g., UserNeed, SystemRequirement) is a common convention for entity type names, but it is not a requirement. Names are case-sensitive.

​
name

The entity type name is the primary identifier used throughout the domain model. It is set automatically from the YAML map key and does not need to be specified separately. 
domainModelTypes:
  UserNeed:           # name = "UserNeed"
    polarionType: user_need
  SystemRequirement:  # name = "SystemRequirement"
    polarionType: sys_req
Entity type names are used in:
  • relationships[].from and relationships[].to to reference participating types
  • Sheet source query.from to identify the root entity type
  • Expansion paths to navigate between related entities
  • Metadata system queries for type-based filtering

​
pluralName

An optional plural form of the entity type name. When omitted, Powersheet auto-generates it using standard English pluralization rules. 
domainModelTypes:
  Hazard:
    polarionType: hazard
    pluralName: Hazards
The pluralName property has limited support in current versions. Auto-generated pluralization covers most standard English forms.

​
polarionType

Maps the domain model entity to one or more Polarion work item types. This property is critical for Powersheet’s integration with Polarion — it determines which work items this entity type can represent. Single type mapping: 
SystemRequirement:
  polarionType: sys_req
Multiple type mapping: 
Requirement:
  polarionType:
    - sys_req
    - des_req
When multiple types are specified, the entity type matches work items of any of the listed Polarion types. This enables a single entity type to aggregate work items across multiple Polarion types. See Polarion Type Mapping for details on type resolution.

​
polarionProto

Specifies the Polarion prototype (object type) this entity maps to. Most entity types use the default work item prototype and do not need to set this property.
ValueUsage
IWorkItem.PROTO (default)Standard work items
Other prototypesNon-work-item Polarion objects
Document:
  polarionProto: IModule.PROTO

​
properties

Defines which fields are available on this entity type. Properties are declared as a map where the key is the property name. 
UserNeed:
  polarionType: user_need
  properties:
    description:
    severity:
    component:
    type:
An empty value after the property name declares the property with all default settings. To customize a property, provide a configuration object: 
UserNeed:
  properties:
    title:
      readable: true
      updatable: true
    outlineNumber:
      readable: true
      updatable: false
    renderColumn:
      serverName: customRenderField
Properties must be declared as a YAML map. Array format (using - name: syntax) is not supported.
Properties can represent:
  • Polarion built-in fields — standard work item fields like title, description, severity
  • Custom fields — Polarion custom fields identified by customFieldName
  • Virtual properties — properties not backed by any Polarion field, commonly used as targets for server rendering or computed display columns
For detailed property configuration including serverName, customFieldName, type, storage, scalar, and navigability, see Properties.

​
Built-in Properties

All entity types automatically include these properties without explicit declaration:
PropertyTypeDescription
objectIdstringUnique entity identifier (primary key)
idstringPolarion work item ID
titlestringWork item title
projectIdstringPolarion project identifier (foreign key)

​
Permission Flags on Properties

Individual properties support field-level access control:
FlagTypeDefaultDescription
readablebooleantrueWhether the property is visible to users in the sheet and available in queries
updatablebooleantrueWhether the property can be modified through save operations
SystemRequirement:
  properties:
    description:
      readable: true
      updatable: true
    outlineNumber:
      readable: true
      updatable: false
    internalStatus:
      readable: false
      updatable: false
Setting readable: false hides the property entirely from the metadata system. Setting updatable: false makes the property read-only in the sheet while still allowing it to be displayed. See Permissions for additional access control options.

​
constraints

Defines data scoping rules at three lifecycle points. Constraints control which work items are loaded, which can be selected in pickers, and how new entities are created. See Constraints for full reference. 
SystemRequirement:
  polarionType: sys_req
  constraints:
    load:
      document:
        type: systemSpecification
    create:
      document:
        moduleFolder: Requirements
        moduleName: System Specification
    pick:
      document:
        type: systemSpecification
ConstraintPurpose
loadFilters which entities are fetched during initial data loading. Applies a Lucene query scope.
createConfigures defaults for newly created entities: document location, project routing, default field values, and type/relation constraints.
pickRestricts which entities appear in picker dialogs when creating or editing relationships.
The load constraint affects what data is visible in the sheet. The pick constraint independently controls what items appear in reference pickers. The create constraint controls the full creation workflow including where new items are placed and what defaults they receive.

​
Built-in Entity Types

Powersheet provides the Document entity type without explicit declaration. All other entity types, including Chapter, must be declared in the domainModelTypes map.
Entity TypeRequires DeclarationDescription
DocumentNoRepresents Polarion documents (LiveDoc modules). Exposes module properties like moduleName, title, and allowedWITypes. Not a work item type.
ProjectNoRepresents the Polarion project. Linked to all work item entities via projectObjectId.
ChapterYesRepresents heading work items in document structures. Must be explicitly declared with polarionType: heading.
The Document entity type is not a work item. It provides navigation access to the containing document’s properties for filtering and constraints. It uses a different Polarion prototype than standard entity types.

​
Declaring Chapter

To use Chapter in your domain model, declare it explicitly: 
domainModelTypes:
  Chapter:
    polarionType: heading
Chapters are commonly used in many-to-one relationships where work items belong to a document section: 
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

​
How Entity Types Connect to Sources and Columns

Entity types defined in domainModelTypes are referenced throughout the sheet configuration. The connection flows through three layers:
  1. Domain model — defines entity types and their relationships
  2. Sheet sources — queries entity types and expands relationships
  3. Sheet columns — binds to entity properties using dot-notation paths
The cardinality of a relationship determines the expand pattern and column binding syntax.

​
Cardinality Summary

CardinalitySource ExpandColumn BindingUI Behavior
N:1 (many-to-one)- name: chapterchapter, chapter.titleSingle-value reference picker
1:N (one-to-many)- name: userNeedsuserNeedsChild rows (new sheet level)
M:N (many-to-many)- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker
See Relationships for relationship configuration and Binding Syntax for column path resolution.

​
Complete YAML Example

A comprehensive domain model using the standard RTM entity set: 
domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
      component:
      type:
    constraints:
      load:
        document:
          type: systemSpecification
      create:
        document:
          moduleFolder: Requirements
          moduleName: System Specification
      pick:
        document:
          type: systemSpecification

  DesignRequirement:
    polarionType: des_req
    properties:
      description:
      severity:
    constraints:
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification

  Hazard:
    polarionType: hazard
    properties:
      description:
      severity:

  RiskControl:
    polarionType: riskControl
    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

  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: systemRequirement

  - from: Hazard
    to: RiskControl
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: riskControls
    back:
      name: hazards

​
Programmatic Access

Powersheet provides several methods for accessing entity type definitions at runtime:
MethodReturn TypeDescription
getDomainModelTypes()CollectionReturns all entity type definitions. Ensures type names are mapped before returning.
getDomainModelTypesMap()MapReturns entity types keyed by name for lookup access.
getDomainModelType(name)OptionalRetrieves a specific entity type by name. Returns empty if the type does not exist.
getProperty(name)PropertyRetrieves a specific property definition from an entity type. Returns null if the property does not exist.
addProperty(name, property)voidProgrammatically adds a property definition to an entity type. Validates that the property name is not null or empty.
Programmatic access is primarily used in server-side extensions and custom Velocity templates. Standard sheet configuration uses the YAML declaration approach.
  • Relationships — Relationship definitions between entity types
  • Properties — Property configuration details including serverName, customFieldName, and type
  • Constraints — Load, create, and pick constraint reference
  • Cardinality — How relationship cardinality affects sources and columns
  • Polarion Type Mapping — How polarionType resolves to work item types
  • Permissions — Property-level access control
  • Link Roles — Polarion link role configuration for relationships
  • Navigation Directions — Forward and reverse navigation properties
Support Tickets
  • Data model configuration guidance
Source Code
  • DomainModelV2.java — domain model container and entity type registry
  • DomainModelTypeV2.java — entity type definition with properties, constraints, and Polarion mappings
  • Property.java — property model with permission flags and storage options
  • Relationship.java — relationship definitions with cardinality and navigation properties