Skip to main content

​
The Configuration File

At the heart of every Risksheet document is a single JSON file named risksheet.json. This file is stored as an attachment to the Polarion LiveDoc document and contains the complete definition of the grid layout, data behavior, and visual presentation. Think of risksheet.json as a blueprint for a spreadsheet. Just as an architect’s blueprint specifies room dimensions, materials, and wiring, the configuration file specifies columns, data types, formulas, and styles. The Risksheet engine reads this blueprint each time the document opens and constructs the interactive grid accordingly. The configuration is loaded through the /api/config endpoint, which returns a rich configuration object containing all settings the grid needs: enumeration values, rating scales, link relations, custom formulas, cell styling rules, and query factories. The global.culture setting within this object also controls localization, affecting date and number formatting.

​
Configuration Sections

The risksheet.json file is organized into distinct sections, each governing a specific aspect of the grid:
SectionPurposeDefault
columnsGrid column definitions (bindings, types, headers, rendering)[]
dataTypesRisk and task work item type configuration{}
levelsHierarchical level definitions with control columns[]
formulasNamed JavaScript formula functions for calculated columns{}
stylesCSS class definitions for conditional formatting{}
cellDecoratorsColumn-to-style mapping logic for dynamic cell formatting{}
enumsEnumeration options for dropdown columns{}
ratingsRating scale definitions for risk parameters{}
relationsDependent enum relationships for cascading selections[]
viewsSaved column visibility presets[]
reviewsReview workflow configuration{}
headersRow and column header dimensions and renderers{}
globalCulture, help URL, refresh behavior, menu organization{}
sortByDefault sort order by column ID sequence[]

​
How Configuration Is Loaded

When you open a Risksheet document, the configuration undergoes a loading and enrichment process before the grid renders: diagram The configuration manager performs several automatic enrichments:
  • Column type inference: If a column does not specify a type, it is automatically detected from the Polarion field binding. For example, a column bound to a date field becomes a date column.
  • Column ID generation: If no id is provided, one is auto-generated from the header or binding property.
  • Read-only enforcement: Columns with a formula or serverRender property are automatically set to read-only. System fields such as author, resolution, created, updated, and type are also locked.

​
Data Type Configuration

The dataTypes section defines how Risksheet interacts with Polarion work items. Two primary data types exist:
  • dataTypes.risk — Defines the work item type for risk items, the link role for relationships, the removal strategy (default: delete), and rejection workflow settings (rejectedAction, rejectedStatus, rejectedResolution).
  • dataTypes.task — Defines the work item type for downstream mitigation tasks, the link role, and menu visibility (showInMenu defaults to true).
Both support dynamic value evaluation, allowing expressions that resolve at runtime based on the project context.

​
Behavioral Properties

Several top-level properties control grid-wide behavior:
  • readonly (default: false) — Makes the entire grid read-only. Also automatically enabled when viewing a historical revision.
  • downstreamReadonly (default: false) — Prevents edits to linked items from other documents.
  • reviewer (default: false) — Enables reviewer mode, restricting editing and showing review-specific controls.
  • canAdmin (default: false) — Indicates whether the current user has administrative privileges to edit configuration.
  • source — Tracks which configuration file (document or template) was used to load this configuration.
  • templateName — Records the template name when configuration inherits from a global template.
The source and templateName properties let you trace where your configuration originated. This is particularly useful when troubleshooting unexpected behavior — you can verify whether the document is using its own configuration or inheriting from a template.

​
Configuration Updates

Configuration changes can be applied through the configuration editor interface, accessible at the /risksheet/configuration/ URL path. The editor supports updating the configuration with a scope parameter that indicates whether changes are being copied from a template. All configuration updates execute within a write transaction, ensuring that partial updates cannot corrupt the document state. After a successful update, the system redirects back to the document view with the new configuration active.
Modifying risksheet.json requires administrative privileges for the project. The canAdmin flag determines whether the current user sees configuration editing options in the interface.
For details on how configurations inherit across templates and documents, see Configuration Hierarchy. To understand the role of columns and data types in defining the grid structure, see Data Model and Work Items. For practical guidance on editing configuration, visit the How-To Guides.
KB ArticlesSource Code
  • RisksheetViewServlet.java
  • RisksheetProjectProperties.java
  • AppConfig.ts
  • AppConfigParser.ts
  • PolarionAppConfigManager.java