Skip to main content
diagram

​
The levels Array

The levels property is a top-level array in risksheet.json. Each element defines one hierarchical level in the grid.
PropertyTypeDefaultDescription
namestringRequiredDisplay name for the level, shown in the menu bar button for creating new items of this type
controlColumnstringsystemItemIdColumn id that controls hierarchy grouping for this level. Cells in this column merge vertically for items sharing the same parent.
zoomColumnstringSee applicationColumn id used for zoom navigation when expanding into this level
showInMenubooleantrueControls whether a “New [name]” button appears in the menu bar for creating items at this level
The controlColumn and zoomColumn values must exactly match the id property defined in the corresponding column configuration. Mismatched IDs cause row duplication and incorrect cell merging. This is one of the most common configuration errors reported in support.

​
Level Indexing

Levels are indexed starting from 0. The index determines the hierarchical depth:
Level IndexTypical UsageColumn level Value
0Primary risk item (Failure Mode, Hazard)1 (default for risk columns)
1Upstream linked item (Requirement, Function)2
2Additional upstream or downstream item3
Task levelDownstream task/mitigation (defined in dataTypes.task)Not set on columns
The levels array index (0-based) and the column level property (1-based) follow different numbering conventions. A column with "level": 2 corresponds to levels[1] in the array. Task-type columns do not use the column level property.

​
name Property

The name property defines the human-readable label for each level. This value appears in two locations:
  1. Menu bar buttons — The ”+” buttons at the top of the grid use the level name (e.g., ”+ Failure Mode”, ”+ System Requirement”)
  2. Context menu — Right-click menu options for creating new items reference the level name
{
  "levels": [
    {
      "name": "Failure Mode"
    },
    {
      "name": "System Requirement"
    }
  ]
}
Use the work item type name that your team recognizes. For FMEA, common names include “Failure Mode”, “Cause”, and “Effect”. For HARA, use “Hazard”, “Hazardous Event”, or “Safety Goal”.

​
controlColumn Property

The controlColumn specifies which column controls the grouping and cell merging behavior for a level. When multiple rows share the same value in the control column, their cells merge vertically to create the hierarchical visual structure.
controlColumn ValueBehavior
systemItemId (default)Groups by the risk item’s Polarion ID. Used for the primary risk level.
Custom column id (e.g., sysReq)Groups by the linked item column. Rows with the same linked item merge.
{
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "systemItemId"
    },
    {
      "name": "System Requirement",
      "controlColumn": "sysReq"
    }
  ]
}
Two different levels must never point to the same controlColumn. Doing so causes description values from previous items to auto-populate into new rows and items to merge incorrectly. Each level must reference a unique column.

​
zoomColumn Property

The zoomColumn specifies which column receives focus when a user expands or navigates into a particular level. This provides a zoom-like navigation experience where expanding a level scrolls to and highlights the specified column. 
{
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "systemItemId",
      "zoomColumn": "title"
    }
  ]
}
The exact zoom behavior and visual effect when navigating between levels may vary depending on the grid width and visible columns. Test zoom navigation with your specific column layout.

​
showInMenu Property

Controls whether the level appears as a creation button in the menu bar and context menu.
ValueBehavior
true (default)A ”+ [name]” button appears in the menu bar. A “New [name]” option appears in the right-click context menu.
falseThe level is hidden from creation menus. Items at this level can only be created through other means (e.g., linking existing items).
{
  "levels": [
    {
      "name": "Failure Mode",
      "showInMenu": true
    },
    {
      "name": "System Requirement",
      "showInMenu": false
    }
  ]
}
Use showInMenu: false when a level represents items that should only be linked from existing work items, not created directly from the Risksheet.

​
Interaction with dataTypes

The levels array works together with the dataTypes configuration to define the complete hierarchy. While levels controls the visual grouping and menu structure, dataTypes defines the work item types and link roles. diagram
Configuration AreaControls
levels[].nameButton label in the menu bar
levels[].controlColumnWhich column drives cell merging for the level
dataTypes.risk.typePolarion work item type created for risk items
dataTypes.risk.roleLink role used when connecting risk items
dataTypes.task.typePolarion work item type created for downstream tasks
dataTypes.task.roleLink role used when connecting task items
dataTypes.task.showInMenuWhether task creation appears in the menu (default true)

​
Interaction with sortBy

