Skip to main content

​
What you will achieve

By the end of this tutorial you will have:
  • A working data 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 throughout, drawn from the shipped RTM example model. In your own configuration, replace UserNeed and SystemRequirement with entity types that match your domain — any names meaningful to your workflow (a risk-analysis model, for instance, might use Hazard and RiskControl instead).

​
Prerequisites

  • Nextedy Powersheet installed and licensed (see Installing Powersheet)
  • Navigation topic enabled — this registers Powersheet as a routable page so your configured sheets are reachable from the project sidebar (see Setting Up Navigation)
  • At least two Polarion work item types configured in your project (e.g., user_need and sys_req)
  • A Polarion link role defined for connecting the two types (e.g., decomposes)
1

Open the Data Models administration

Navigate to Administration > Nextedy Powersheet > Data Models.
Polarion Administration sidebar showing the Nextedy Powersheet section with Data Models, Sheet Configurations, Setup, and License entries
The Data Models page lists existing models grouped by scope — Global models apply to all projects, while project-scoped sections (e.g., RTM w/ Components) hold models tied to a specific project.
Data Models administration page showing Global and project-scoped (RTM w/ Components) sections with existing models listed
Click New to create a new data model at the project level. Select System Default as the base and give your model a name (e.g., rtm).
New data model creation row with the name field filled as newModel and a System Default base template selected
You should see: A new row is added to the Data Models list for your project. Click Open on that row to launch the configuration editor — it opens in a new browser tab, preloaded with the default template content.
Saving a new model only adds a row to the Data Models list; it does not open the editor automatically. Click Open on the model row to launch the configuration editor in a separate browser tab, leaving the administration page open behind it. Save in the editor tab, then return to the administration tab to manage other models.
The System Default base preloads a rich template (around 270 lines defining many entity types such as Document, Chapter, and several requirement types). The minimal YAML shown in this tutorial is meant for learning the structure. For a real project, extend the template rather than wholesale-replacing it — and before you make sweeping changes, copy the original content aside (for example via Menu > Download configuration, see Step 4) so you can recover the entity definitions you would otherwise lose.
You can also reach the model editor directly from an open Powersheet document via Menu > Configuration > Edit Data Model.
Powersheet document Menu dropdown opened on Configuration with Edit Sheet Configuration and Edit Data Model options highlighted
Data model files use YAML syntax. Indentation must use spaces (not tabs), and each nesting level uses two spaces. Most errors in data model setup come from incorrect indentation. For a complete introduction to YAML syntax, see the YAML Primer.
2

Define entity types

For this tutorial, set the data model content to the following minimal YAML (for a real project, add these definitions to the existing template rather than replacing it — see the warning in Step 1):
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    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.
Data model YAML editor with domainModelTypes containing Document, Chapter, UseStep, and UserNeed entity definitions, showing the Save toolbar at the top
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.
The polarionType value must be the exact ID of a Polarion work item type configured in your project — and the match is case-sensitive. Polarion type IDs are commonly snake_case (for example user_need, sys_req), not the camelCase or PascalCase you might assume. Writing userNeed when the real type ID is user_need does not raise an error: the model saves cleanly, and the mismatch only surfaces later as a sheet that renders empty with no diagnostic.Look up the real IDs before you fill in polarionType: go to Administration > Work Items > Types and copy each type’s ID value verbatim (the ID, not the display name). Note that the entity type name (the key, e.g. UserNeed) is separate — it is what you reference everywhere else in Powersheet configuration, while polarionType is the bridge to Polarion.
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.
The decomposes link role and a SystemRequirement → UserNeed relationship are already present in the System Default template. If you kept that template instead of starting from the minimal YAML above, do not add a second definition — adjust the existing relationship’s direct/back names if needed rather than duplicating it.
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 user_need (the Polarion type ID). Mismatching these is a common cause of data model errors.
4

Review the complete model

Your complete data model should look like this:
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    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.
The configuration editor auto-indents on every Enter, and the indentation accumulates with each new line. If you type multi-line YAML by hand, the leading spaces compound and the structure quickly breaks (deeper-and-deeper indentation that no longer reflects the real nesting). Instead, paste the whole block at once — for example by copying the complete YAML above with the copy button on the code block — and verify the indentation matches what is shown here. If you do edit by hand, watch the leading spaces on each line rather than trusting the editor to indent for you.
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.
The model editor also offers a Menu > Download configuration action that saves the current YAML as a file on your machine. This is useful for backing up models, sharing them between projects, or version-controlling them outside Polarion.
Data Model editor toolbar showing the Menu dropdown opened with the 'Download configuration' option exposed next to the Save button
diagram
5

Understand the connection to sheet configuration

The navigation properties you defined (userNeeds and systemRequirements) are the bridge between your data model and your sheet configuration. Here is how they connect:
Data 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: user_needResolved 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.
6

Refine with constraints (optional)

By default, an entity loads every matching work item in the project. Constraints let you scope that behavior per relationship, using three actions that each take a Polarion query:
  • load (loadFromQueries) — where the entity’s items are loaded from (which items appear in the sheet).
  • saveToQueries — where a new item is created when added through this relationship (for example, into a specific document or component). (This stage has no short save alias — the data-model editor rejects a bare save, unlike load and pick.)
  • pick (pickFromQueries) — which items are offered in the item picker (the dropdown used to link existing items).
A constraint query can reference the current context — for example restricting items to the same component as the source document via $context.source.document.component. You typically add a constraints block to a relationship once the basic model works; it is not required to get a sheet rendering.
relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    constraints:
      load:        # alias for loadFromQueries
        document:                       # scope by document — NOT a work-item type
          moduleFolder: Requirements
          moduleName: UserNeedSpecification
    direct:
      name: userNeeds
    back:
      name: systemRequirements
For the full syntax and worked examples, see Configure Constraints.
A single entity type can map to more than one Polarion work item type (a “multi-type entity”) — useful when, say, several discipline-specific requirement types should behave as one entity in the sheet. See Map Multiple Polarion Types to One Entity.

​
Next steps

Last modified on July 10, 2026