Display Multi-Level Hierarchies - Nextedy Documentation

Define Levels in Configuration

Add a levels array to your risksheet.json. Each entry specifies a controlColumn that identifies work items at that hierarchy tier:

{
  "levels": [
    {
      "controlColumn": "sysElement",
      "showInMenu": true
    },
    {
      "controlColumn": "failureMode",
      "showInMenu": true
    },
    {
      "controlColumn": "cause",
      "showInMenu": false
    }
  ]
}

Property	Type	Default	Description
`controlColumn`	string	required	Column `id` that drives grouping and merging at this level
`showInMenu`	boolean	`true`	Whether this level appears in the context menu for creating new items

Assign Columns to Levels

Each column in your columns array should specify which level it belongs to. Columns at the same level merge vertically when their parent control column values match:

{
  "columns": [
    {
      "id": "sysElement",
      "header": "System Element",
      "binding": "title",
      "level": 1
    },
    {
      "id": "failureMode",
      "header": "Failure Mode",
      "binding": "title",
      "level": 2,
      "type": "itemLink"
    },
    {
      "id": "cause",
      "header": "Cause",
      "binding": "title",
      "level": 3,
      "type": "itemLink"
    },
    {
      "id": "sev",
      "header": "Severity",
      "binding": "severity",
      "level": 2,
      "type": "rating:severity_scale"
    }
  ]
}

The level property defaults to 1 when not specified. Task columns do not have a level assigned.

Two different levels must not point to the same controlColumn value. Duplicate control columns cause description values from previous items to auto-populate into new items and trigger incorrect cell merging.

Understand Merge Behavior

Risksheet automatically merges cells based on the levels hierarchy:

Level 1 (System)	Level 2 (Failure Mode)	RPN
Braking System	Fluid leak	120
(merged cell)	Loss of braking	180
(merged cell)	Pad contamination	240
Unintended brake	Sensor short circuit	360
(merged cell)	ABS software fault	280

Key merge rules:

Level 2 cells merge within the same level 1 group when their control column values match
Empty cells in control columns act as merge boundaries — they stop merge propagation to prevent unrelated groups from joining
Downstream and task columns follow separate merge rules based on work item ID grouping

If a level 1 control column cell is empty, level 2 and higher cells in that row will not merge with adjacent rows. This is intentional to maintain clean visual separation between hierarchy groups.

Display Multi-Level Linked Items

To display items linked across multiple levels (such as Level 0 to Level 1 to Level 2), you have two approaches:

Approach A: Transitive Linking with `upstreamChains`

The upstreamChains property automatically builds transitive link chains across levels:

{
  "upstreamChains": [
    "FailureMode-causes-Cause",
    "SystemElement-has_failure-FailureMode"
  ]
}

The format is fromType-linkRole-toType. This creates automatic transitive links so items linked through intermediate levels appear in the correct hierarchy.

The upstreamChains property only creates links — it never deletes them. Once a transitive link is established, it persists even if the intermediate link is removed.

Approach B: Server-Side Rendering for Read-Only Display

For read-only display of indirectly linked items, use serverRender with a Velocity script:

{
  "id": "indirectReq",
  "header": "Linked Requirement",
  "serverRender": "$item.fields().get('linkedReqField').render().htmlFor().forFrame()",
  "level": 1
}

Columns with serverRender are automatically read-only and render on the server side.

Configure Sort Order for Hierarchies

Define the default sort order to align with your hierarchy using sortBy:

{
  "sortBy": ["sysElement", "failureMode", "cause"]
}

This ensures the grid rows are arranged to match the hierarchy structure, which is essential for proper cell merging.

Complete FMEA Hierarchy Example

A three-level FMEA configuration with System Element, Failure Mode, and Cause:

{
  "levels": [
    { "controlColumn": "sysElement", "showInMenu": true },
    { "controlColumn": "failureMode", "showInMenu": true },
    { "controlColumn": "cause", "showInMenu": false }
  ],
  "columns": [
    { "id": "sysElement", "header": "System Element", "binding": "title", "level": 1 },
    { "id": "failureMode", "header": "Failure Mode", "binding": "title", "level": 2, "type": "itemLink" },
    { "id": "failureEffect", "header": "Failure Effect", "binding": "description", "level": 2 },
    { "id": "cause", "header": "Cause", "binding": "title", "level": 3, "type": "itemLink" },
    { "id": "sev", "header": "S", "binding": "severity", "level": 2, "type": "rating:severity_scale" },
    { "id": "occ", "header": "O", "binding": "occurrence", "level": 3, "type": "rating:occurrence_scale" },
    { "id": "det", "header": "D", "binding": "detection", "level": 3, "type": "rating:detection_scale" },
    { "id": "rpn", "header": "RPN", "formula": "commonRpn", "level": 3 }
  ],
  "sortBy": ["sysElement", "failureMode", "cause"],
  "formulas": {
    "commonRpn": "function(info){ var value = info.item['occ']*info.item['det']*info.item['sev']; return value?value:null;}"
  }
}

Troubleshooting

Problem	Cause	Solution
Rows are duplicated	`controlColumn` ID does not match column `id`	Verify exact string match between `levels[].controlColumn` and `columns[].id`
Cells do not merge	Empty values in control column	Ensure parent-level control columns always have values
Two levels point to same column	Configuration error	Each level must use a unique `controlColumn` value
New items get wrong values	Duplicate `controlColumn` across levels	Correct the levels configuration so each level has its own control column

Verification

After configuring your levels hierarchy, you should now see:

Level 1 cells merging vertically when consecutive rows share the same system element
Level 2 cells merging within their parent level 1 group
The context menu showing “New Item” options for levels where showInMenu is true
Rows sorted according to the sortBy order, preserving the hierarchy structure

​Define Levels in Configuration

​Assign Columns to Levels

​Understand Merge Behavior

​Display Multi-Level Linked Items

​Approach A: Transitive Linking with upstreamChains

​Approach B: Server-Side Rendering for Read-Only Display

​Configure Sort Order for Hierarchies

​Complete FMEA Hierarchy Example

​Troubleshooting

​Verification

​See Also

Define Levels in Configuration

Assign Columns to Levels

Understand Merge Behavior

Display Multi-Level Linked Items

Approach A: Transitive Linking with `upstreamChains`

Approach B: Server-Side Rendering for Read-Only Display

Configure Sort Order for Hierarchies

Complete FMEA Hierarchy Example

Troubleshooting

Verification

See Also