Multi-Item Link Columns - Nextedy Documentation

Column type	Cell behavior
`itemLink`	Shows a single linked item per cell; additional links are silently dropped.
`multiItemLink`	Shows multiple linked items per cell. Use when more than one link is expected.

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 bindings	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
`bindings`	`string`	Required	Polarion field ID 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 Nextedy 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
`headerGroup`	`string`	None	Column group header for organizing related columns under a shared header row

Type-Specific Properties

These typeProperties sub-properties apply specifically to multiItemLink columns.

Property	Type	Default	Description
`typeProperties.linkRole`	`string`	See application	Link role used when creating relationships to items in this column (for example, `verifies`, `is_verified_by`).
`typeProperties.linkTypes`	`string`	See application	Comma-separated list of Polarion work item type IDs that can be linked in this column. List multiple types to allow different work item types in the same cell (for example, `systemTestCase,softwareTestCase`).
`typeProperties.linkDirection`	`string`	Forward	Direction of link traversal. Set to `"back"` to traverse the link in reverse (back-link).
`typeProperties.backLink`	`boolean`	`false`	When `true`, the column renders the back-link side of the relationship rather than the forward side.
`typeProperties.itemTemplate`	`string`	See application	Velocity template that controls how each linked item is displayed in the cell.
`typeProperties.queryFactory`	`string`	None	Name of a registered queryFactory function that produces a Lucene filter for the autocomplete dropdown.
`typeProperties.project`	`string`	Current project	Polarion project ID for linked items. Specify to load items from a different project. Space-separated values and the `$projectId` variable support multi-project autocomplete.
`typeProperties.document`	`string`	See application	Document path where linked items are scoped or where newly created items are stored. Useful for shared upstream library patterns.

The exact set of typeProperties sub-properties and their behaviors may vary by Risksheet version. The properties listed above are verified against production sheet configurations and the Nextedy Support Portal.

Basic Configuration

A minimal multiItemLink column definition in the sheet configuration:

columns:
  - id: testCases
    header: Test Cases
    bindings: 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 as a comma-separated string. This is useful when both system-level and software-level test cases link to the same risk item.

columns:
  - id: allTestCases
    header: Test Cases
    bindings: 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
    bindings: 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. Use a space-separated list (and the $projectId runtime variable for the current project) to enable multi-project autocomplete:

columns:
  - id: sharedHazards
    header: Shared Hazards
    bindings: linkedItems.title
    type: multiItemLink
    typeProperties:
      project: '$projectId HARA_Demo HARA_SampleProject'
      linkTypes: 'hazard'

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. The queryFactory references a named function defined in the top-level queryFactories section of the sheet configuration; the function returns a Lucene query string used to filter dropdown suggestions based on the current row context.

columns:
  - id: requirements
    header: Requirements
    bindings: linkedItems.title
    type: multiItemLink
    typeProperties:
      linkTypes: 'requirement'
      queryFactory: filterBySystemElement

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. This pattern is also used for shared upstream library scoping (for example, restricting autocomplete to items from a shared harms or requirements library).

columns:
  - id: mitigations
    header: Mitigation Measures
    bindings: 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 `bindings` 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
    bindings: id
    level: 1
    readOnly: true
    width: 100

  - id: title
    header: Failure Mode
    bindings: title
    level: 1
    width: 250

  - id: sev
    header: Severity
    bindings: severity
    type: enum:severity
    level: 1
    width: 80

  - id: requirements
    header: Linked Requirements
    bindings: linkedItems.title
    type: multiItemLink
    typeProperties:
      linkTypes: 'requirement,systemRequirement'
      linkRole: verifies
    level: 2
    canCreate: true
    filterable: true
    width: 300

  - id: testCases
    header: Verification Tests
    bindings: linkedItems.title
    type: multiItemLink
    typeProperties:
      linkTypes: 'systemTestCase,softwareTestCase'
      linkRole: is_verified_by
    level: 1
    canCreate: true
    filterable: true
    width: 300

levels:
  - name: Failure Mode
    controlColumn: systemItemId
    zoomColumn: systemItemId
  - name: Requirement
    controlColumn: requirements
    zoomColumn: requirements

dataTypes:
  risk:
    type: failureMode

​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