Item Link Columns - Nextedy Documentation

Risksheet is a generic tool supporting any risk management methodology (FMEA, HARA, TARA, STRIDE, CVSS, and others). The itemLink column type is a generic upstream traceability mechanism — it links risk items to any Polarion work item type using configured link roles.

Column Type

Syntax	Description
`itemLink`	Auto-detected when binding refers to a linked work item field

itemLink displays only one linked item per cell. If multiple items are linked, additional links are silently dropped. Use Multi-Item Link Columns when you need to display multiple linked items in a single cell.

Column Properties

Name	Type	Default	Description
`id`	`string`	Auto-generated from header or bindings	Unique identifier for the column
`type`	`string`	Auto-detected from bindings	Set to `itemLink` for single-item link columns
`header`	`string`	None	Display text in the column header
`bindings`	`string`	Same as `id`	The Polarion field reference. For link columns, uses dot notation (e.g., `sysReq.title`)
`readOnly`	`boolean`	Upstream columns default to `true`	Controls whether the column cells can be edited
`canCreate`	`boolean`	`true`	Controls whether users can create new linked items from the cell editor. When `false`, users can only link or unlink existing items
`filterable`	`boolean`	`true`	Controls whether users can filter by values in this column
`level`	`number`	`1`	Visual hierarchy level for cell merging (1-indexed; maps to `levels[level-1]`). An unleveled risk-item column defaults to level 1 and merges into the first level.
`width`	`number`	See application	Column width in pixels
`minWidth`	`number`	See application	Minimum resize width in pixels
`headerGroup`	`string`	None	Header group for multi-level headers
`typeProperties`	`object`	None	Sub-configuration controlling link role, allowed types, autocomplete scope, and rendering

Binding Patterns

Risksheet item-related columns support three binding patterns. Choose the pattern that matches what you want to display or edit:

Pattern	Example	Description
`fieldId`	`bindings: title`	Direct field on the risk work item — editable
`linkedItem.fieldId`	`bindings: harm.title`	Field on a linked item — displayed read-only
`linkedItem.$item`	`bindings: task.$item`	Entire linked item object — accessed via `serverRender` Velocity template for custom rendering

For itemLink columns specifically, the binding pattern is linkName.property (a dot-notation binding to a property of the linked item, such as sysReq.title).

Item link bindings must contain a dot character. The system logs a warning for invalid configurations: "Invalid column config, itemLink bindings without dot.".

A companion linkName_link binding (with the _link suffix) provides the HTML hyperlink URL for the linked item and can be used to render the cell as a clickable link.

typeProperties for itemLink Columns

The typeProperties object on an itemLink column configures which Polarion items the column can reference and how the link is rendered. All six sub-properties are verified against real production configurations.

Sub-property	Type	Description
`linkRole`	`string`	Polarion link role connecting the risk item to the linked item (e.g., `mitigates`, `relates_to`)
`linkTypes`	`string`	Comma-separated Polarion work item type IDs that this column may reference (e.g., `characteristic,requirement`)
`linkDirection`	`string`	Direction of the link traversal. Use with `backLink` for reverse direction
`backLink`	`boolean`	When `true`, renders reverse-direction links (items that point TO the risk, rather than FROM it)
`itemTemplate`	`string`	Velocity template used to render the linked item display (overrides default rendering)
`queryFactory`	`string`	Reference to a named function in the `queryFactories` section that returns a Lucene query for autocomplete filtering

Scoping Properties (Optional)

Sub-property	Type	Description
`document`	`string`	Restricts autocomplete to items from a specific document path. Enables the library pattern for shared upstream references
`project`	`string`	Project scoping for autocomplete. Supports the `$projectId` runtime variable and a space-separated list for multi-project autocomplete
`createInCurrentDocument`	`boolean`	When `true`, new linked items are created in the current LiveDoc document

Library Pattern with `document`

Use typeProperties.document to point an itemLink column at a shared reference document (a harms library, requirements catalog, function library, etc.):

columns:
  - id: harm
    header: Harm
    type: itemLink
    bindings: harm.title
    typeProperties:
      linkRole: caused_by
      linkTypes: harm
      document: 02 - Risk Management File/Harms Library

This is the recommended pattern for upstream traceability to shared library documents.

Cross-Project Autocomplete with `project`

The project sub-property accepts the $projectId runtime variable and a space-separated list of project IDs for cross-project autocomplete:

