The Central Configuration File
Every RISKSHEET document is governed by a single file:risksheet.json. This file is stored as an attachment on the Polarion LiveDoc document itself, making each document self-contained and portable. When you open a RISKSHEET document, the server reads this attachment, validates it, applies defaults, and delivers the resolved configuration to the browser.
Think of risksheet.json as a blueprint for a spreadsheet. It doesn’t contain data — it defines the structure that data fills: which columns exist, how they behave, what formulas compute, and how cells are styled.
What Configuration Controls
Therisksheet.json file organizes configuration into distinct functional domains:
| Domain | Key Properties | Purpose |
|---|---|---|
| Grid structure | columns, levels, headers | Which columns appear, hierarchical grouping, layout dimensions |
| Data behavior | dataTypes, sortBy | Risk and task work item types, link roles, default sort order |
| Calculations | formulas | Named JavaScript expressions for calculated columns |
| Visual presentation | styles, cellDecorators | Conditional formatting rules that change cell appearance based on values |
| Dropdown values | enums, ratings, relations | Enumeration options for dropdowns, risk rating scales, dependent enum cascades |
| Perspectives | views | Saved column visibility presets for switching between analysis views |
| Global settings | global | Culture/locale, help URL, refresh behavior, menu organization |
| Workflow | reviews | Review manager integration for approval processes |
How the Server Resolves Configuration
When you open a document, the server doesn’t simply passrisksheet.json to the browser unchanged. It performs several resolution steps that add intelligence to the configuration:
Type inference from Polarion fields. If a column definition specifies a bindings reference to a Polarion field but omits the type, the server automatically detects the correct type from the field definition. An enum field becomes an enum column; a date field becomes a date column. This means most columns need only a bindings value and a header — the server infers the rest.
Automatic read-only enforcement. Certain columns are forced read-only regardless of what the configuration says. Columns with a formula property, columns with serverRender scripts, and system fields like author, creation date, and resolution are all locked automatically. This prevents accidental edits to computed or system-managed values.
Column ID generation. If a column definition omits the id property, the server generates one from the header or bindings value. While convenient for simple cases, explicitly setting id is recommended when columns are referenced by formulas or cell decorators.
Default values. Properties like filterable (defaults to true), canCreate on link columns (defaults to true), and level showInMenu (defaults to true) are filled in when not explicitly set.
Two Layers of Settings
RISKSHEET separates configuration into two distinct layers that serve different purposes: Document-level configuration (risksheet.json) controls everything about the grid: columns, formulas, styling, views, and data types. Each document carries its own copy, making it fully self-contained.
Project-level properties control infrastructure that applies to all RISKSHEET documents within a project: template paths (where new documents can be created), the tool name displayed in the UI, suggester behavior for linking work items, and whether auto-suspect marking is active. These settings are configured through Polarion’s project administration, not through risksheet.json.
This separation matters because changing a project-level property (like the tool name from “Risksheet” to “FMEA Tool”) affects every document in the project instantly, while changing risksheet.json in one document has no effect on any other document.
Template Inheritance
When a new RISKSHEET document is created, itsrisksheet.json is copied from a template document. This is a one-time copy — after creation, the document’s configuration is independent. Changes to the template do not propagate to existing documents.
This design is intentional. In regulated industries, a document that passed review under one configuration must not silently change behavior because someone updated a template. Each document’s configuration is frozen at creation and only changes through deliberate edits.
To apply template changes to an existing document, use the configuration editor’s option to update from template. This is an explicit action that replaces the document’s configuration with a fresh copy from the template — see Override Template Configuration for the practical approach.
Common Misconceptions
“Editing the template updates all documents.” No. Template inheritance is copy-on-create. Each document is independent after creation. To standardize configuration across documents, you must update each one individually or use the update-from-template action. “I need to specify every property.” The server applies sensible defaults and infers types from Polarion field definitions. A minimal column definition needs onlyheader and bindings. Start minimal and add properties only when you need to override default behavior.
“Read-only means the column is broken.” Columns with formulas, server-rendered content, and system fields are automatically forced read-only. This is expected behavior, not a configuration error. Check whether the column has a formula or serverRender property before investigating further.
Next Steps
- Configuration Hierarchy — How template and document configurations interact in detail
- Risksheet.json Format — Complete property reference for the configuration file
- Use the Configuration Editor — Practical guide to editing configuration through the UI
- Set Up Global Templates — How to create and manage reusable templates across projects
- Default Configuration Values — Full list of server-applied defaults
Sources
Sources
KB ArticlesSource Code
RisksheetViewServlet.javaRisksheetProjectProperties.javaAppConfig.tsAppConfigParser.tsPolarionAppConfigManager.java