Skip to main content

​
The Problem Levels Solve

A typical FMEA table is not a flat list. It is a hierarchy: a system function has one or more failure modes, each failure mode has causes and effects, and each cause may have mitigation tasks. In Polarion, these are separate work items connected by links. Without levels, Risksheet would display every work item as an independent row with no structural relationship, making it impossible to read as a coherent risk analysis. Levels solve this by defining a layered structure where each tier of the hierarchy is a separate “level” in the grid. Work items at Level 1 (the root tier) occupy the top of the hierarchy. Work items at Level 2 are children nested beneath their Level 1 parent. Task-level items (mitigation measures, verification activities) appear as the innermost tier. The grid merges cells vertically so that a single Level 1 item spans all of its Level 2 children, producing the familiar FMEA spreadsheet layout. diagram

​
How Levels Are Defined

Levels are configured in the levels array within risksheet.json. Each entry in the array represents one tier of the hierarchy: 
{
  "levels": [
    {
      "controlColumn": "systemItemId",
      "showInMenu": true
    },
    {
      "controlColumn": "riskId",
      "showInMenu": true
    }
  ]
}
The position in the array determines the level number: the first entry is Level 1, the second is Level 2, and so on. Each level has a controlColumn property (default: systemItemId) that specifies which column acts as the identity and navigation anchor for items at that level. The showInMenu property (default: true) controls whether the level appears in the context menu for creating new items. Every column in the columns array has a level property (default: 1) that assigns it to a specific tier. Columns at Level 1 display data from Level 1 work items; columns at Level 2 display data from Level 2 work items. Task-level columns do not have a level number and are associated with downstream linked items defined in dataTypes.task.

​
What Determines Visibility

Not every work item in the Polarion document appears in the Risksheet grid. Visibility is controlled by a combination of type filtering, status filtering, permission checks, and level membership.

​
Type Filtering

The dataTypes configuration defines which work item types are allowed at each tier:
  • dataTypes.risk.type — work item types displayed as risk items (the primary grid rows). Multiple types can be specified as comma-separated values.
  • dataTypes.task.type — work item types displayed as task/mitigation items (the downstream linked rows). Multiple types can be specified as comma-separated values.
Work items whose type does not match either risk.type or task.type are excluded from the grid entirely. This is the most fundamental visibility filter.

​
Rejected Status Filtering

Work items with a status matching the configured rejectedStatus are automatically hidden from the grid. This enables a soft-delete pattern where items are removed from view by changing their workflow status rather than being permanently deleted:
  • dataTypes.risk.rejectedStatus (default: rejected) — risk items in this status are hidden.
  • The system applies separate filtering rules for risk items and task items.
Rather than permanently deleting risk items, configure rejectedStatus to hide them from the grid. The items remain in Polarion for audit and traceability purposes but do not clutter the active risk analysis view.

​
Permission-Based Filtering

Risksheet respects Polarion’s security model. Work items that the current user lacks read permission for are automatically excluded from results. This filtering is transparent — the user simply does not see items they cannot access. This ensures compliance with project access controls, which is particularly important in regulated environments where role-based access to risk data may be required.

​
Unresolvable Item Filtering

Work items that are corrupted, deleted at the repository level, or otherwise unresolvable are automatically excluded to prevent grid errors. This is a defensive mechanism that handles data quality issues silently. diagram

​
Upstream and Downstream Relationships

Levels are fundamentally about relationships between work items. The terminology used in Risksheet maps to the direction of traceability links:
  • Upstream items are work items that the current row links TO (e.g., a failure mode links to a system requirement). These appear in upstream traceability columns, typically configured as itemLink or multiItemLink column types.
  • Downstream items are work items that link FROM the current row (e.g., mitigation tasks linked to a failure mode via the task role). These appear in task-level columns at the bottom of the hierarchy.
A common source of confusion is the difference between items directly linked to a risk item and items linked through an intermediary. For example, if a failure mode (Level 2) links to a requirement (Level 1), and that requirement links to a system function, the system function is an indirect link — it is not directly connected to the failure mode.

​
Displaying Indirectly Linked Items

