Multi-Item Link Columns - Nextedy Documentation

itemLink vs multiItemLink Column Behavior
itemLink column (single): multiItemLink column (multiple):
Risk Item: FM-001	Risk Item: FM-001
Requirement: [REQ-042]	Requirements:
(shows ONE linked item)	[REQ-042]
+---------------------------+	[REQ-055]
[REQ-071]
(shows ALL linked items)

Use multiItemLink instead of itemLink when a cell may contain more than one linked work item. An itemLink column shows only one item per cell and silently drops additional links. If you need to display requirements, test cases, or other items where multiple links are expected, always use multiItemLink.

Column Properties

Property	Type	Default	Description
`id`	`string`	Auto-generated from header or binding	Unique identifier for the column. Used in `levels`, `sortBy`, and `cellDecorators` references.
`type`	`string`	Auto-detected	Must be set to `"multiItemLink"` for this column type
`header`	`string`	Required	Column header text displayed at the top of the grid
`binding`	`string`	Required	Data binding for the linked item property. Uses dot notation for nested properties (e.g., `linkedItems.title`).
`level`	`number`	`1`	Hierarchical level at which this column appears (1 = top level, 2 = second level, etc.)
`readOnly`	`boolean`	`false`	Controls whether the column is editable. Automatically set to `true` for formula columns, server-rendered columns, and when permissions deny modification.
`canCreate`	`boolean`	`true`	Controls whether users can create new linked items directly from the cell editor. When `true`, the autocomplete dropdown includes an “Add new [type]” option.
`filterable`	`boolean`	`true`	Controls whether users can filter the Risksheet by values in this column
`formula`	`string`	None	Client-side formula for calculated values. When set, the column becomes read-only by default.
`serverRender`	`string`	None	Server-side rendering script. When set, the column becomes text type and read-only automatically.
`width`	`number`	See application	Column width in pixels
`minWidth`	`number`	See application	Minimum column width in pixels
`visible`	`boolean`	`true`	Controls whether the column is visible in the grid
`group`	`string`	None	Column group header for organizing related columns under a shared header row

Type-Specific Properties

These properties apply specifically to multiItemLink columns.

Property	Type	Default	Description
`typeProperties.linkTypes`	`array`	See application	Array of work item type IDs that can be linked in this column. List multiple types to allow different work item types in the same cell (e.g., `["systemTestCase", "softwareTestCase"]`).
`typeProperties.project`	`string`	Current project	Polarion project ID for linked items. Specify to load items from a different project.
`typeProperties.document`	`string`	See application	Document path where newly created items are stored.
`typeProperties.role`	`string`	See application	Link role used when creating relationships to items in this column.
`typeProperties.customQuery`	`string`	None	Custom query to filter available items in the autocomplete dropdown.

The exact set of typeProperties sub-properties and their behaviors may vary by Risksheet version. The properties listed above are derived from common configuration patterns and support ticket resolutions.

Basic Configuration

A minimal multiItemLink column definition:

{
  "columns": [
    {
      "id": "testCases",
      "header": "Test Cases",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "level": 1
    }
  ]
}

Displaying Multiple Work Item Types

To show different linked work item types in a single column, list all types in typeProperties.linkTypes. This is useful when both system-level and software-level test cases link to the same risk item.

{
  "columns": [
    {
      "id": "allTestCases",
      "header": "Test Cases",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "linkTypes": ["systemTestCase", "softwareTestCase"]
      },
      "level": 1
    }
  ]
}

Instead of creating separate columns for each linked work item type, use a single multiItemLink column with multiple linkTypes. This provides a better overview and reduces the total column count, which also improves performance for large sheets.

Cross-Project Linking

multiItemLink columns can load and display items from a different Polarion project by specifying the typeProperties.project property.

{
  "columns": [
    {
      "id": "sharedRequirements",
      "header": "Shared Requirements",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "project": "SharedRequirementsProject",
        "linkTypes": ["requirement"]
      },
      "level": 2
    }
  ]
}

When loading items from multiple projects, the system uses the first mentioned project for saving new items. You can control which project receives newly created items by listing the preferred project first.

For multiItemLink columns loading items from multiple projects, new items created through the “Add new” option are saved to the first project specified. Ensure the target project has the appropriate work item types and permissions configured.

Creating New Items from multiItemLink Cells

When canCreate is true (the default), users can create new linked work items directly from the cell editor:

Click on a multiItemLink cell to activate the editor
Start typing in the autocomplete field
If no existing item matches, select the “Add new [item type]” option from the dropdown
The new item is created with the typed text as its title and automatically linked to the current risk item

The autocomplete dropdown combines:

Existing items matching the search query from the server
Locally created but unsaved items from the current session
An “Add new [type]” option if canCreate is true

Query Factory for Autocomplete Filtering

You can customize the autocomplete suggestions by configuring a queryFactory that applies custom filtering logic. This restricts which items appear in the dropdown based on business rules.

{
  "columns": [
    {
      "id": "requirements",
      "header": "Requirements",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "linkTypes": ["requirement"],
        "queryFactory": "filterBySystemElement"
      }
    }
  ]
}

