Skip to main content

​
Overview

The levels property in your risksheet.json configuration defines the hierarchical structure of your risk analysis. Each level represents a grouping dimension in your FMEA/HARA analysis. diagram Each level contains columns that are visually merged when they have identical values. The last level +1 represents downstream work items (typically mitigation tasks) linked to the risk items.

​
Essential Level Properties

PropertyTypeRequiredDescription
namestringYesDisplay label for the level, shown in toolbar menu buttons (e.g., ”+ Failure Mode”, ”+ Cause”)
controlColumnstringYesColumn ID that controls vertical cell merging for this level. Cells merge when values in this column are identical
zoomColumnstringYesColumn ID where the cursor highlights when a new row is created at this level
showInMenubooleanNoControls whether the ”+” button for this level appears in the toolbar. Default: true

​
Configuration Example

{
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "failureMode",
      "zoomColumn": "failureMode"
    },
    {
      "name": "Cause",
      "controlColumn": "systemItemId",
      "zoomColumn": "causes"
    }
  ],
  "dataTypes": {
    "risk": {
      "type": "risk"
    },
    "task": {
      "type": "task",
      "role": "mitigates",
      "name": "Task"
    }
  }
}

​
How Levels Control Merging

​
Level 1 (Failure Mode)

  • Columns at Level 1 are merged vertically based on the controlColumn value
  • When multiple rows share the same “Failure Mode” value, those cells merge into a single visual cell
  • This creates the visual grouping that users see in your risk analysis

​
Level 2 and Beyond (Causes)

  • Columns at Level 2+ are also merged based on their level’s controlColumn
  • Level 2 typically uses systemItemId as the control column, which means cells do not merge (each risk item has a unique ID)
  • This is the expected behavior for FMEA: causes belong to specific failure modes, not shared across them

​
Last Level + 1 (Tasks/Mitigations)

  • Task columns represent downstream work items linked to the risk items
  • Task columns are never merged—each task row is independent
  • Task creation and linking is controlled by the dataTypes.task configuration

​
Creating Menu Bar Buttons

The toolbar buttons (like ”+ Failure Mode”, ”+ Cause”) are automatically generated from your levels configuration. Each level with "showInMenu": true creates a corresponding button.
When you click a toolbar button (e.g., ”+ Failure Mode”), the system:
  1. Creates a new risk work item
  2. Jumps the cursor to the column specified in zoomColumn
  3. Highlights the new row for immediate editing
To hide a level button, set "showInMenu": false: 
{
  "name": "Hidden Level",
  "controlColumn": "hiddenField",
  "zoomColumn": "hiddenField",
  "showInMenu": false
}

​
Level-to-Column Binding

Every column in your configuration must declare which level it belongs to using the level property: 
{
  "columns": [
    {
      "id": "failureMode",
      "header": "Failure Mode",
      "bindings": "failureMode",
      "level": 1
    },
    {
      "id": "causes",
      "header": "Causes",
      "bindings": "causes",
      "level": 2
    },
    {
      "id": "severity",
      "header": "Severity",
      "bindings": "severity",
      "level": 2
    }
  ]
}
Columns without a level property are assumed to be task-level columns (downstream items).

​
Control Column Constraints

Each level must have a unique control column. Multiple levels cannot reference the same column as their controlColumn. This causes configuration errors and unpredictable merging behavior.
Valid configuration: 
{
  "levels": [
    { "name": "Failure Mode", "controlColumn": "failureMode" },
    { "name": "Cause", "controlColumn": "systemItemId" }
  ]
}
Invalid configuration (will cause errors): 
{
  "levels": [
    { "name": "Failure Mode", "controlColumn": "title" },
    { "name": "Cause", "controlColumn": "title" }  // ❌ Duplicate!
  ]
}

​
Multi-Level Hierarchy Example

A typical three-level FMEA structure:
PropertyLevel 1Level 2Level 3 (Tasks)
RepresentsFailure ModeCauseMitigation Task
Work Item TypeRisk ItemRisk ItemTask Item
Control ColumnfailureModesystemItemIdn/a
MergedYes (by failureMode)No (unique IDs)No (independent tasks)
Menu Button”+ Failure Mode""+ Cause”n/a (auto-created via link)

​
Zoom Column Behavior

The zoomColumn defines where the cursor lands when creating a new row. This is purely for UX convenience: 
{
  "name": "Failure Mode",
  "controlColumn": "failureMode",
  "zoomColumn": "failureMode"  // Jump to Failure Mode cell
}
Different levels can zoom to different columns: 
{
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "failureMode",
      "zoomColumn": "failureMode"  // Zoom to Failure Mode
    },
    {
      "name": "Cause",
      "controlColumn": "systemItemId",
      "zoomColumn": "causes"  // Zoom to Causes (more specific field)
    }
  ]
}

​
Data Types and Level Interaction

The dataTypes configuration works in tandem with levels: 
{
  "dataTypes": {
    "risk": {
      "type": "risk"  // Work item type for Level 1 & 2
    },
    "task": {
      "type": "task",
      "role": "mitigates",  // Link role for task creation
      "name": "Task",
      "zoomColumn": "taskTitle"
    }
  }
}
  • risk section: Controls Level 1 and Level 2 row creation and work item linking
  • task section: Controls Level 3 (Last Level + 1) row creation via linked tasks

​
Troubleshooting Level Configuration

​
Issue: Cells Not Merging as Expected

Check your controlColumn values:
  • Ensure the column actually exists in your columns array
  • Verify column bindings match actual work item field names
  • Confirm that test data has consistent values in the control column

​
Issue: Menu Buttons Missing

Verify showInMenu setting: 
{ "showInMenu": false }  // Button will not appear
{ "showInMenu": true }   // Button will appear (default)

​
Issue: Configuration Validation Errors

Common causes:
  • Duplicate control columns across levels
  • Missing controlColumn or zoomColumn properties
  • Control column references non-existent field
  • Level number mismatches between levels array and column definitions
Related FeatureReference Page
Data TypesSee Risksheet.json Format for dataTypes configuration
Column ConfigurationSee Column Type Reference for level property on columns
Work Item VisibilitySee Work Item Visibility and Levels for strategic overview
Configuration SystemSee Configuration System for hierarchy and precedence

​
Best Practices

Do:
  • Use meaningful names that match FMEA terminology (“Failure Mode”, “Cause”, “Effect”)
  • Make control columns unique across all levels
  • Align zoom columns with the most important editable field at each level
  • Keep level count to 2–3 for clarity and performance
Don’t:
  • Reuse the same control column in multiple levels
  • Create more than 4–5 levels (performance degrades with deep hierarchies)
  • Use systemItemId as a control column unless you want no merging
  • Set zoomColumn to a read-only or calculated column