Configuration Hierarchy - Nextedy Documentation

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

This three-tier structure applies equally to both data models (entity types and relationships) and sheet configurations (column layout, views, formatters, sources). Think of it like CSS specificity: the most specific scope wins. A project-level configuration always takes precedence over a global one when both are candidates for the same document.

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`

The (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

These properties are configured through Polarion’s standard project properties mechanism, separate from the YAML file management interface.

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

The binding path 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

Powersheet provides predefined header styles such as 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.

YAML Configuration System — how YAML configuration files are structured and parsed
Data Model vs Sheet Configuration — understanding the two configuration layers
Source Configuration — how sources reference data models by name
Powersheet Architecture — where configuration fits in the overall system
Core Components — the building blocks that consume configuration
Creating Your First Sheet Configuration — hands-on tutorial for building your first sheet configuration
Creating Your First Data Model — step-by-step tutorial for data model setup

For practical guidance on working with configurations at different scopes, see:

Assign Configuration to Document — selecting a configuration for a Powersheet document
Administration Guides — managing configurations across projects

​The Configuration Hierarchy

​The Two Configuration Layers

​Why a Layered Hierarchy Matters

​What Gets Scoped: The Two Configuration Layers

​Data Models

​Sheet Configurations

​How Configuration Resolution Works

​The Picker Experience

​Administration at Each Scope Level

​Propagating Changes Across Projects

​Configuration Hierarchy Decision Matrix

​The Role of Project-Specific Properties

​Common Misconceptions

​Configuration Editor Scopes

​Key YAML Patterns

​Columns Use Dot-Notation Binding Paths

​Styles and Anchors Reduce Repetition

​Column Groups Organize Related Columns

​Practical Example: Multi-Project Setup

​Related Pages

The Configuration Hierarchy

The Two Configuration Layers

Why a Layered Hierarchy Matters

What Gets Scoped: The Two Configuration Layers

Data Models

Sheet Configurations

How Configuration Resolution Works

The Picker Experience

Administration at Each Scope Level

Propagating Changes Across Projects

Configuration Hierarchy Decision Matrix

The Role of Project-Specific Properties

Common Misconceptions

Configuration Editor Scopes

Key YAML Patterns

Columns Use Dot-Notation Binding Paths

Styles and Anchors Reduce Repetition

Column Groups Organize Related Columns

Practical Example: Multi-Project Setup

Related Pages