columns:
  - id: hazard
    header: Hazard
    type: itemLink
    bindings: hazard.title
    typeProperties:
      linkRole: relates_to
      linkTypes: hazard
      project: $projectId HARA_Demo HARA_SampleProject

typeProperties.project (on an itemLink column) is a space-separated string. This is different from dataTypes.task.projects (an array for downstream task items, v23.7.0+).

Reverse-Direction Linking with `backLink`

Set typeProperties.backLink: true to render items that link into the risk item (rather than items the risk item links out to). This is useful when the canonical link direction in the data model is from the upstream item to the risk, but you want to display the relationship from the risk’s perspective.

Multiple Link Types

linkTypes is a comma-separated string of Polarion work item type IDs (it is not a JSON array):

columns:
  - id: upstream
    header: Upstream
    type: itemLink
    bindings: upstream.title
    typeProperties:
      linkRole: traces_to
      linkTypes: characteristic,requirement

Autocomplete Behavior

When editing an item link cell, an autocomplete editor searches for linkable items through the server data access layer. The search requires a minimum of 3 characters before returning results.

Behavior	Description
Search	Substring match on item ID and type, minimum 3 characters
`queryFactory`	Optional custom Lucene query constraints, referenced by name in `typeProperties.queryFactory`
Dependent columns	Selecting an item automatically populates nested columns from the selected item’s properties
Duplicate prevention	Error displayed if item is already linked: `"This item is already linked to selected row."`

Disabling Item Creation

Set canCreate to false to allow linking and unlinking existing items while preventing creation of new items. Default is true. Applies to itemLink, multiItemLink, and taskLink columns.

columns:
  - id: sysReq
    header: System Requirement
    type: itemLink
    bindings: sysReq.title
    canCreate: false
    typeProperties:
      linkRole: mitigates
      linkTypes: systemRequirement

Use canCreate: false for upstream columns where linked items should be pre-created in a shared library document (combined with typeProperties.document) rather than created inline from the grid.

canCreate also exists at the dataTypes.task level as a global switch. When dataTypes.task.canCreate: false, users cannot create new task items at all — only link to existing ones. The column-level canCreate is independent and applies per column.

Multi-Project Support

Item link columns can load items from multiple projects via typeProperties.project. When creating new items in a multi-project column, the system saves to the first mentioned project by default. Use createInCurrentDocument: true to override this and save new items in the current project’s current document.

Link Role Compliance

The checkLinkRoleCompliance property (version 24.2.2+) enables multiple link roles from a risk item for item link columns.

The checkLinkRoleCompliance property must be explicitly enabled in Polarion Administration Configuration Properties via nextedy.risksheet.checkLinkRoleCompliance=true. This is a backward incompatible change.

Right-click on an item link cell to access:

Action	Description
Open Linked Item	Opens the linked work item in Polarion’s item editor. Available when cell contains a valid item link.

Cell Merging

Item link columns participate in hierarchical cell merging based on the column’s level property. When undoing edits to merged item link cells, the undo operation applies to all rows in the merged range.

Export Behavior

Format	Rendering
Excel	Plain text with HTML formatting stripped
PDF	Label property displayed as text

Complete Example

The following example shows an itemLink column referencing requirements from a shared library document, with autocomplete scoped to the current project and a partner project:

columns:
  - id: sysReq
    header: System Requirement
    type: itemLink
    bindings: sysReq.title
    level: 1
    width: 200
    canCreate: false
    filterable: true
    typeProperties:
      linkRole: mitigates
      linkTypes: systemRequirement
      document: 02 - Requirements/System Requirements
      project: $projectId SharedRequirements
      createInCurrentDocument: true

dataTypes:
  risk:
    type: fmeaRisk

​Column Type

​Column Properties

​Binding Patterns

​typeProperties for itemLink Columns

​Scoping Properties (Optional)

​Library Pattern with document

​Cross-Project Autocomplete with project

​Reverse-Direction Linking with backLink

​Multiple Link Types

​Autocomplete Behavior

​Disabling Item Creation

​Multi-Project Support

​Link Role Compliance

​Context Menu

​Cell Merging

​Export Behavior

​Complete Example

Column Type

Column Properties

Binding Patterns

typeProperties for itemLink Columns

Scoping Properties (Optional)

Library Pattern with `document`

Cross-Project Autocomplete with `project`

Reverse-Direction Linking with `backLink`

Multiple Link Types

Autocomplete Behavior

Disabling Item Creation

Multi-Project Support

Link Role Compliance

Context Menu

Cell Merging

Export Behavior

Complete Example