Skip to main content

​
The Three-Layer Architecture

RISKSHEET operates as a specialized view layer on top of Polarion’s work item management system. Think of it as a rendering engine that transforms standard Polarion data structures into an interactive spreadsheet interface optimized for risk analysis. diagram

​
Layer 1: Data Storage (Polarion Work Items)

At the foundation, RISKSHEET stores all risk data as standard Polarion work items within a LiveDoc document. This layer ensures:
  • Persistence: All data survives RISKSHEET updates or even complete uninstallation
  • API access: External tools can query risk data via Polarion’s REST or SOAP APIs
  • Traceability: Standard Polarion link roles connect risks to requirements, tests, and mitigations
  • Version control: Polarion’s baseline and branching features provide audit trails
A typical FMEA implementation might define:
  • Work item type: risk (with custom fields: failureMode, cause, severity, occurrence, detection)
  • Work item type: task (standard Polarion task with assignee, status, dueDate)
  • Link role: mitigates (connects tasks to risks)
See Data Model and Work Items for detailed field mapping.

​
Layer 2: Configuration (risksheet.json)

The risksheet.json file acts as a blueprint that transforms raw Polarion data into a structured risk analysis interface. This configuration file defines:
Configuration SectionPurposeKey Properties
ColumnsWhich work item fields appear as spreadsheet columnsid, header, bindings, width, level
LevelsHow rows merge to create hierarchical groupingsname, controlColumn, zoomColumn
Data TypesWhich Polarion types represent risks vs. mitigation taskstype, role, name
FormulasJavaScript functions calculating derived valuesNamed functions referencing info.item['field']
Cell DecoratorsConditional styling based on cell valuesCSS class toggling functions
StylesVisual customization rulesCSS rule definitions
ReviewsReview workflow configurationreviewManager, typeProperties
See Configuration System for detailed explanations and risksheet.json Format for the complete schema.

​
Layer 3: Presentation (Browser UI)

The client-side application renders the configured structure as an interactive spreadsheet:
  • Grid rendering: Displays work items as rows with merged cells for hierarchical levels
  • Formula engine: Evaluates JavaScript formulas in real-time as users edit cells
  • Event handlers: Capture user actions (cell edits, row additions, saves) and translate them to Polarion API calls
  • Styling engine: Applies conditional formatting based on cell values and decorators

​
Document-to-Risksheet Relationship

Understanding the 1:1 document-to-RISKSHEET relationship is critical for architecture design: diagram

​
Why 1:1 Architecture?

This design choice provides several benefits:
  1. Clear ownership: Each document represents a single risk analysis scope (product, component, release)
  2. Predictable behavior: All work items in the document appear in RISKSHEET (subject to query filters)
  3. Simplified permissions: Polarion document permissions automatically control RISKSHEET access
  4. Configuration isolation: Each document can have unique column layouts without affecting others
RISKSHEET cannot display work items from multiple Polarion documents in a single view. If you need to analyze risks across multiple documents, you must either:
  • Create separate RISKSHEETs for each document
  • Consolidate work items into a single master document
  • Use Polarion’s document reuse features to pull content into a central document
Attempting to configure cross-document queries will fail. RISKSHEET is designed as a visual representation of a single document’s contents, not as an aggregation layer.
See Work with Branched Documents for multi-release scenarios.

​
Configuration Hierarchy and Template Inheritance

RISKSHEET’s configuration system supports a template-to-instance hierarchy that balances standardization with flexibility: diagram

​
Configuration Search Order

When RISKSHEET loads, it searches for risksheet.json in this order:
  1. Attached to current document: Check if the LiveDoc being viewed has risksheet.json attached
  2. Attached to template document: Check if the document’s templateDoc custom field points to another document with risksheet.json
  3. Built-in default: Fall back to RISKSHEET’s built-in configuration if no custom config exists
This hierarchy enables:
  • Team standardization: All projects start with approved organizational templates
  • Project flexibility: Individual documents can override configurations for unique needs
  • Centralized updates: Template changes propagate to all documents automatically (unless overridden)
See Configuration Hierarchy and Override Template Configuration. RISKSHEET displays two categories of work items in the grid:
  1. Primary items (Levels 1-N): Work items contained in the document (typically risk items)
  2. Downstream items (Level N+1): Work items linked to primary items (typically mitigation tasks)
