Configuration Hierarchy - Nextedy Documentation

Nextedy RISKSHEET (Risksheet) solves this with a clear separation between configuration templates and risksheet instances. A single template defines how the analysis looks and behaves; many instances inherit that template and each binds the resulting grid to its own scope — its own system, subsystem, or component. This page explains the mental model behind that separation, where templates live, how instances pick up the right one, and what to expect when configuration changes over time.

The Mental Model: One Template, Many Instances

The clearest analogy is a product specification template. A safety department defines a single FMEA template that prescribes the column layout, severity and occurrence scales, RPN calculation, and styling. Every engineering team then creates their own FMEA document — one for the braking system, one for the steering ECU, one for the diagnostic interface. The document is the unit of work; the template is the unit of governance. In Risksheet terms:

A risksheet instance is a single Polarion LiveDoc with risk items inside it. It is what users open, edit, and review. Each instance is bound to a specific context — a system, subsystem, or component — through the document title, location, and the work items it contains.
A configuration template is a shared definition of how those instances look and behave. It lives as sheet configuration (risksheet.json) on a designated template document. Many instance documents reference the same template and inherit its settings.

The arrows in the diagram are the inheritance relationship: each instance reads its grid structure from the template. The instances themselves are independent — they hold different risk items, link to different requirements, and follow different lifecycles. The template is the contract; the instance is the work.

Without this separation, every new risk document would either be a hand-edited copy of an older one (configuration drift) or every methodology change would require updating dozens of identical files. The template-instance model gives you a single place to evolve the methodology and many places to apply it.

What Lives in the Template vs. the Instance

The line between “template content” and “instance content” is sharp and worth internalising. A common misconception is that everything in the sheet configuration is shared — in reality, only the sheet configuration itself is. The risk data is always per-instance.

Belongs to the template	Belongs to the instance
Column definitions (`columns`, including `bindings` and `type`)	The risk items (work items) themselves
Visual hierarchy (`levels`)	Values entered into cells
Calculated columns (`formulas`)	Links to upstream requirements
Conditional formatting (`cellDecorators` and `styles`)	Links to downstream mitigations and tasks
Work item types in use (`dataTypes`)	Review comments and approval state
Saved views (`views`)	The document title, location, and history
Default sort (`sortBy`), header layout (`headers`), review setup (`reviews`)	Attachments and revisions

The template answers what the grid looks like. The instance answers what we are analysing.

Risksheet does not have its own data store. Every risk item is a standard Polarion work item, subject to Polarion authorization and traceable through Polarion’s audit infrastructure. The configuration controls how that data is displayed and edited — it does not duplicate or cache the data elsewhere.

Template Scoping: Project vs. Global

Templates can be defined at two scopes, and the choice has real consequences for how a programme is governed.

Project-Scoped Templates

A project-scoped template is a LiveDoc inside the same Polarion project as the instance documents. The project’s administrators control it, and only documents within that project can reference it. This is the default scope and the simplest to reason about: one project, one set of templates, one team. Use project scoping when:

The methodology is project-specific (for example, a customer-tailored FMEA for one programme).
The team running the project also owns the methodology.
Cross-project sharing is not required.

The project-level setting that defines where templates live is the Risksheet Template Path (default: Risks/Risk Specification). Administrators can configure multiple comma-separated paths to support several methodologies inside one project — for example, a path for FMEA templates and another for HARA templates.

Global-Scoped Templates

A global-scoped template lives in a dedicated library project — a shared, organization-wide repository (often called GlobalLibrary or similar). Instance documents in any project can reference templates from that library, which makes the library project the single source of truth for company-wide methodology. The reference uses the PROJECTID:TEMPLATE_PATH format, for example GlobalLibrary:Risks/Risk Specification. The colon separates the library project ID from the document path inside that project. Use global scoping when:

A single safety or quality team owns the methodology for many engineering projects.
Compliance with ISO 26262, ISO 14971, or similar standards requires a controlled, central methodology.
You want to audit every change to the FMEA methodology in one place rather than across N project repositories.

A project can mix both scopes. An engineering project might inherit its main methodology from a global library template, while keeping a small project-local template for an experimental analysis type. The two coexist without conflict — each instance picks exactly one template to follow.

Template Linking: How an Instance Finds Its Template

The link between an instance and its template is explicit, not magical. Each instance document carries a Polarion custom field — typically templateDoc — that records which template document it follows. The field is of type enum:@document (an enum bound to Polarion’s built-in document list), which means a user selects an existing template document rather than typing a free-form path. This eliminates broken references and lets Polarion’s referential integrity guard against template documents being moved or deleted without notice. When a user opens a risksheet instance:

Risksheet reads the instance document’s templateDoc field.
It loads the sheet configuration from the referenced template.
The grid renders using the template’s columns, levels, formulas, and styles.
The instance’s own work items populate the rows.

If the instance has no templateDoc reference, Risksheet falls back to the project’s configured template path. If neither is set, the instance must carry its own sheet configuration directly.

Polarion has a generic “Reuse” feature for duplicating documents and their content. It is tempting to use it to “clone” a template into each new instance, but doing so creates an independent copy of the configuration attachment on every instance. The link to the template is lost, and future template changes will not propagate. Instead, create instances normally and set the templateDoc reference — that is the supported inheritance mechanism.

What Happens When the Template Changes

Because the instance reads the template’s configuration on open, changes to the template are picked up the next time each instance is opened. There is no manual push, no rebuild step, and no per-instance migration. Add a new column to the template, fix a formula, adjust a rating threshold — every instance that links to that template will reflect the change on its next session. This is powerful, but it is also why the template-instance separation needs disciplined ownership. Editing a template is a methodology change, not a per-document tweak. In regulated environments, template edits should pass through the same review gate as any other methodology artefact.

