Skip to main content

​
Why Configuration Hierarchy Matters

Think of RISKSHEET configuration like a company’s dress code policy: there’s a company-wide default, department-specific variations, and individual employees might have special accommodations. Similarly, RISKSHEET allows:
  • Global defaults that apply to all projects
  • Project-level overrides that customize behavior for specific projects
  • Template-based configurations that define reusable document structures
  • Document-specific overrides that allow one-off customizations without affecting the template
This layered approach prevents configuration sprawl while giving administrators precise control over where changes apply.

​
The Three Configuration Layers

diagram

​
Layer 1: Project/Global Configuration Properties

These settings are defined in Administration > Configuration Properties and control system-wide behavior that affects how RISKSHEET interacts with Polarion. Examples include:
  • nextedy.risksheet.branchingSupport - Enables support for branched documents
  • nextedy.risksheet.checkInstanceFieldPermissions - Controls field-level permission checks
  • nextedy.risksheet.upstreamSubColumnsReadonly - Determines if upstream columns are editable
These properties apply across all RISKSHEET documents in the project unless overridden by document or template configuration.
Use global properties for settings that should be consistent across all risk documents in your organization: permission models, branching behavior, suggester algorithms, and integration flags.

​
Layer 2: Template-Level Configuration

The template configuration is stored as a risksheet.json file attached to a template document. This is the primary location for defining:
  • Column structure (headers, bindings, types)
  • Formulas and calculated fields
  • Cell styling and conditional formatting
  • Data types (risk, task, review)
  • Hierarchical levels
Documents created from a template inherit this configuration automatically. When you update the template’s risksheet.json, all documents pointing to that template receive the updates—unless they have document-specific overrides.
A common misconception: users expect that attaching risksheet.json to a template document automatically makes it a template. In reality, individual documents must reference the template via their templateDoc custom field to inherit the configuration.

​
Layer 3: Document-Specific Configuration

When you attach risksheet.json directly to a RISKSHEET document (not the template), that configuration takes precedence over the template. This creates a detached configuration that:
  • No longer receives updates from the template
  • Allows document-specific customization
  • Requires manual synchronization if template changes are needed
Use this layer sparingly—only when a specific document requires unique configuration that shouldn’t affect other documents.

​
Configuration Resolution Process

When RISKSHEET loads a document, it searches for configuration in this order:
RISKSHEET ships with a built-in default configuration that provides basic FMEA columns and structure. This serves as a fallback when no custom configuration is found.

​
Template Override: Switching Between Layers

The Menu > Configuration > Override Template action is the key mechanism for moving between template-based and document-specific configuration.

​
What “Override Template” Does

  • Copies the current template’s risksheet.json to the document as an attachment
  • Severs the link to the template—future template changes will not propagate to this document
  • Allows editing this document’s configuration independently

​
Common Use Cases

ScenarioRecommended Approach
Need consistent configuration across 50+ risk documentsUse template-based configuration (Layer 2)
One document needs an extra column not in the templateUse Override Template, then edit document config (Layer 3)
Testing a new formula before rolling it out organization-wideCreate a test document, Override Template, experiment in Layer 3
Need to exclude one document from global template updatesUse Override Template to detach it
Once you override the template, there is no automatic “reattach” mechanism. To revert to template-based configuration, you must manually delete the document-attached risksheet.json and ensure the templateDoc field points to the correct template.

​
Property-Level Precedence

Within the risksheet.json file itself, some properties can exist at multiple levels:
  • global.* properties (culture, help, refreshOnSave) apply document-wide
  • columns[].readOnly can be overridden by permission checks (Layer 1)
  • dataTypes.*.type can use Velocity expressions evaluated against global properties
When the same property appears in multiple layers, the most specific layer wins: 
Document-specific property > Template property > Global property > Built-in default

​
Multi-Project Scenarios

In organizations with multiple Polarion projects, configuration hierarchy becomes more complex:
  • Project-level properties are scoped to a single project
  • Global properties (defined at the repository level) apply to all projects
  • Templates can be shared across projects via cross-project document references
For multi-project environments, consider creating a dedicated “Configuration Project” that holds shared templates. Other projects reference these templates via cross-project links, ensuring consistent configuration while allowing project-specific overrides.

​
Configuration Editor and Hierarchy

Starting with version 25.5.0, the configuration editor (Menu > Configuration > Edit Risksheet Configuration) provides:
  • Visual indication of whether you’re editing template or document-specific configuration
  • Template override wizard that walks through the detachment process
  • Configuration history showing which layer each property comes from
  • Download support for backing up configurations before making changes
The editor automatically detects which layer you’re modifying and highlights inherited vs. overridden properties.

​
Common Pitfalls

​
Misconception 1: “Attaching risksheet.json makes it a template”

Reality: Attaching risksheet.json to a document makes it a configuration source, but other documents only inherit from it if their templateDoc field points to that document.

​
Misconception 2: “I can revert document-specific config to template-based”

Reality: Override Template is a one-way operation. To revert, you must manually delete the document-attached file and clear cached configuration.

​
Misconception 3: “Global properties always override document config”

Reality: Global properties (Layer 1) control system behavior, while document config (Layer 2/3) controls structure. They operate in different domains—global properties affect how RISKSHEET interprets document config, not what that config contains.
KB ArticlesSupport TicketsSource Code
  • RisksheetViewServlet.java
  • RisksheetProjectProperties.java
  • AppConfigParser.ts
  • AppConfig.ts
  • PolarionAppConfigManager.java