diagram

​
Downstream Item Resolution

The dataTypes.task configuration controls how RISKSHEET finds linked items by specifying the Polarion work item type, link role name, display name, and zoom column. See Configure Downstream Tasks for configuration details. When rendering the grid, RISKSHEET:
  1. Loads all work items from the document (primary items)
  2. For each primary item, queries Polarion for linked items matching type and role
  3. Filters results to ensure only items of the specified type appear
  4. Sorts results by work item ID for consistent display
The project parameter in typeProperties only works for direct links. RISKSHEET cannot traverse transitive/multi-hop links across projects.Supported: Risk in Project A → Task in Project B (direct link)Not supported: Risk in Project A → Harm in Project A → Requirement in Project B (transitive link)For complex cross-project traceability, use separate RISKSHEETs per project or consolidate linked items into the primary project.
See Traceability and Linking and Configure Downstream Tasks.

​
Session and State Management

RISKSHEET operates as a stateful client application:

​
Server-Side State

  • Data storage: Polarion database stores all work items and links
  • Configuration: risksheet.json file attached to Polarion documents
  • Permissions: Polarion project and document permissions control access

​
Client-Side State

  • Grid data: Loaded into browser memory on page load
  • User edits: Tracked in client-side change buffer until save
  • Formula results: Calculated in browser, not stored in Polarion
  • Session: Lost on page refresh unless saved

​
Save Operation

When users click Save:
  1. Client collects all modified work items from change buffer
  2. Sends batch update request to Polarion API
  3. Polarion validates permissions and field constraints
  4. Polarion persists changes to database
  5. If global.refreshOnSave: true, RISKSHEET reloads data to reflect server state
RISKSHEET warns users when navigating away with unsaved changes. However, browser crashes or network interruptions will lose unsaved edits. Save frequently when making bulk changes.
See Working Sessions.

​
Revision and Baseline Support

RISKSHEET integrates with Polarion’s version control architecture:

​
Current/Head View

By default, RISKSHEET displays the latest version of all work items. Users can edit, add, and delete items freely (subject to permissions).

​
Historical/Revision View

Users can view specific document revisions or baselines via URL parameters: 
/polarion/risksheet/view?project=MyProject&document=RiskAnalysis&revision=2.5
In revision mode:
  • RISKSHEET loads work item data from the specified revision
  • All editing controls are disabled (read-only mode)
  • Downstream items display their state at the time of the revision
  • Formulas calculate based on historical field values
This enables compliance teams to audit historical risk assessments without risk of accidental modification. See Work with Branched Documents.

​
Topic Visibility and Access Control

RISKSHEET appears in Polarion as a topic in the sidebar navigation. Topic visibility is controlled by Polarion’s view configuration under Administration > Portal > Topics by adding a <topic id="risksheet"/> entry.

​
Multi-View Environments

In organizations using Polarion’s role-based views (e.g., separate views for engineers vs. managers), administrators must ensure the RISKSHEET topic entry exists in all active view configurations. If the topic entry is missing from a view, users assigned to that view cannot access RISKSHEET — even if they have proper document permissions.
If users report “RISKSHEET disappeared after project setup” or “I can’t find RISKSHEET in the sidebar,” check that the <topic id="risksheet"/> entry exists in all active Polarion views.Even if users have proper document permissions, they cannot access RISKSHEET if the topic is filtered from their view.
See Troubleshooting Access Denied Errors.

​
Performance and Scalability Considerations

RISKSHEET’s architecture is optimized for documents containing hundreds of work items:

​
Client-Side Rendering

  • Grid virtualization renders only visible rows, enabling smooth scrolling with 500+ items
  • Formula evaluation is lazy—only visible cells are calculated initially
  • Cell reuse minimizes DOM manipulation during scroll operations

​
Server-Side Optimizations

  • Batch API calls load all document work items in a single request
  • Downstream item queries execute in parallel for all primary items
  • Caching reduces repeated field mapping lookups

​
Known Limitations

  • Documents with >1000 work items may experience slower initial load times
  • Complex formulas with many field references can slow editing responsiveness
  • Large baseline comparisons may timeout if document history is extensive
See Performance Questions and Slow Page Loading.

​
Next Steps

Support Tickets