An instance can carry its own sheet configuration that overrides the template’s. This is occasionally useful — for example, to disable a column for one specific analysis — but every override is a piece of configuration that escapes central governance. Prefer extending the template (with views, for example) over per-instance overrides.

Saved Views: Lightweight, Per-Document Adaptation

Often, what looks like a need for per-instance configuration is actually a need for a different view of the same configuration. The template’s views section lets you define multiple saved column subsets that users can switch between — without changing the underlying template. For example, a single DFMEA template can offer views like Identify Failure Modes, Initial Risk Ranking, Mitigations, and Final Risk Assessment. Each view shows the columns relevant to one stage of the analysis. The data is identical across views; only the visible columns change. Views support an @all shorthand to include every column, and a -columnId prefix to exclude individual columns from that set:

views:
  - name: Full Analysis
    defaultView: true
    columnIds:
      - "@all"
  - name: Initial Ranking
    columnIds:
      - failureMode
      - severity
      - occurrence
      - detection
      - rpn
  - name: Without Upstream Links
    columnIds:
      - "@all"
      - "-upstreamRequirements"

This pattern often eliminates the need for per-instance overrides entirely. Instead of forking the template, add a view to it. See Configuration Management for practical configuration steps.

Versioning: A Practical Reality, Not Yet a Polished Workflow

A natural question follows from everything above: if instances pick up the template’s current configuration whenever they open, what about audits, baselines, and historical fidelity? Risksheet’s answer here is honest and worth stating plainly: versioning of the configuration template is supported through Polarion’s general document revision and baseline mechanisms, but it is not yet a fully mature, purpose-built feature. What is true today:

Each template document is a standard Polarion LiveDoc, so it has revisions, baselines, and audit history like any other Polarion document.
When a risksheet instance is viewed at a specific revision (for example, through a Polarion baseline), the grid renders in read-only mode and reflects the state of that point in time.
Changes to the template are visible in Polarion’s history view, and Polarion’s role-based permissions can restrict who is allowed to edit it.

What is still evolving:

There is no built-in mechanism to pin an instance to a specific template revision. Instances always follow the template’s current state.
The configuration editor offers history-style features for the sheet configuration, but cross-instance impact analysis (“which instances would be affected by this template change?”) is not yet provided out of the box.
Migration tooling for breaking template changes (renamed columns, restructured levels) is a manual exercise — the template author needs to coordinate with instance owners.

Risksheet’s configuration editor introduced YAML editing support with syntax highlighting and history-style features in v25.5.0. Specific versioning capabilities continue to evolve — confirm exact behaviour against your installed version.

Practical Guidance Today

In practice, teams handle template versioning by combining product features with process discipline:

Practice	Why it works
Treat the template as a controlled methodology artefact, with its own review gate.	Stops accidental edits from rippling across every analysis overnight.
Use Polarion baselines on the template document at release milestones.	Creates a recoverable, audit-visible snapshot of the methodology in use.
Communicate template changes to instance owners before they are applied.	Avoids surprise when a column disappears or a formula’s behaviour shifts.
Use saved views for stage-based or role-based adaptations rather than forking the template.	Keeps the template canonical; reduces the need for per-instance overrides.
For breaking changes, plan a coordinated rollout window across affected instances.	Acknowledges that instances cannot independently pin an older template.
Capture the template’s revision in the instance’s review records.	Documents which methodology revision was in force when an analysis was approved.

This combination is enough for most regulated programmes today, but expect the product to keep adding more first-class versioning support over time.

Common Misconceptions

“Each risksheet document needs its own configuration file.” Only if you choose to override the template. The intended model is that many instances share one template, and most instances carry no configuration of their own — they inherit it through their templateDoc reference. “Copying a template document with Polarion’s Reuse feature is how you create a new instance.” No. Reuse duplicates the configuration attachment, breaking the link to the original template. Create instances through the normal Risksheet document creation flow, then set the templateDoc reference. “Changing the template will retroactively change every historical analysis.” When a user views an instance at a historical revision (a baseline), Polarion renders the document as it was at that point in time, and Risksheet honours that read-only mode. The methodology shown in the historical view is whatever the template was at the time of the snapshot, as far as Polarion’s revision tracking allows. “The template defines the data; the instance defines the look.” It is the opposite. The template defines the look and behaviour; the instance defines the data. Confusing this is the most common cause of unnecessary per-instance configuration overrides.

Where to Go Next

Data Model and Work Items — how risk items and task items are stored as Polarion work items.
Architecture — how Risksheet runs inside Polarion and where each piece of configuration is loaded.
Configuration Management — practical guides for setting up template paths, linking documents, and managing views.
Administration — administrator-facing tasks for project-level Risksheet settings.
Templates Reference — reference detail for template documents and their configuration.

​The Mental Model: One Template, Many Instances

​What Lives in the Template vs. the Instance

​Template Scoping: Project vs. Global

​Project-Scoped Templates

​Global-Scoped Templates

​Template Linking: How an Instance Finds Its Template

​What Happens When the Template Changes

​Saved Views: Lightweight, Per-Document Adaptation

​Versioning: A Practical Reality, Not Yet a Polished Workflow

​Practical Guidance Today

​Common Misconceptions

​Where to Go Next

The Mental Model: One Template, Many Instances

What Lives in the Template vs. the Instance

Template Scoping: Project vs. Global

Project-Scoped Templates

Global-Scoped Templates

Template Linking: How an Instance Finds Its Template

What Happens When the Template Changes

Saved Views: Lightweight, Per-Document Adaptation

Versioning: A Practical Reality, Not Yet a Polished Workflow

Practical Guidance Today

Common Misconceptions

Where to Go Next