Skip to main content

​
The Configuration Hierarchy

Powersheet configuration operates at three scope levels, each with its own storage location in the Polarion repository:
ScopeStorage LocationVisibilityWhen to Use
Repository (Global)Global configuration directoryAll projects in the instanceShared standards, common traceability models
Project GroupGroup-level configuration directoryAll projects in the groupDivision or program-level customizations
ProjectProject-level configuration directoryOnly the specific projectProject-unique layouts, experiments
This three-tier structure applies equally to both domain 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. diagram

​
The Two Configuration Layers

Powersheet relies on two distinct YAML files that serve complementary roles. Think of it like a blueprint: the domain 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. diagram Domain 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 > Domain Models. One domain 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 domain model and sheet configuration are separate files, you can reuse the same domain 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 domain models and sheet configurations in every project. The hierarchy addresses three organizational realities: Consistency at scale. A global domain 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:

​
Domain Models

Domain models define entity types, their properties, relationships, and cardinality. A global domain model establishes the canonical traceability structure. Project-specific domain 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 domain 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:
  1. A Powersheet document loads. The document has a custom field (nextedySheetConfig) that stores the selected sheet configuration identifier.
  2. 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.
  3. The sheet configuration references a domain model by name. The sources.model property in the YAML points to a model name (not a file path).
  4. 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 domain 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 NameSourceID Format
rtm-standard (Global)Global directory/rtm-standard
medical-rtm (Global)Global directory/medical-rtm
project-customProject directoryproject-custom
pilot-layoutProject directorypilot-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 domain 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 domain 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:
QuestionIf YesIf No
Will more than one project use this configuration?Global or Project GroupProject
Does it define a standard traceability model?GlobalProject Group or Project
Is it an experiment or prototype?ProjectPromote 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 GroupGlobal 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):
PropertyPurposeDefault Behavior
Powersheet document queryLucene query identifying which documents appear in Powersheet DriveSearches for documents with nextedySheetConfig populated
Sheet configuration field IDCustom field linking documents to their configurationnextedySheetConfig
Open button titleText displayed on the “Open in Powersheet” buttonCustomizable per project for branding
Template document queryQuery to identify template documents for duplicationSame 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 domain 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 domain 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 domain model
Each project selects its configuration through the document-level picker. The global configurations provide the baseline, and projects customize only what they need. For practical guidance on working with configurations at different scopes, see:
KB ArticlesTickets
  • Configuration setup guidance: incremental approach recommended for new users
  • Model connection errors: sources.model must match actual model file name
  • Multi-item column configuration for linked work item types
Source Code
  • SheetConfigEnumProvider.java — dynamic enum provider scanning global and project-specific directories
  • PowersheetDocumentConfigurationService.java — configuration loading and resolution service
  • PowersheetConfigProperties.java — project-specific runtime properties
  • hivemodule.xml — administration page registration at project, project group, and repository scopes
  • Powersheet.tsx