Skip to main content
This page explains why an incremental approach to configuration is essential, and how the architecture of Powersheet supports building complexity one layer at a time.

​
The core problem

Powersheet requires two YAML files to work together: a domain model (defining entity types and relationships) and a sheet configuration (defining columns, sources, and views). These files reference each other — the sheet configuration uses navigation property names from the domain model, and queries entity types defined there. When both files are written from scratch with full complexity, any mismatch between them produces errors that are difficult to trace. A typo in a navigation property name, a missing entity type reference, or an incorrect relationship direction can all produce similar-looking failures.
Support data shows that jumping straight to complex multi-entity configurations is the most common cause of setup errors. Users who start with a single entity type and extend incrementally report far fewer issues.

​
The layered model

Think of Powersheet configuration as building with blocks. Each layer adds one capability on top of a working foundation: diagram
The layers below use RTM entity types as an example. Apply the same incremental approach with whatever entity types your domain requires.

​
Layer 1: Single entity type

Start with just one entity type in the domain model and two or three columns in the sheet configuration. This validates that:
  • The domain model loads without errors
  • The polarionType mapping is correct
  • The sheet configuration can query and display data
  • The model reference in the sheet configuration resolves

​
Layer 2: One relationship

Add a second entity type and a single relationship. This validates that:
  • Navigation property names (fromNavPropName, toNavPropName) are correct
  • The expand section in the source configuration works
  • Binding paths like systemRequirements.systemRequirement resolve correctly

​
Layer 3: Deeper hierarchy

Add a third entity type with nested expansion. This validates that multi-level expansion paths like systemRequirements.systemRequirement.designRequirements.designRequirement work correctly.

​
Layer 4: Full configuration

Add constraints, views, entity factories, and additional entity types. At this point the foundation is proven and each addition is isolated to a single change.

​
Why this works

Powersheet processes domain model and sheet configuration through several stages. First, the domain model YAML is loaded and its entity types are translated into a metadata structure. Then the sheet configuration is loaded, columns are resolved against the metadata, and data sources execute their queries with the specified expansion paths. When an error occurs at any stage, having only one new change since the last working state makes the cause obvious. The alternative — writing the entire configuration at once — means any of dozens of possible mismatches could be the cause.

​
Configuration scope

Both domain models and sheet configurations support two levels of scope:
ScopeLocationUse case
ProjectProject-level administrationProject-specific entity types and columns
GlobalGlobal administration (shown with “(Global)” suffix)Shared configurations reused across projects
Global configurations can be overridden at the project level. This means you can start with a global template and customize it per project, following the same incremental principle at the organizational level.
Use global configurations for standard domain models that apply across projects (e.g., a company-wide RTM structure). Use project-level configurations for project-specific column layouts and views.

​
Common validation pitfalls

Based on support patterns, these are the errors most frequently seen during initial configuration:
Error patternLikely cause
Model fails to loadEntity type name contains spaces or special characters
”Left error” in relationshipsfrom value does not match any domainModelTypes name
”Right error” in relationshipsto value does not match any domainModelTypes name
Columns show no dataBinding path uses wrong navigation property name
Sheet shows no rowsquery.from uses Polarion type ID instead of entity type name
Each of these errors is immediately identifiable when only one change was made since the last working configuration. In a full configuration written from scratch, any combination of these could occur simultaneously.

​
Practical starting points

For hands-on tutorials that follow this incremental approach: For deeper understanding of the configuration files themselves:
  • Concepts — architecture and design principles
  • Reference — complete property documentation
KB ArticlesSupport TicketsSource Code
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/e2e/userFlows/multiple-entity-type-flow.cy.ts
  • prod-powersheet-src/com.nextedy.powersheet/src/META-INF/hivemodule.xml
  • prod-powersheet-src/com.nextedy.powersheet/src/com/nextedy/powersheet/PowersheetDocumentConfigurationService.java
  • prod-powersheet-src/com.nextedy.powersheet/src/com/nextedy/powersheet/PowersheetService.java
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/ConfigProvider/ConfigProvider.tsx