Incremental Configuration Approach

​

Why incremental matters

Powersheet requires two YAML files working in concert: a domain model that defines entity types and their relationships, and a sheet configuration that defines columns, sources, and views. These files are tightly coupled. The sheet configuration references navigation property names from the domain model, uses entity types defined there, and constructs binding paths that traverse the relationship graph. When both files are written from scratch with their full intended complexity, any mismatch between them produces errors that look similar regardless of the underlying cause. A misspelled navigation property name, a missing entity type, an incorrect relationship direction, or a malformed binding path can all surface as vague loading failures or empty sheets. The incremental approach works because each layer introduces a bounded set of new concepts. When something breaks, you know it was caused by the most recent change, not by an interaction between dozens of configuration elements.

​

The layered configuration model

Think of Powersheet configuration as stacking blocks. Each layer adds one capability on top of a working, validated foundation. You never move to the next layer until the current one works correctly.

​

Layer 1: Single entity type

Start with just one entity type in the domain model and two or three columns in the sheet configuration. The goal is to prove that the fundamental wiring between Powersheet, the domain model, and Siemens Polarion ALM works correctly. At this stage, your domain model defines a single entity type with its polarionType mapping, and your sheet configuration references that model and exposes basic properties like title and severity. What you are validating:

• The domain model YAML loads without parse errors
• The polarionType mapping correctly connects the entity type to a Polarion work item type
• The sheet configuration’s model reference resolves to your domain model file
• The sheet queries data and displays rows
• Basic column bindings (direct properties like title, severity) render values

What to check if it fails: Once Layer 1 works, you have a known-good baseline. Every subsequent change is measured against this working state.

​

Layer 2: One relationship

Add a second entity type and define a single relationship between the two. This is where configuration complexity increases significantly, because you are now dealing with navigation properties, expansion paths, and cross-entity binding paths. For example, add SystemRequirement as a second entity type and create a relationship from UserNeed to SystemRequirement. In the sheet configuration, add an expand entry to the source and new columns that use binding paths traversing the relationship. What you are validating:

• Relationship navigation property names (direct.name, back.name) are correctly defined in the domain model
• The expand section in the source configuration references the correct navigation property
• Binding paths like systemRequirements.systemRequirement.title resolve correctly across the relationship
• Expanding a row in the sheet shows child items from the related entity type

Common misconceptions at this layer: A frequent source of confusion is the direction of navigation properties. When you define a relationship between UserNeed and SystemRequirement, the direct property is the name used to navigate from the source entity to the target, and the back property navigates in reverse. These names must match exactly between the domain model relationship definition and the sheet configuration’s expansion and column binding paths.

​

Layer 3: Deeper hierarchy

With two entity types and one relationship working, add a third entity type and a second relationship to create a multi-level hierarchy. This is where you validate that Powersheet can handle nested expansion paths. For example, add DesignRequirement with a relationship from SystemRequirement. This creates a three-level hierarchy: UserNeed > SystemRequirement > DesignRequirement. Your binding paths now span multiple levels, such as systemRequirements.systemRequirement.designRequirements.designRequirement.title. What you are validating at this layer:

• Multi-level expansion paths resolve correctly through nested relationships
• Column groups can organize columns from different entity types visually
• Views (named column visibility presets) correctly show and hide columns per analysis perspective
• Constraints, if added, enforce the intended creation and linking rules

This is also the right stage to introduce views. With three entity types generating many columns, views let you define named presets that show only the columns relevant to a particular analysis perspective. For instance, a “Requirements Coverage” view might show UserNeed and SystemRequirement columns while hiding DesignRequirement details. What to check if multi-level expansion fails:

​

Layer 4: Full configuration

Once the three-level hierarchy is proven, add the remaining entity types, constraints, formatters, column groups, and any cross-entity features your domain requires. For a full RTM, this means adding entity types like Hazard and RiskControl, along with their relationships and dedicated columns. At this point, each addition is isolated. If adding Hazard breaks something, you know the issue is in the Hazard entity type definition, its relationship, or its column bindings, not in the foundation you already validated. Features to add at Layer 4:

• Additional entity types with their relationships and expansion paths
• Formatters for conditional cell styling based on values
• Column groups with color-coded headers for visual organization (columnGroups with groupName, groupStyle, headerStyle)
• Sort and grouping defaults (sortBy at the sheet level, groupBy and sort on individual columns)
• Entity factories for creating new work items directly from the sheet
• Constraints that control which items can be created or linked

​

The validation loop

The incremental approach follows a consistent loop at every layer:

1. Add one thing — a new entity type, a relationship, a column group, a constraint
2. Reload the sheet — open the Powersheet document in the browser to test
3. Verify it works — check that data loads, columns render, expansion functions
4. Diagnose if it fails — the cause is isolated to your most recent change
5. Commit when stable — save the working configuration before moving to the next addition

This loop is analogous to test-driven development in software engineering. You never write the entire program and then test it. Instead, you build and verify in small increments, ensuring each piece works before adding the next.

​

How Powersheet architecture supports this

Several architectural features of Powersheet make the incremental approach practical: Configuration files are independent. The domain model and sheet configuration are separate YAML files managed through Administration > Nextedy POWERSHEET. You can update one without touching the other, and the sheet reloads configuration on each page load. Domain models are additive. Adding a new entity type or relationship to the domain model does not affect existing types. The metadata system discovers entity types from the model and makes them available for binding. Existing columns continue to work as before. Sources and expansion are declarative. The expand section in a source configuration explicitly lists which relationships to traverse. Adding a new entity type to the domain model does not automatically add it to the sheet. You must explicitly configure expansion and columns, which keeps each addition deliberate and reviewable. Views provide isolation. Named views let you create focused perspectives that show only the columns you are currently working with. When adding Layer 3 columns, you can create a temporary view that shows only those columns, making it easier to verify they work without visual clutter from existing columns. Configuration scoping supports gradual rollout. Both domain models and sheet configurations support project-level and global scoping. You can develop and test a configuration at the project level before promoting it to a global configuration shared across projects. The default configuration ships with Powersheet. Every installation includes a bundled default configuration (powersheet.yaml) that serves as both a reference and a starting point. You can examine how it structures columns, sources, and expansion to understand the patterns before writing your own.

​

When to deviate from the layers

The four-layer model is a guideline, not a rigid process. Some situations call for a different ordering:

• If your domain has a flat structure (no hierarchies), you may only need Layers 1 and 4. Define all entity types as independent sources without expansion paths.
• If you are migrating from an existing configuration, start by importing it and validating it works, then refactor incrementally rather than rebuilding from scratch.
• If you need constraints early (for instance, to prevent accidental data creation during testing), add them at Layer 2 rather than waiting for Layer 4.

The principle remains the same: change one thing, verify, then move on.

​

Common validation pitfalls

Based on support patterns, these are the errors most frequently seen during initial configuration: 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, making root cause analysis far more difficult.

​

Next steps

For hands-on tutorials that follow this incremental approach:

• Creating Your First Data Model covers Layer 1 in detail
• Creating Your First Sheet Configuration walks through source and column setup
• Creating Your First Powersheet Document shows how to connect configuration to a LiveDoc

For reference material on domain model and sheet configuration properties:

• Data Model Reference
• Sheet Configuration Reference

For task-oriented guidance on specific configuration topics:

• Data Model Guides
• Sheet Configuration Guides