Skip to main content

​
Symptom Quick Reference

Use this table to jump to the right fix based on the error you are seeing:
SymptomLikely CauseJump To
Sheet fails to load after saving the domain modelInvalid from or to entity referenceStep 1: Verify Entity Type References
Navigation columns appear emptyMissing or wrong direct/back nameStep 2: Check Navigation Property Names
Expansion path produces no child rowsNavigation name mismatch between model and sourcesStep 3: Align Sources with Navigation Names
Links not saved to PolarionInvalid linkRole valueStep 4: Verify the Link Role
Wrong column behavior (multi vs. single)Cardinality does not match the actual relationshipStep 5: Validate Cardinality
Second linked column shows nothingMissing multiItem: true on the columnStep 6: Fix Multi-Item Column Declarations

​
Step 1: Verify Entity Type References

Every relationship must reference valid entity type names in its from and to fields. These names must exactly match keys defined under domainModelTypes, including capitalization. 
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

relationships:
  - from: UserNeed              # Must match a domainModelTypes key exactly
    to: SystemRequirement       # Must match a domainModelTypes key exactly
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
Entity type names are case-sensitive. systemRequirement and SystemRequirement are different values. If the from value does not match any domainModelTypes key, the source side of the relationship is broken. If the to value is wrong, the target side is broken. Double-check exact capitalization in both locations.

​
Step 2: Check Navigation Property Names

The direct and back sections each contain a name field that creates a navigation property on the respective entity type. These navigation property names are what you use in column binding paths and source expansion paths throughout the sheet configuration.
  • direct.name — creates a forward navigation property on the from entity type (navigates toward the to entity)
  • back.name — creates a reverse navigation property on the to entity type (navigates back toward the from entity)
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds              # Property on SystemRequirement pointing back to UserNeed
    back:
      name: systemRequirements     # Property on UserNeed pointing forward to SystemRequirement
diagram
If either direct or back is missing its name field, the corresponding navigation property will not be created. Any column or expansion path that references that property name will silently return no data.

​
Step 3: Align Sources with Navigation Names

The expand entries in your sheet configuration sources must exactly match the navigation property names defined by direct.name or back.name in the domain model. A mismatch here is one of the most common causes of empty expansion results. Many-to-one (N:1) — single-level expand: 
# Domain model: UserNeed -> Chapter, direct.name = "chapter"
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter           # Must match direct.name exactly
One-to-many (1:N) — collection expand: 
# Domain model: Chapter <- UserNeed, back.name = "userNeeds"
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds         # Must match back.name exactly
Many-to-many (M:N) — two-level expand through association: 
# Domain model: UserNeed <-> SystemRequirement, back.name = "systemRequirements"
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements          # Association level
        expand:
          - name: systemRequirement       # Target entity level
Many-to-many relationships use an association entity between the two types. The source expand must go two levels deep: first the collection navigation property (e.g., systemRequirements), then the target entity within the association (e.g., systemRequirement). Forgetting the second level is a frequent cause of empty columns.
The linkRole must match a link role ID defined in your Polarion project configuration, not its display name. 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes          # Polarion link role ID, not display name
    direct:
      name: userNeeds
    back:
      name: systemRequirements
To find valid link role IDs, go to Administration > Work Items > Link Roles in Polarion. The ID column shows the value to use in your domain model YAML.
The linkRole value is the link role ID (e.g., decomposes, parent), not the display name (e.g., “Decomposes”, “Has Parent”). If the link role ID does not exist in the project, relationships will not persist when users save changes in the sheet.

​
Step 5: Validate Cardinality

The cardinality value must match the actual relationship between your entity types. Using the wrong cardinality causes incorrect UI behavior — columns that should allow multiple selections only show one value, or vice versa.
CardinalitySource ExpandColumn BindingUI Behavior
many-to-one- name: chapterchapter, chapter.titleSingle-value reference picker
one-to-many- name: userNeedsuserNeedsChild rows (new sheet level)
many-to-many- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker
A many-to-one column displays a single-value reference picker. A one-to-many expand creates child rows in the sheet. A many-to-many column uses a multi-item picker with association entity binding. If you set the wrong cardinality, the sheet may render but users will encounter errors when trying to edit or save relationships.

​
Step 6: Fix Multi-Item Column Declarations

When a parent entity links to multiple work item types (for example, a SystemRequirement linked to both DesignRequirement and DesignVerification), the second linked column must include multiItem: true in the sheet configuration. This is a non-obvious requirement that frequently blocks first-time configurations. 
columns:
  designRequirements.designRequirement:
    title: Design Requirement
    list:
      search:
        - title
  designVerifications.designVerification:
    title: Design Verification
    multiItem: true               # Required for the second linked entity column
    list:
      search:
        - title
When setting up a new sheet, start with the simplest possible configuration — one entity type, one relationship. Add additional linked columns incrementally. This approach makes it much easier to isolate which relationship definition is causing errors.

​
Step 7: Validate the Complete Configuration Chain

After making corrections, verify the full chain from domain model through sources to columns:
  1. Domain model — confirm from/to match domainModelTypes keys, linkRole is a valid Polarion link role ID, and both direct.name and back.name are present
  2. Sources — confirm each expand name matches a navigation property name from the domain model, and many-to-many expands have two levels
  3. Columns — confirm column binding paths use the correct dot-notation from the expand chain, and multiItem: true is set where needed
  4. Storage — confirm storage: linkedWorkItems is used for Polarion link-based relationships

​
Verification

After correcting the relationship configuration:
  1. Save the domain model YAML in Administration > Nextedy POWERSHEET > Domain Models
  2. Open a powersheet document that uses this domain model
  3. Expand a row with related entities
  4. You should now see child entities appearing correctly under the expansion path, and the reference picker columns displaying valid choices

​
See Also

Support TicketsSource Code
  • DomainModelV2.java
  • Relationship.java