The queryFactory references a custom JavaScript function registered in window.risksheet.queryFactories that dynamically generates the filter query based on the current row context.

Query factory support for multiItemLink columns was added in version 24.3.0. Verify that your version supports this feature.

Saving New Items to Specific Documents

When typeProperties.project and typeProperties.document are both specified, newly created items are stored in the designated document within the target project.

{
  "columns": [
    {
      "id": "mitigations",
      "header": "Mitigation Measures",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "project": "CurrentProject",
        "document": "Mitigations/Mitigation Specification",
        "linkTypes": ["mitigationAction"]
      },
      "canCreate": true
    }
  ]
}

Sorting Behavior

When users click the column header to sort a multiItemLink column, the system concatenates all linked item labels into a single string and sorts alphabetically by the combined value. Unsaved items (prefixed with *) are sorted with their asterisk prefix intact.

Cell Content	Sort Key
`[REQ-042] Braking`, `[REQ-055] Emergency`	`"Braking, Emergency"`
`[REQ-001] Airbag`	`"Airbag"`
`*New Requirement`	`"*New Requirement"`

The sortBy configuration can include multiItemLink column IDs for default sort order. Use the ~ prefix for descending sort:

{
  "sortBy": ["~requirements", "systemItemId"]
}

Undo/Redo Support

Changes to multiItemLink cells are tracked by the undo/redo system. When you undo an edit to a multiItemLink cell, all dependent column values are automatically restored to maintain data consistency. This includes:

The linked item references in the cell
Any nested column values that were populated from the linked items
Related column values in merged cell ranges

The undo stack maintains up to 50 actions. Paste operations that affect multiple multiItemLink cells are bundled as a single undoable action.

Excel Export Behavior

When exporting to Excel, multiItemLink columns are rendered as newline-separated lists of linked item labels. Each linked item appears on a separate line within the Excel cell.

Grid Display	Excel Output
`[REQ-042]` `[REQ-055]` `[REQ-071]`	`REQ-042 Braking System`<br/>`REQ-055 Emergency Stop`<br/>`REQ-071 Thermal Protection`

Items with IDs starting with * (unsaved items) are exported with the asterisk prefix to indicate their unsaved state.

Error Handling

Error	Cause	Resolution
`"Invalid column config, itemLink bindings without dot."`	The `binding` property does not use dot notation for linked item properties	Use dot notation: `"linkedItems.title"` instead of `"title"`
`"This item is already linked to selected row."`	Attempting to link an item that is already linked to the current risk item	Choose a different item or remove the existing link first
Items link to only one risk instead of all	Bug in versions before 24.3.0 where new items linked to only one risk in the cell	Update to Risksheet 24.3.0 or later

Complete Example

A comprehensive FMEA configuration with two multiItemLink columns — one for upstream requirements and one for verification test cases:

{
  "columns": [
    {
      "id": "systemItemId",
      "header": "ID",
      "binding": "id",
      "level": 1,
      "readOnly": true,
      "width": 100
    },
    {
      "id": "title",
      "header": "Failure Mode",
      "binding": "title",
      "level": 1,
      "width": 250
    },
    {
      "id": "sev",
      "header": "Severity",
      "binding": "severity",
      "type": "enum",
      "level": 1,
      "width": 80
    },
    {
      "id": "requirements",
      "header": "Linked Requirements",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "linkTypes": ["requirement", "systemRequirement"],
        "role": "verifies"
      },
      "level": 2,
      "canCreate": true,
      "filterable": true,
      "width": 300
    },
    {
      "id": "testCases",
      "header": "Verification Tests",
      "binding": "linkedItems.title",
      "type": "multiItemLink",
      "typeProperties": {
        "linkTypes": ["systemTestCase", "softwareTestCase"],
        "role": "is_verified_by"
      },
      "level": 1,
      "canCreate": true,
      "filterable": true,
      "width": 300
    }
  ],
  "levels": [
    {
      "name": "Failure Mode",
      "controlColumn": "systemItemId",
      "showInMenu": true
    },
    {
      "name": "Requirement",
      "controlColumn": "requirements",
      "showInMenu": false
    }
  ],
  "dataTypes": {
    "risk": {
      "type": "failureMode",
      "role": "relates_to"
    }
  }
}

​Column Properties

​Type-Specific Properties

​Basic Configuration

​Displaying Multiple Work Item Types

​Cross-Project Linking

​Creating New Items from multiItemLink Cells

​Query Factory for Autocomplete Filtering

​Saving New Items to Specific Documents

​Sorting Behavior

​Undo/Redo Support

​Excel Export Behavior

​Error Handling

​Complete Example

​See Also

Column Properties

Type-Specific Properties

Basic Configuration

Displaying Multiple Work Item Types

Cross-Project Linking

Creating New Items from multiItemLink Cells

Query Factory for Autocomplete Filtering

Saving New Items to Specific Documents

Sorting Behavior

Undo/Redo Support

Excel Export Behavior

Error Handling

Complete Example

See Also