Standard Risksheet columns can only display directly linked work items. To show items connected through upstream relationships (items linked to linked items), you have two options:
  1. Server render columns — Use Velocity scripts to traverse indirect links and render the results as read-only HTML. See Server Render Columns for the Velocity patterns.
  2. upstreamChains — A configuration property (format: fromType-linkRole-toType) that automatically builds transitive link chains. This creates actual links in Polarion, making the indirect relationships editable. Note that upstreamChains only creates links; it never deletes them.
Users frequently expect that configuring a Level 2 column will automatically show items linked through Level 1 items. This is not how levels work. Each level displays items that are directly linked to the current row’s work item. Indirect links require explicit configuration via server render or upstreamChains.

​
Cross-Project Item Visibility

Risksheet supports displaying work items from other Polarion projects. This is configured via the project parameter in the typeProperties section of a column or data type definition. When a project ID is specified, Risksheet loads items from that project instead of (or in addition to) the current project. Cross-project visibility has limitations:
  • It works for directly linked items only. Indirect links through intermediary work items in other projects require additional configuration (typically server render columns with cross-project Velocity queries).
  • The user must have read permissions in the target project. Items the user cannot access are filtered out.
  • Workflow status dropdowns correctly load actions for the source project using the project!workItemId format, enabling status editing for cross-project items.

​
The Read-Only Boundary

Not all visible items are editable. Several factors can make work items or individual columns read-only:
ConditionEffect
readonly: true in root configurationEntire grid is read-only
downstreamReadonly: trueDownstream linked items (tasks) from other documents cannot be edited
reviewer: trueReviewer mode restricts editing and shows review-specific controls
Historical revision viewingViewing a non-current revision forces read-only mode automatically
Column has serverRenderColumn is always read-only
Column has formulaColumn is read-only by default
System fields (id, status, type, project, outlineNumber)Always read-only regardless of configuration
Permission restrictionsColumns where the user lacks write permission are read-only
Newly created work items (identified by IDs starting with *) have limited functionality until saved. Status dropdowns are disabled for new items because workflow actions only apply to items that exist in Polarion. You must save the item before workflow transitions become available.

​
Cell Merging and Visual Structure

When multiple Level 2 items share the same Level 1 parent, the Level 1 columns merge vertically to span all child rows. This produces the characteristic FMEA layout where a single failure mode description spans multiple cause/effect pairs. The controlColumn property on each level determines which column drives the merge grouping. Rows with the same value in the control column at a given level are merged. The default control column is systemItemId, which groups by the Polarion work item ID. The visual result is a grid where:
  • Level 1 columns span multiple rows, showing the parent item data once
  • Level 2 columns show one row per child item
  • Task-level columns show one row per downstream linked item within each Level 2 group

​
Context Menu and Item Creation

The context menu (right-click on a grid cell) provides options for creating new items at different levels. The menu dynamically generates options from the levels array where showInMenu is true. Only levels that are configured for menu visibility appear as creation options. The context menu also provides:
  • Open Row Item — navigates to the current row’s work item in Polarion’s item editor
  • Open Linked Item — opens a linked work item from an item link column
  • Open Task Item — opens a task work item; the menu label uses the task type name from dataTypes.task.name if configured
  • Remove Row Item — removes the selected row (only in editable grids)
  • New Level Items — creates new work items at the selected level (only in editable grids)

​
Practical Mental Model

Think of levels as a telescope with adjustable zoom:
  • Level 1 is the widest view — you see the top-tier items (system functions, hazards, or failure modes depending on your FMEA structure).
  • Level 2 zooms in to the children of each Level 1 item — causes, effects, or sub-failure modes.
  • Task level zooms to the finest detail — mitigation tasks, verification activities, or design changes linked to specific Level 2 items.
Each column in the grid is assigned to exactly one zoom level. When you look at a row, the Level 1 columns show data from the Level 1 parent, the Level 2 columns show data from the Level 2 item, and the task columns show data from the downstream linked task. All three levels coexist in the same visual row, but they represent data from different work items connected by links. The levels configuration in risksheet.json tells Risksheet how many zoom levels exist and which column drives the grouping at each level. The dataTypes configuration tells Risksheet which work item types belong to which tier and what link roles connect them.

​
See Also

KB ArticlesSupport TicketsSource Code
  • RiskSheetContextMenu.ts
  • RisksheetDataStorage.java
  • StatusComboBox.ts
  • ResultFilter.java
  • AppConfig.ts