This page explains the major components of Risksheet, how they communicate, and why the architecture is designed the way it is.
High-Level Architecture
Risksheet operates as a bridge between two worlds: the structured data management capabilities of Siemens Polarion ALM and the interactive grid experience that safety engineers expect from spreadsheet-based risk analysis tools. The architecture achieves this by deploying a server-side plugin within Polarion and a client-side grid that renders in the browser.
The Server-Side Plugin
The Risksheet server plugin runs inside the Polarion application server as a standard Polarion extension. It does not require a separate server or database — it operates entirely within the Polarion process space.
Configuration Manager
The configuration manager is responsible for loading, validating, and processing risksheet.json configuration files. When a Risksheet page loads, the configuration manager:
- Locates the
risksheet.json attachment on the current LiveDoc document.
- If not found, falls back to the template-based configuration path.
- Parses the JSON and validates required properties.
- Applies default values for missing properties (e.g.,
columns[].level defaults to 1, columns[].filterable defaults to true).
- Infers column types from Polarion field definitions when
type is not explicitly set.
- Enforces constraints (e.g., formula columns become read-only, server-rendered columns become text type and read-only).
The configuration manager also supports dynamic expression evaluation. Properties like dataTypes.risk.type and dataTypes.risk.role can reference Polarion project properties, allowing configurations to be portable across projects without hardcoding project-specific values.
The configuration manager only reads and processes the configuration. It never modifies work item data. Changing risksheet.json changes how data is displayed and interacted with, not the data itself.
Data Service
The data service bridges the gap between the client grid and Polarion’s work item repository. It handles:
- Data loading. Queries Polarion for work items matching the configured data types, document scope, and optional custom queries. Returns work item field values in a format the client grid can consume.
- Data saving. Receives batch updates from the client containing modified field values. Translates grid values back to Polarion field types, validates against permissions and workflow rules, and persists changes within a transaction.
- Type conversion. Converts between Risksheet column types (text, int, float, date, enum, etc.) and Polarion’s internal storage formats. This bidirectional conversion allows the grid to display any Polarion field as different column types.
The type conversion system is a critical architectural component. It supports the following conversions:
| Risksheet Type | Polarion Storage | Notes |
|---|
text | Text, String | Rich text stripped to plain text for display |
enum | EnumOption, String, Integer | Uses enum IDs (not display names) except for status field |
multiEnum | List of EnumOption, comma-separated String | Blank options filtered automatically |
int / rating | Integer | Interchangeable internally |
float | Float, Double | Standard floating-point precision |
currency | BigDecimal wrapped in Currency type | Maintains financial precision |
date | DateOnly, Date, Calendar, ISO String | Format: yyyy-MM-dd |
datetime | Date, Calendar, ISO String | Full timestamp |
time | TimeOnly from Date/Calendar | Format: hh:mm:ss |
duration | DurationTime, Integer, Float | Parsed via DurationTime.fromString() |
boolean | Boolean, String “true”/“false” | Automatic string-to-boolean conversion |
user | User ID string or Assignees collection | Single-user assignment supported |
Query Builder
The query builder constructs Polarion Lucene queries based on the dataTypes configuration. It determines which work items to load by combining the configured work item type, document scope, and optional query parameters. The dataTypes.risk.type property is required — without it, the query builder raises the error: No type attribute is defined for dataType.
Workflow Actions
The workflow actions component handles workflow transitions triggered from the grid, such as rejecting a risk item. It uses the rejectedAction, rejectedStatus, and rejectedResolution properties from the dataTypes configuration to execute the appropriate Polarion workflow action on the work item.
OData Provider
Risksheet exposes grid data through an OData API, enabling external systems to consume risk analysis data programmatically. The OData provider maps Risksheet column types to OData EDM primitive types:
| Risksheet Type | OData EDM Type |
|---|
text | Edm.String |
int | Edm.Int64 |
float | Edm.Double |
rating | Edm.Int32 |
currency | Edm.Decimal |
boolean | Edm.Boolean |
date | Edm.Date |
datetime | Edm.DateTimeOffset |
time | Edm.DateTimeOffset |
duration | Edm.String |
multiEnum | Edm.String |
| Unrecognized | Edm.String (fallback) |
The Client-Side Grid
The client-side application runs in the user’s browser and provides the interactive grid experience. It loads configuration and data from the server plugin, renders the grid, and handles user interactions.
Configuration Parser
The client-side configuration parser transforms the raw configuration received from the server into a strongly-typed application model. It processes:
- Column definitions into renderable grid column objects
- Enum and rating registries for dropdown editors
- Relation definitions for dependent enum behavior
- Document metadata (URL, revision, project context)
- User permissions (admin, reviewer flags)
A key behavior of the configuration parser is automatic read-only enforcement for historical revisions. When the revision property is non-empty (indicating you are viewing a baseline or past version), the entire grid is forced into read-only mode regardless of the readonly configuration property.
The formula engine evaluates JavaScript functions defined in the formulas section of risksheet.json. Formulas run entirely in the browser, which means:
- Instant recalculation. When you change a cell value, dependent formula columns recalculate immediately without a server round-trip.
- Client-side only. Formula results are not stored in Polarion. They are computed on-the-fly from the current field values each time the page loads.
- Standard JavaScript. Formulas are standard JavaScript functions that receive an
info object containing the current row’s data.
Example: The RPN formula multiplies three risk parameters:
function(info) {
var value = info.item['occ'] * info.item['det'] * info.item['sev'];
return value ? value : null;
}
Cell Decorators
Cell decorators are JavaScript functions that apply conditional CSS classes to cells based on their values. They run after each cell render, enabling dynamic visual feedback. Decorators reference CSS classes defined in the styles section.
The decorator-to-style chain works as follows:
Session Manager
The session manager tracks the state of the current editing session:
- Which cells have been modified (dirty tracking)
- Navigation warnings when leaving with unsaved changes
- Save operation coordination (batch collection, server submission, response processing)
- Active view state (which saved view is selected)
See Working Sessions for a detailed explanation of session lifecycle.
Data Flow
Understanding how data flows through the architecture clarifies the relationship between configuration, rendering, and persistence.
Load Flow
1. Browser navigates to LiveDoc with RISKSHEET widget
2. Server loads risksheet.json (document attachment or template)
3. Server validates config, applies defaults, infers types
4. Server queries Polarion for work items matching dataTypes config
5. Server converts work item fields to grid-compatible format
6. Client receives config + data payload
7. Client parser builds typed application model
8. Grid renders columns from config, populates rows from data
9. Formula engine evaluates all formula columns
10. Cell decorators apply conditional styling
11. Grid is interactive and ready for editing
Save Flow
1. User clicks Save (or presses keyboard shortcut)
2. Session manager collects all dirty (modified) items
3. Modified field values sent as batch to server data service
4. Server validates permissions and workflow constraints
5. Server converts grid values back to Polarion field types
6. Server persists changes in a Polarion transaction
7. If transaction succeeds: updated values returned to client
8. Client refreshes grid with confirmed values, clears dirty flags
9. Formulas recalculate, decorators reapply
10. If transaction fails: rollback, error reported to client
Design Principles
Several architectural decisions shape how Risksheet behaves:
No separate data store. Risksheet does not maintain its own database. All data lives in standard Polarion work items. This ensures a single source of truth and preserves Polarion’s audit trail, versioning, and permission system.
Configuration over code. The grid’s behavior is entirely driven by risksheet.json. Administrators do not write Java code or deploy custom plugins to customize the grid layout, formulas, or styling. This makes configuration portable and version-controllable.
Client-side interactivity, server-side persistence. The split between client-side formula evaluation and server-side data persistence gives users instant feedback during editing while maintaining data integrity through transactional saves.
Graceful degradation. Unrecognized column types default to text/string. Missing configuration properties receive documented defaults. This design minimizes the impact of configuration errors and makes it easier to incrementally customize a Risksheet setup.
Related Pages
