> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Incremental Configuration Approach
> Nextedy POWERSHEET configurations are powerful. A single data model and sheet configuration can express complex multi-level traceability hierarchies with constraints, custom columns, and dynamic expressions -- so build them incrementally to keep configuration errors easy to isolate.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
## Why incremental matters
Powersheet requires two YAML files working in concert: a **data 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 data 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.
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 experience far fewer issues and resolve problems faster.
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.
The layers below use RTM entity types (`UserNeed`, `SystemRequirement`, `DesignRequirement`, `Hazard`, `RiskControl`) as a running 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 data model and two or three columns in the sheet configuration. The goal is to prove that the fundamental wiring between Powersheet, the data model, and Siemens Polarion ALM works correctly.
At this stage, your data 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 data 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 data 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:**
| Symptom | Likely cause |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| Sheet shows "Configuration error" | YAML syntax error in data model or sheet configuration |
| Sheet loads but shows no rows | `polarionType` does not match any existing work item type in the project |
| Column shows blank cells | Column binding path does not match a property name on the entity type |
| "Model not found" error | The `model` value in the sheet configuration does not match the data model filename |
Use the Polarion administration interface at **Administration > Nextedy Powersheet > Data Models** to verify your data model file is recognized before troubleshooting the sheet configuration.
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 data 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 data model relationship definition and the sheet configuration's expansion and column binding paths.
A mismatch between the navigation property name in the data model and the binding path in the sheet configuration is the single most common error at Layer 2. Double-check that the property name used after the dot in your column binding path exactly matches the `direct.name` or `back.name` value from the relationship definition.
## 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:**
| Symptom | Likely cause |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Second-level children do not appear | The second relationship's navigation property is not referenced in the nested `expand` |
| Columns show data for wrong entity type | Binding path skips a level or uses incorrect navigation property name |
| Expansion works but columns are empty | The binding path after the last navigation property does not match a real property on the target entity |
## 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.
Keep a copy of your last known-good configuration at each layer. If an addition breaks things and you cannot quickly identify the cause, reverting to the previous working state and trying again is faster than debugging a complex, multi-change failure.
## How Powersheet architecture supports this
Several architectural features of Powersheet make the incremental approach practical:
**Configuration files are independent.** The data 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.
**Data models are additive.** Adding a new entity type or relationship to the data 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 data 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 data 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:
| Error pattern | Likely cause | Layer |
| ---------------------------------------------- | ------------------------------------------------------------------------------- | ----- |
| Data model fails to load | YAML syntax error or entity type name contains invalid characters | 1 |
| Sheet loads with no rows | `polarionType` does not match any work item type in the project | 1 |
| Columns show no data after adding relationship | Binding path uses wrong navigation property name | 2 |
| Expansion shows no children | `expand` references a navigation property that does not exist in the data model | 2 |
| Multi-level path resolves partially | Intermediate relationship navigation property is misspelled | 3 |
| Column group does not appear | `columnGroup` value on the column does not match any `columnGroups` key | 4 |
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](/powersheet/getting-started/first-data-model) covers Layer 1 in detail
* [Creating Your First Sheet Configuration](/powersheet/getting-started/first-sheet-configuration) walks through source and column setup
* [Creating Your First Powersheet Document](/powersheet/getting-started/first-document) shows how to connect configuration to a LiveDoc
For reference material on data model and sheet configuration properties:
* [Data Model Reference](/powersheet/reference/data-model/index)
* [Sheet Configuration Reference](/powersheet/reference/sheet-config/index)
For task-oriented guidance on specific configuration topics:
* [Data Model Guides](/powersheet/guides/data-model/index)
* [Sheet Configuration Guides](/powersheet/guides/sheet-configuration/index)