> ## Documentation Index > Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt > Use this file to discover all available pages before exploring further. # Multi-Item Link Columns > Multi-item link columns display multiple linked work items per cell. export const LastReviewed = ({date}) => { if (!date) return null; const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" }); return

Last reviewed on {formatted}

; }; | 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: ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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: ```yaml theme={null} 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: 1. Click on a `multiItemLink` cell to activate the editor 2. Start typing in the autocomplete field 3. If no existing item matches, select the "Add new \[item type]" option from the dropdown 4. The new item is created with the typed text as its title and automatically linked to the current risk item diagram 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. ```yaml theme={null} 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). ```yaml theme={null} 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: ```yaml theme={null} 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`\
`REQ-055 Emergency Stop`\
`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: ```yaml theme={null} 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 ``` ## See Also * [Item Link Columns](/risksheet/reference/columns/item-link-columns) -- Single-item link column type for one linked item per cell * [Task Link Columns](/risksheet/reference/columns/task-link-columns) -- Columns for downstream task/mitigation links * [Column Type Reference](/risksheet/reference/columns/column-types) -- Overview of all available column types * [Levels Configuration](/risksheet/reference/levels-configuration) -- Hierarchical level configuration including `controlColumn` * [Data Types](/risksheet/reference/columns/data-types) -- Configuring risk and task data types * [Suggestion and Autocomplete API](/risksheet/reference/api/suggestion-api) -- API behind linked item autocomplete