Skip to main content

​
Prerequisites

  • A domain model already configured in Administration > Nextedy POWERSHEET > Domain Models
  • Permissions to create a LiveReport page in your Polarion project
  • At least one entity type with relationships defined in your domain model

​
Step 1: Create the Model Helper LiveReport Page

Model Helper runs as a LiveReport page inside Polarion. To set it up:
  1. Navigate to your project in Polarion
  2. Go to Wiki > LiveReport Pages
  3. Create a new LiveReport page
  4. Import the Model Helper page archive provided by Nextedy
The Model Helper page archive is supplied with the Powersheet installation package. Contact your administrator if you do not have access to the archive file.

​
Step 2: Configure the Parameters

When you open the Model Helper LiveReport, fill in four parameter values at the top of the page:
ParameterDescriptionExample
modelName of the domain model to visualizertm
projectIdProject ID where the model is definedRTM_Demo
startEntityRoot entity type for expansion visualizationUserNeed
depthNumber of relationship levels to expand from the start entity3
Enter these values and submit to generate the visualization. diagram
Begin with depth: 2 or 3. Higher values produce very large visualizations that can be difficult to read, especially for domain models with many cross-entity relationships.

​
Step 3: Read the Visualization Output

The Model Helper displays three key pieces of information:
  • Entity types shown as nodes, each displaying the entity name and its polarionType mapping (for example, UserNeed mapped to user_need)
  • Relationships shown as labeled connections between entity nodes, annotated with the navigation property name (the direct or back name from your domain model)
  • Expansion depth indicating how many relationship levels each entity sits from the start entity
This visualization directly maps to the three configuration layers you work with in Powersheet:
LayerWhat it definesWhat Model Helper shows
Domain modelEntity types and relationshipsNodes and connections
Sheet sourcesHow to query and expand relationshipsExpansion paths from start entity
Sheet columnsHow to display the resulting dataAvailable binding paths at each level

​
Step 4: Map Visualization to Source Configuration

The expansion paths shown in Model Helper translate directly to the expand section of your sheet sources. The cardinality of each relationship determines the expand pattern.

​
Many-to-One (N:1) Relationships

For scalar navigation properties (one parent per child), use a single-level expand with the direct name: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
The direct name in your domain model (chapter) becomes the expand name. In your columns, bind to this property for a reference picker: 
columns:
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true
  • chapter renders a single-value reference picker (scalar navigation property)
  • chapter.title renders a read-only display of the referenced Chapter’s title using dot-notation

​
One-to-Many (1:N) Relationships

For collection navigation properties (one parent, many children), the expand opens a new hierarchy level using the back name: 
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds
The back name in your domain model (userNeeds) becomes the expand name. In columns, reference the child level directly: 
columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: Title
    hasFocus: true
The expand creates child rows in the sheet — no dot-notation needed because the expand directly opens the child level.

​
Many-to-Many (M:N) Relationships

Many-to-many relationships use an association entity between the two types. The source expand requires two levels: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
The first level (systemRequirements) is the association collection; the second level (systemRequirement) is the target entity. Column bindings use dot-notation through the association: 
columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
For M:N relationships, always use two-level expansion: the collection name (systemRequirements) followed by the singular entity name (systemRequirement). Using only the first level will expose the association entity itself, not the target entity you want to display.

​
Step 5: Validate Binding Paths Against the Model

After building your source and column configuration, use Model Helper to verify that every binding path in your columns corresponds to a valid expansion path. Cross-check each column key against the visualization:
  1. Simple property (e.g., title, description) — the property must exist on the source entity type
  2. Single-level navigation (e.g., chapter) — must match a direct or back name in a relationship from the source entity
  3. Dot-notation path (e.g., systemRequirements.systemRequirement.title) — each segment must follow a valid relationship defined in the domain model

​
Cardinality Quick Reference

CardinalityDomain ModelSource ExpandColumn BindingUI Behavior
N:1cardinality: many-to-one, direct name: chapter- name: chapterchapter, chapter.titleSingle-value reference picker
1:NReverse of N:1, back name: userNeeds- name: userNeedsuserNeedsChild rows (new hierarchy level)
M:Ncardinality: many-to-many, back name: systemRequirements- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker
After modifying your domain model (adding entity types or relationships), re-run Model Helper with an updated depth to verify that the new paths appear correctly before updating your sheet configuration.

​
Step 6: Verify Your Setup

After configuring your sheet based on Model Helper output:
  1. Open the Powersheet document that uses your sheet configuration
  2. Verify that all entity types listed in Model Helper appear as expandable levels in the sheet
  3. Confirm that column headers match the expected entity properties at each level
  4. Expand rows at each hierarchy level to confirm that relationships load correctly
  5. Test reference pickers to ensure they display the correct linked entities
You should now see your domain model relationships reflected in the sheet, with each expansion level matching the depth and navigation property names shown in Model Helper.
Open Model Helper in a separate browser tab while editing your sheet configuration YAML. This lets you quickly verify navigation property names and expansion paths without switching back and forth between configuration files.

​
See Also

Source Code
  • DomainModelV2.java
  • Relationship.java
  • Property.java
  • EntityTypeFactory.java
  • SheetConfigEnumProvider.java