The sortBy property works with levels to determine the display order of items. Column IDs referenced in sortBy must match the column id values used in the configuration, just as with controlColumn. 
{
  "sortBy": ["sysReq", "systemItemId"],
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "systemItemId"
    },
    {
      "name": "System Requirement",
      "controlColumn": "sysReq"
    }
  ]
}
Column IDs used in sortBy must exactly match the id property defined in column configurations. The same requirement applies to controlColumn values in levels. A mismatch between any of these IDs causes row duplication and incorrect merging.

​
Interaction with Column level Property

Each column definition includes a level property (default 1) that determines at which hierarchical depth the column appears. This links columns to specific entries in the levels array.
Column levelLevels Array IndexTypical Content
1levels[0]Risk item fields (title, description, severity, occurrence)
2levels[1]Upstream linked item fields (requirement title, system element)
3levels[2]Additional hierarchy fields
Not set (task columns)Defined by dataTypes.taskDownstream task fields (mitigation action, assignee)
{
  "columns": [
    {
      "id": "title",
      "header": "Failure Mode",
      "binding": "title",
      "level": 1
    },
    {
      "id": "sysReq",
      "header": "System Requirement",
      "binding": "linkedItem.title",
      "type": "itemLink",
      "level": 2
    }
  ]
}

​
Complete Example

The following risksheet.json excerpt demonstrates a two-level FMEA configuration with a risk item level and an upstream system requirement level, plus downstream mitigation tasks. 
{
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "systemItemId",
      "zoomColumn": "title",
      "showInMenu": true
    },
    {
      "name": "System Requirement",
      "controlColumn": "sysReq",
      "zoomColumn": "sysReq",
      "showInMenu": true
    }
  ],
  "dataTypes": {
    "risk": {
      "type": "failureMode",
      "role": "relates_to"
    },
    "task": {
      "type": "task",
      "role": "relates_to",
      "showInMenu": true
    }
  },
  "sortBy": ["sysReq", "systemItemId"],
  "columns": [
    {
      "id": "systemItemId",
      "header": "ID",
      "binding": "id",
      "level": 1,
      "readOnly": true
    },
    {
      "id": "title",
      "header": "Failure Mode",
      "binding": "title",
      "level": 1
    },
    {
      "id": "sev",
      "header": "Severity",
      "binding": "severity",
      "type": "enum",
      "level": 1
    },
    {
      "id": "occ",
      "header": "Occurrence",
      "binding": "occurrence",
      "type": "enum",
      "level": 1
    },
    {
      "id": "det",
      "header": "Detection",
      "binding": "detection",
      "type": "enum",
      "level": 1
    },
    {
      "id": "rpn",
      "header": "RPN",
      "formula": "commonRpn",
      "level": 1
    },
    {
      "id": "sysReq",
      "header": "System Requirement",
      "binding": "linkedItem.title",
      "type": "itemLink",
      "level": 2
    },
    {
      "id": "taskTitle",
      "header": "Mitigation Task",
      "binding": "task.title",
      "type": "taskLink"
    }
  ],
  "formulas": {
    "commonRpn": "function(info){ var value = info.item['occ']*info.item['det']*info.item['sev']; return value?value:null;}"
  }
}
This configuration produces a grid where:
  • Level 0 rows display Failure Mode fields (title, severity, occurrence, detection, RPN). Cells merge vertically when multiple causes share the same Failure Mode ID.
  • Level 1 rows display linked System Requirements. The sysReq column controls merging so multiple Failure Modes linked to the same Requirement group together.
  • Task rows display downstream mitigation tasks linked to each Failure Mode.
  • The menu bar shows three creation buttons: ”+ Failure Mode”, ”+ System Requirement”, and ”+ Task”.

​
Common Configuration Errors

ErrorCauseFix
Rows appear duplicatedcontrolColumn ID does not match actual column idVerify that controlColumn values exactly match a column id in the columns array
Values auto-populate from previous itemsTwo levels reference the same controlColumnAssign a unique controlColumn to each level
Menu button missing for a levelshowInMenu set to false or dataTypes entry missingSet showInMenu: true and verify dataTypes configuration
Cells do not mergeColumn level property does not align with levels arrayEnsure column level values (1-based) match the intended levels array position (0-based)
Sort order incorrectsortBy column IDs do not match column configurationUse exact column id values in the sortBy array

​
See Also