Skip to main content

​
Prerequisites

The queryFactory property connects a link column to a JavaScript function that generates dynamic query constraints. When users search for items to link, the query factory filters the results based on the current row context.

​
Step 1: Register a Query Factory Function

Query factory functions are registered on the global window.risksheet.queryFactories object. Add your function using a TopPanel script or a wiki page script block: 
window.risksheet = window.risksheet || {};
window.risksheet.queryFactories = window.risksheet.queryFactories || {};

window.risksheet.queryFactories.filterBySystemElement = function(item, column) {
  var sysElement = item['linkedSystemElement'];
  if (sysElement) {
    return "linkedWorkItems:(" + sysElement + ")";
  }
  return "";
};
This example filters suggestions to show only items linked to the same system element selected in the current row.

​
Step 2: Reference the Query Factory in Column Configuration

Add the queryFactory property to the link column in risksheet.json: 
{
  "columns": [
    {
      "id": "requirement",
      "header": "Requirement",
      "type": "itemLink",
      "level": 1,
      "queryFactory": "filterBySystemElement"
    }
  ]
}
When users click the dropdown or start typing, the query factory function is called with the current row data and column configuration. The returned query string is appended to the search criteria. diagram Query factories also work with multiItemLink columns. The editor applies the filter each time the user searches, requiring a minimum of 3 characters before the search triggers. Use cell decorators with the systemReadOnlyFields property to prevent linking based on other field values: 
{
  "cellDecorators": {
    "lockIfApproved": "function(info){ if(info.item['status'] === 'approved') { info.item.systemReadOnlyFields = info.item.systemReadOnlyFields || []; info.item.systemReadOnlyFields.push('requirement'); }}"
  },
  "columns": [
    {
      "id": "requirement",
      "header": "Requirement",
      "type": "itemLink",
      "cellDecorator": "lockIfApproved"
    }
  ]
}
This makes the requirement link column read-only when the row’s status is “approved”, preventing further link modifications after approval.
Use queryFactory to filter available items during search and systemReadOnlyFields to lock columns entirely based on workflow state. These two mechanisms complement each other for comprehensive link control.
Starting with version 24.2.2, Risksheet supports the checkLinkRoleCompliance property for multiple link roles from risk items. This must be explicitly enabled:
  1. Navigate to Polarion Administration > Configuration Properties
  2. Add: nextedy.risksheet.checkLinkRoleCompliance=true
  3. Save and restart the Polarion service
The checkLinkRoleCompliance property changes how link roles are validated. Enabling this in an existing configuration may affect link column behavior. Test in a development environment before enabling in production.
FeatureitemLinkmultiItemLinktaskLink
Query factorySupportedSupportedSupported
canCreateYes (default true)Yes (default true)N/A
Duplicate preventionN/A (single item)AutomaticN/A
Context menu navigationOpen Linked ItemOpen Linked ItemOpen Task Item
readOnly overrideSupportedSupportedSupported

​
Troubleshooting

Query factory function not called — Verify the function is registered on window.risksheet.queryFactories before the risksheet loads. Check that the queryFactory value matches the registered function 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 column binding for an itemLink column must include a dot separator (e.g., requirement.title). Verify your column binding format.

​
Verify

After configuring the queryFactory, reload the risksheet and click on the link column. Type at least 3 characters to trigger the search. You should now see only items matching your query factory filter in the suggestion dropdown, rather than all available items.

​
See Also