> ## 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.
# Item Link Columns
> Item link columns display a single linked work item reference in a Nextedy RISKSHEET 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}
;
};
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](/risksheet/reference/columns/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.):
```yaml theme={null}
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:
```yaml theme={null}
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):
```yaml theme={null}
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.
```yaml theme={null}
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.
## Context Menu
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:
```yaml theme={null}
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
```