This page explains the architecture of the configuration system, how its layers interact, and why the design works the way it does. For practical setup instructions, see the Sheet Configuration Guides. For a primer on YAML syntax itself, see YAML Primer for Powersheet.
Two Configuration Files, Two Responsibilities
Every Powersheet deployment relies on two distinct YAML files that serve complementary purposes:
| File | Responsibility | Analogy |
|---|
| Domain model | Defines what exists — entity types, their properties, and how they relate to each other | A database schema |
| Sheet configuration | Defines what to show — which columns to display, how to format them, and where to get the data | A report template |
The domain model defines the vocabulary; the sheet configuration uses that vocabulary to compose a specific view.
Anatomy of a Sheet Configuration
A sheet configuration file is organized into several top-level sections, each controlling a distinct aspect of the rendered sheet:
# Top-level sections of a sheet configuration
columnGroups: # Visual grouping of related columns
sortBy: # Default sort order
columns: # Column definitions with binding paths
views: # Named visibility presets
formatters: # Conditional styling rules
styles: # Reusable CSS class definitions
sources: # Data retrieval and expansion paths
Columns: The Core Building Block
The columns section is where most configuration effort goes. Each entry maps a binding path — a dot-separated property reference from the domain model — to display settings:
columns:
title:
title: "Title"
width: 300
hasFocus: true
systemRequirements.systemRequirement.title:
title: "System Requirement"
width: 250
columnGroup: sysReq
multiItem: true
display: title
title) references a simple property on the root entity. The second column (systemRequirements.systemRequirement.title) follows a navigation path through a relationship defined in the domain model: from the root entity, through the systemRequirements relationship, to the systemRequirement entity type, and finally to its title property.
Every column key in the sheet configuration must correspond to a valid path through the domain model. If a binding path references an entity type or relationship that does not exist in the domain model, the column will fail to render. The domain model acts as the contract that the sheet configuration relies on.
Column Groups: Visual Organization
Column groups cluster related columns under a shared header with consistent styling. They are purely visual — they do not affect data retrieval:
columnGroups:
sysReq:
groupName: "System Requirements"
groupStyle: blue
headerStyle: blue
collapseTo: systemRequirements.systemRequirement.title
collapseTo property specifies which column remains visible when the group is collapsed, giving users a compact summary view.
Views: Named Perspectives
Views let administrators define named column visibility presets. A single sheet configuration can offer multiple analysis perspectives — for example, a “Risk Focus” view that hides requirement columns and emphasizes risk-related fields, or a “Full Traceability” view that shows everything:
views:
riskFocus:
columns:
hazards.hazard.severity:
visible: true
systemRequirements.systemRequirement.title:
visible: false
fullTraceability:
columns:
hazards.hazard.severity:
visible: true
systemRequirements.systemRequirement.title:
visible: true
visible property of columns. Users switch between views at runtime without modifying the underlying configuration. For more on how views shape analysis workflows, see Views as Analysis Perspectives.
Formatters apply conditional styling rules to cells based on their values. A formatter definition pairs an expression (the condition) with a style (the visual effect):
formatters:
severityHighlight:
expression: "value === 'Critical'"
style: criticalStyle
styles:
criticalStyle:
backgroundColor: "#ffebee"
color: "#c62828"
isReadOnly property to true or applying a read-only formatter prevents user editing regardless of permissions. This is useful for computed or derived columns that should only be viewed, not modified.
Sources: Where Data Comes From
The sources section defines which entity types to load as root items, what query filters to apply, and how to expand related entities. Sources connect the sheet configuration to live Polarion data through the domain model:
sources:
- type: UserNeed
query: "type:userneed AND NOT HAS_VALUE:resolution"
expand:
- systemRequirements.systemRequirement
- systemRequirements.systemRequirement.designRequirements.designRequirement
Configuration Storage and Discovery
Powersheet configurations are stored in the Polarion repository (SVN) and can exist at two scopes:
- Global configurations are stored in a shared repository location, available to all projects. Their identifiers start with
/ and display with a “(Global)” suffix in the selection UI.
- Project-specific configurations are stored within a project’s repository space. Their identifiers use the filename without a path prefix.
When an administrator assigns a sheet configuration to a Polarion document, a custom field (nextedySheetConfig) stores the configuration file reference. Powersheet dynamically discovers all available configuration files at both scopes and presents them as selectable options through the Administration > Nextedy POWERSHEET interface.
Users must explicitly select a configuration for each Powersheet document. There is no automatic default assignment — this is deliberate, because every document’s data model and column needs differ. The system does include a bundled powersheet.yaml as a starter template, accessible through the built-in configuration editor.
Configuration Scoping: Instance, Template, Default
The configuration editor supports three levels of scope that allow fine-grained override control:
| Scope | Purpose | Precedence |
|---|
| Instance | Per-document overrides for a specific Powersheet | Highest |
| Template | Shared configuration template used across multiple documents | Middle |
| Default | Global fallback defaults | Lowest |
How Configuration Becomes a Sheet
Understanding the runtime flow helps clarify why the configuration is structured the way it is:
-
Load — Powersheet reads the YAML configuration from the repository location stored in the document’s custom field. If the file cannot be read or parsed, an error is surfaced (YAML parse errors are logged but do not crash the application).
-
Validate against domain model — Column binding paths are resolved against the domain model. Each dot-separated segment must match a known property or navigation path. Unresolvable paths produce rendering failures for those specific columns.
-
Fetch metadata — The metadata system translates entity types and relationships from the domain model into a queryable schema that the client uses for data retrieval.
-
Execute sources — Source definitions trigger queries against Polarion, filtered by the specified query expressions. Expansion paths are followed to load related entities at each hierarchy level.
-
Render — Columns are laid out according to their defined widths, groups, and visibility settings. Formatters evaluate their expressions against cell values and apply styles. Views determine which columns are visible in the current perspective.
The Domain Model as Contract
The domain model is not just a separate file — it is the contract that all sheet configurations must honor. It defines:
- Entity types via
domainModelTypes — each mapping a logical name (like UserNeed or SystemRequirement) to a Polarion work item type through the polarionType property
- Properties — the fields available on each entity type, which become valid column binding targets
- Relationships — the navigation paths between entity types, including cardinality (one-to-one vs. one-to-many) and direction (direct vs. back)
When a sheet configuration references systemRequirements.systemRequirement.title, the domain model must define: (1) a relationship called systemRequirements on the root entity, (2) that relationship’s target entity type SystemRequirement, and (3) a title property on that entity type.
For deeper coverage of domain model concepts, see Model-Driven Design and Entity Types and Relationships.
Common Misconceptions
A frequent source of support issues is attempting to build a complex multi-entity configuration from scratch. The recommended approach is to start with a minimal single-entity setup — one source, a few columns — verify it renders correctly, and then add complexity incrementally. Each addition (a new relationship path, a column group, a formatter) can be validated independently before moving on.
title property within each column definition controls the display label. Two columns can have the same display title but different binding paths.
“Global configurations override project configurations.” They coexist as separate options in the selection list. A global configuration is simply one that is available to all projects. There is no inheritance or override relationship between global and project-specific configurations — a document uses exactly one configuration file.
Configuration Editor
Powersheet includes a built-in YAML editor accessible through the Polarion interface. The editor provides:
- Syntax-aware editing with support for both YAML and JSON content languages
- JSON Schema validation that checks your configuration against the expected structure
- Language conversion — content can be switched between JSON and YAML representations
- Scope awareness — the editor shows which scope level (instance, template, or default) you are editing
- History — links to revision history for tracking configuration changes over time
The editor supports optional Vim keybinding mode and line wrapping toggles, with preferences persisted in the browser. Theme styling adapts to match the Powersheet product branding.
Relationship to Other Concepts
The YAML configuration system is the foundation that connects most other Powersheet concepts:
For hands-on guidance, the Data Model Guides and Sheet Configuration Guides walk through practical setup scenarios step by step. 
