Skip to main content

​
What you will achieve

By the end of this tutorial you will have:
  • A working domain model with two entity types (UserNeed and SystemRequirement)
  • A many-to-many relationship connecting the two entity types via a Polarion link role
  • Navigation properties (direct and back) that you can reference in sheet configurations
  • A foundation you can extend with additional entity types like DesignRequirement, Hazard, or RiskControl
This tutorial uses UserNeed and SystemRequirement from the shipped RTM example model. In your own configuration, replace these with entity types that match your domain — for example, Hazard and RiskControl, or any names meaningful to your workflow.

​
Prerequisites

  • Powersheet installed and licensed (see Installing Powersheet)
  • Navigation topic enabled (see Setting Up Navigation)
  • At least two Polarion work item types configured in your project (e.g., userNeed and systemRequirement)
  • A Polarion link role defined for connecting the two types (e.g., decomposes)

​
Step 1: Open the domain model administration

Navigate to Administration > Nextedy POWERSHEET > Domain Models. Click New to create a new domain model at the project level. Select System Default as the base and give your model a name (e.g., rtm). You should see: A new domain model file opens in the configuration editor with the default template content.
Domain model files use YAML syntax. Indentation must use spaces (not tabs), and each nesting level uses two spaces. Most errors in domain model setup come from incorrect indentation. For a complete introduction to YAML syntax, see the YAML Primer.

​
Step 2: Define entity types

Replace the content of the domain model with the following minimal YAML: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description:
      severity:
Each key under domainModelTypes defines an entity type name. The polarionType property maps the entity type to a Polarion work item type. The properties section lists which work item fields are exposed for use in sheet configurations. You should see: The YAML is accepted without errors in the editor.
Entity type names under domainModelTypes must be single words with no spaces or special characters. PascalCase (e.g., UserNeed, SystemRequirement) is the recommended naming convention, but it is not enforced by the system. The important rule is that these names are used consistently throughout your configuration — in relationships, sources, and column bindings.
Do not confuse the entity type name (UserNeed) with the Polarion work item type ID (userNeed). The entity type name is what you use everywhere in Powersheet configuration. The polarionType value must match the exact Polarion work item type ID configured in your project.

​
Step 3: Define a relationship

Add the relationships section below the entity types. Relationships use direct and back properties to define forward and reverse navigation: 
relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
This defines a many-to-many relationship from SystemRequirement to UserNeed, stored using the Polarion decomposes link role.
  • direct creates a navigation property on the from entity (SystemRequirement). The name userNeeds lets you navigate from a system requirement to its linked user needs.
  • back creates a reverse navigation property on the to entity (UserNeed). The name systemRequirements lets you navigate from a user need to its linked system requirements.
You should see: The complete model now has both domainModelTypes and relationships sections.
The from and to values must match the entity type names defined in domainModelTypes — not the Polarion work item type IDs. For example, use UserNeed (the entity type name), not userNeed (the Polarion type ID). Mismatching these is the most common cause of domain model errors.

​
Step 4: Review the complete model

Your complete domain model should look like this: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description:
      severity:

relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
Save the model. You should see: The model saves without errors. The direct.name and back.name values become the navigation properties you reference in your sheet configuration — in source expand paths and column bindings. diagram

​
Step 5: Understand the connection to sheet configuration

The navigation properties you defined (userNeeds and systemRequirements) are the bridge between your domain model and your sheet configuration. Here is how they connect:
Domain model propertyUsed in sheet configurationPurpose
direct.name: userNeedsexpand: - name: userNeedsExpands system requirements to show linked user needs
back.name: systemRequirementsexpand: - name: systemRequirementsExpands user needs to show linked system requirements
polarionType: userNeedResolved automaticallyMaps entity to Polarion work item queries
properties: descriptioncolumns: description:Exposes field for column display
Begin with two entity types and one relationship. Once your sheet renders correctly, add more entity types (e.g., DesignRequirement, Hazard, RiskControl) and relationships incrementally. See Incremental Configuration Approach for guidance.

​
Next steps