> ## 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.

# Enable Conditional Linking

> Restrict which work items can be linked to a Nextedy RISKSHEET row based on query filters, field values, or workflow state.

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 <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* An existing risksheet with link columns (`itemLink`, `multiItemLink`, or `taskLink`)
* Administrator access to edit the sheet configuration (the sheet configuration file, `risksheet.json`)
* Familiarity with [upstream traceability columns](/risksheet/guides/columns/upstream-traceability) or [downstream traceability columns](/risksheet/guides/columns/downstream-traceability)

## Filter Link Suggestions with `queryFactory`

A query factory is a named JavaScript function that returns a Lucene query string. The query string is appended to the autocomplete search criteria for a link column, so the suggestion dropdown only shows work items that match both the user's typed text and your filter.

### Step 1: Define the Query Factory in the Sheet Configuration

Query factories live in the top-level `queryFactories` section of the sheet configuration. Each entry is a named function that receives an `info` object (current row context) and returns a Lucene query string.

```yaml theme={null}
queryFactories:
  filterBySystemElement: |
    function(info) {
      var sysElement = info.item['linkedSystemElement'];
      if (sysElement) {
        return 'linkedWorkItems:(' + sysElement + ')';
      }
      return '';
    }
```

This factory filters suggestions to work items linked to the same system element selected in the current row. If no element is selected yet, the factory returns an empty string (no extra filter applied).

### Step 2: Reference the Query Factory from a Link Column

For `itemLink` and `multiItemLink` columns, set `queryFactory` inside the column's `typeProperties` block. The value is the name of the registered factory:

```yaml theme={null}
columns:
  - id: requirement
    header: Requirement
    type: itemLink
    bindings: linkedRequirement
    level: 1
    typeProperties:
      linkRole: relates_to
      linkTypes: requirement
      queryFactory: filterBySystemElement
```

When users type in the autocomplete, Risksheet calls `filterBySystemElement(info)` with the current row data, appends the returned query to the search, and shows only matching work items.

### Step 3: Reload and Verify

Save the sheet configuration. The autocomplete requires a minimum of 3 characters before the search triggers — type at least three characters in the link cell and confirm that suggestions are now limited to items matching your filter.

## Interactive Filtering from the Top Panel

A query factory can read user input from the top panel (`risksheetTopPanel.vm`) using jQuery, turning a dropdown into a live filter for autocomplete suggestions.

```yaml theme={null}
queryFactories:
  hazardQuery: |
    function(info) {
      var sel = $('#asilFilter').val();
      if (sel === 'all') { return ''; }
      return 'asilClassification:' + sel;
    }
```

Users pick a classification in the top panel (for example, a `<select id="asilFilter">` element), and itemLink autocomplete results update on the next search. This pattern enables stage-by-stage analysis without rewriting the sheet configuration.

## Make Link Columns Conditionally Read-Only

To lock a link column based on row data, use a cell decorator that appends the column's field ID to `info.item.systemReadOnlyFields`. This property is a **pipe-delimited string** (not an array), and a column whose binding appears between two pipes becomes read-only for that specific row.

```yaml theme={null}
cellDecorators:
  lockIfApproved: |
    function(info) {
      if (info.item['status'] === 'approved') {
        info.item.systemReadOnlyFields = (info.item.systemReadOnlyFields || '') + '|linkedRequirement|';
        info.cell.addClass('rs-readonly');
      }
    }
columns:
  - id: requirement
    header: Requirement
    type: itemLink
    bindings: linkedRequirement
    cellRenderer: lockIfApproved
```

The column property is `cellRenderer`, and its value names a function defined in the `cellDecorators` section. The built-in `rs-readonly` CSS class grays the cell out so users see the locked state.

<Tip title="Combine with query factory">
  Use `queryFactory` to filter what users can choose, and `cellRenderer` plus `systemReadOnlyFields` to lock cells entirely based on workflow state. The two mechanisms complement each other for comprehensive link control.
</Tip>

## Enable Link Role Compliance

From Risksheet 24.2.2 onward, the `checkLinkRoleCompliance` property validates multiple link roles from risk items. It is disabled by default and must be enabled explicitly:

1. Navigate to **Administration > Nextedy Risksheet > Setup** at the Polarion server level
2. Add the configuration property `nextedy.risksheet.checkLinkRoleCompliance=true`
3. Save and restart the Polarion service

<Warning title="Backward incompatible change">
  `checkLinkRoleCompliance` changes how link roles are validated. Enabling it on an existing project may affect link column behavior. Test in a sandbox project before applying it in production.
</Warning>

## Link Column Behavior Summary

| Feature                               | `itemLink`           | `multiItemLink`      | `taskLink`     |
| ------------------------------------- | -------------------- | -------------------- | -------------- |
| `queryFactory` (via `typeProperties`) | Supported            | Supported            | Supported      |
| `canCreate`                           | Yes (default `true`) | Yes (default `true`) | N/A            |
| Duplicate prevention                  | N/A (single item)    | Automatic            | N/A            |
| Context menu navigation               | Open Linked Item     | Open Linked Item     | Open Task Item |
| `readOnly` override                   | Supported            | Supported            | Supported      |

## Troubleshooting

**Query factory function not called.** Verify the factory is defined in the `queryFactories` section of the sheet configuration and that `typeProperties.queryFactory` on the column matches the factory name exactly.

**"This item is already linked to selected row".** The `multiItemLink` editor prevents duplicate links automatically. Each work item can be linked only once per cell.

**"Invalid column config, itemLink bindings without dot".** The `bindings` value for an `itemLink` column displaying a linked field must include a dot separator (for example, `requirement.title`). Verify the binding format.

## See Also

* [Use Query Factory](/risksheet/guides/advanced/query-factory) — advanced query factory patterns
* [Configure Queries](/risksheet/guides/advanced/query-configuration) — Lucene query syntax reference
* [Enable Editing of Upstream Columns](/risksheet/guides/columns/edit-upstream-columns) — making link columns editable
* [Consolidate Multiple Link Columns](/risksheet/guides/columns/consolidate-link-columns) — combining link columns
* [Configure Dependent Enums](/risksheet/guides/advanced/dependent-enums) — cascading selection patterns

<LastReviewed date="2026-06-24" />
