The Configuration Hierarchy
Powersheet configuration operates at three scope levels, each with its own storage location in the Polarion repository:
| Scope | Storage Location | Visibility | When to Use |
|---|
| Repository (Global) | Global configuration directory | All projects in the instance | Shared standards, common traceability models |
| Project Group | Group-level configuration directory | All projects in the group | Division or program-level customizations |
| Project | Project-level configuration directory | Only the specific project | Project-unique layouts, experiments |
The Two Configuration Layers
Powersheet relies on two distinct YAML files that serve complementary roles. Think of it like a blueprint: the data model defines what types of rooms exist and how they connect, while the sheet configuration defines how each room looks and what furniture it contains.
Data model (domainModelTypes, relationships) — Defines the semantic layer: entity types — for example, UserNeed, SystemRequirement, and DesignRequirement in an RTM model — their properties, and how they relate to each other. Managed through Administration > Nextedy Powersheet > Data Models. One data model can be shared across many sheet configurations.
Sheet configuration (columns, views, styles, sources) — Defines the presentation layer: which columns appear, how they are styled, what data sources to query, and what views are available. Stored as a YAML file associated with a specific powersheet document via the nextedySheetConfig custom field.
Because the data model and sheet configuration are separate files, you can reuse the same data model across different sheet configurations. For example, one RTM model can power both a requirements traceability sheet and a risk analysis sheet — each with different columns and views.
Why a Layered Hierarchy Matters
In enterprise environments, multiple Polarion projects often share the same engineering methodology. A medical device program might have separate projects for hardware, software, and system integration, but all three follow the same traceability model — for example, UserNeed to SystemRequirement to DesignRequirement to Hazard to RiskControl. Without a global scope, administrators would need to duplicate identical data models and sheet configurations in every project.
The hierarchy addresses three organizational realities:
Consistency at scale. A global data model ensures that all projects use the same entity types, relationship definitions, and property names. When compliance auditors review traceability across projects, the structure is uniform.
Local flexibility. Individual projects may need to map entity types to different Polarion work item types (different polarionType values), add project-specific columns, or experiment with new layouts before standardizing.
Incremental rollout. New configurations can be tested at project level, promoted to project group level once proven, and eventually elevated to global scope for organization-wide adoption.
What Gets Scoped: The Two Configuration Layers
Powersheet manages two distinct types of configuration files, and both follow the same scoping rules:
Data Models
Data models define entity types, their properties, relationships, and cardinality. A global data model establishes the canonical traceability structure. Project-specific data models can:
- Map the same entity types to different Polarion work item types via
polarionType
- Add relationships unique to a single project
- Define project-specific constraints for picker filtering (e.g., restricting
moduleFolder or type in the pick section)
When a sheet configuration references a data model by name through its sources section, Powersheet resolves that name against both global and project-level directories.
Sheet Configurations
Sheet configurations define columns, column groups, views, formatters, sort order, and source expansion paths. A global sheet configuration provides a standard layout; project-specific configurations can modify column visibility, add custom columns, or define different conditional formatting rules.
The SheetConfigEnumProvider dynamically discovers available configuration files and presents them in the picker on each Powersheet document:
- Global configurations: ID starts with
/, display name includes a (Global) suffix
- Project-specific configurations: ID is the filename without path, display name is the filename without extension
All discovered configurations from both scopes appear together in the same picker list.
How Configuration Resolution Works
Understanding the resolution process is critical for predicting which configuration a document will use. Here is the sequence:
-
A Powersheet document loads. The document has a custom field (
nextedySheetConfig) that stores the selected sheet configuration identifier.
-
The configuration service resolves the identifier. If the identifier starts with
/, the service looks in the global configuration directory. Otherwise, it looks in the project-specific directory.
-
The sheet configuration references a data model by name. The
sources.model property in the YAML points to a model name (not a file path).
-
The model is resolved. Powersheet scans both global and project-specific model directories. If a model with the same name exists at both levels, the project-specific model takes precedence for that project.
The sources.model property must match the name of the model file, not a default value like rtm. New users frequently leave this as the default, causing the sheet to fail to connect to the correct data model. Always verify that the model name in your sheet configuration matches an actual model file at either the global or project level.
The Picker Experience
When a user opens a Powersheet document and selects a configuration, the picker shows a combined list:
| Display Name | Source | ID Format |
|---|
rtm-standard (Global) | Global directory | /rtm-standard |
medical-rtm (Global) | Global directory | /medical-rtm |
project-custom | Project directory | project-custom |
pilot-layout | Project directory | pilot-layout |
(Global) suffix is the visual signal that a configuration is shared. Project-specific files appear by filename alone.
Powersheet does not define a default sheet configuration. Each document must have a configuration explicitly selected. If the nextedySheetConfig field is empty, the document will not render a sheet.
Administration at Each Scope Level
Powersheet integrates into Polarion’s native administration interface, adding pages under Administration > Nextedy Powersheet for:
- Data Models — manage data model YAML files
- Sheet Configurations — manage sheet configuration YAML files
- Setup — initial Powersheet configuration
- License — license management
Each administration page is available at all three scope levels: project, project group, and repository (global). The scope is determined by where the administrator navigates in Polarion’s administration hierarchy before opening the Powersheet section.
The embedded file manager interface supports creating, editing, and deleting YAML files within the selected scope. When editing at repository scope, changes affect all projects that reference global configurations.
Propagating Changes Across Projects
One of the key advantages of global configurations is centralized updates. When you modify a global data model or sheet configuration, every project that references it picks up the change on next load — no per-project edits required.
However, this also means that a breaking change in a global configuration can affect every project simultaneously. Consider these strategies:
Staged rollout. Create a new version of the configuration at project level first. Test it in a pilot project. Once validated, promote it to global scope.
Naming conventions. Use versioned names for global configurations (e.g., rtm-v2, rtm-v3) so that projects can opt in to new versions at their own pace rather than being forced into an immediate upgrade.
Project-level overrides as safety nets. If a project has unique needs that might conflict with global changes, define a project-specific configuration. It will always take precedence over the global one, insulating the project from upstream changes.
The project group scope provides a middle ground. If your organization uses Polarion project groups to organize related projects (e.g., all projects in a product line), you can define configurations at the group level. These override global configurations but are themselves overridden by project-level configurations.
Configuration Hierarchy Decision Matrix
Use this matrix to decide where to place your configuration files:
| Question | If Yes | If No |
|---|
| Will more than one project use this configuration? | Global or Project Group | Project |
| Does it define a standard traceability model? | Global | Project Group or Project |
| Is it an experiment or prototype? | Project | Promote later if successful |
| Does it need to override a global standard? | Project (same name overrides) | Use global as-is |
| Is it specific to a product line or division? | Project Group | Global or Project |
The Role of Project-Specific Properties
Beyond YAML configuration files, Powersheet reads project-level properties from Polarion’s configuration system. These properties control runtime behavior and are always project-specific (not subject to the global/project hierarchy):
| Property | Purpose | Default Behavior |
|---|
| Powersheet document query | Lucene query identifying which documents appear in Powersheet Drive | Searches for documents with nextedySheetConfig populated |
| Sheet configuration field ID | Custom field linking documents to their configuration | nextedySheetConfig |
| Open button title | Text displayed on the “Open in Powersheet” button | Customizable per project for branding |
| Template document query | Query to identify template documents for duplication | Same as document query by default |
Common Misconceptions
“Project configurations inherit from global and merge.” This is not how it works. Powersheet does not merge a global model with a project model. If a project defines its own model file with the same name, the entire project-level file replaces the global one for that project. There is no property-level merging.
“I need to copy the global configuration to customize it.” Not necessarily. You can create a completely new project-specific configuration with a different name. The document’s nextedySheetConfig field determines which configuration is used — you simply select the project-specific one instead of the global one.
“Global configurations are read-only.” Global configurations are fully editable at repository scope in the administration interface. However, editing them requires repository-level administration access, which is typically restricted to system administrators.
Configuration Editor Scopes
Beyond the repository-level hierarchy (global, project group, project), the configuration editor exposes three additional scope levels within a single document:
- Instance — A per-document override. Changes at this level apply only to the specific Powersheet document being edited.
- Template — Template-level defaults. When a document is created from a template, it inherits these settings.
- Default — The global baseline from the YAML file itself.
This layered approach means teams can share a base configuration while allowing individual documents to override specific settings without modifying the shared file.
Although some internal field names reference JSON for historical reasons, all user-facing configuration files use YAML syntax. The configuration editor supports both formats and can convert between them, with YAML as the preferred language.
Key YAML Patterns
Columns Use Dot-Notation Binding Paths
Column keys in the sheet configuration use dot-separated paths that trace the expansion path through entity relationships:
columns:
title:
title: Title
width: 200
systemRequirements.systemRequirement.title:
title: System Req Title
width: 180
systemRequirements.systemRequirement.title means: follow the systemRequirements expansion, select the systemRequirement entity, and display its title property.
Styles and Anchors Reduce Repetition
YAML anchors (&) and aliases (*) allow you to define a style once and reuse it across multiple columns:
styles:
readOnlyStyle:
backgroundColor: 'grey100'
columns:
outlineNumber:
title: "#"
width: 80
header:
style: darkgrey
red, blue, green, purple, and their variants (darkred, lightblue, etc.) that map to the built-in design token palette.
The columnGroups section visually groups related columns under a shared header with optional collapse behavior:
columnGroups:
epic:
groupName: Epics
groupStyle: darkgreen
headerStyle: green
collapseTo: title
Practical Example: Multi-Project Setup
Consider an organization with three projects sharing a medical device traceability model:
- Global data model (
medical-rtm): Defines UserNeed, SystemRequirement, DesignRequirement, Hazard, and RiskControl entity types with standard relationships
- Global sheet configuration (
medical-standard): Standard column layout with traceability columns, risk assessment groups, and compliance views
- Project HW uses
medical-standard (Global) as-is
- Project SW uses
medical-standard (Global) but adds a project-specific data model that maps DesignRequirement to a different Polarion work item type
- Project Integration defines its own
integration-layout sheet configuration with additional cross-reference columns, while still using the global medical-rtm data model
Each project selects its configuration through the document-level picker. The global configurations provide the baseline, and projects customize only what they need.
Related Pages
For practical guidance on working with configurations at different scopes, see:
