Skip to main content

​
Step 1: Understand Query Factory

A query factory is a JavaScript function that generates custom query constraints for autocomplete suggestions. When a user types in a link column, the query factory dynamically builds a filter that restricts which items appear in the dropdown. diagram Query factories are registered on the window.risksheet.queryFactories object and referenced by name in column configuration.

​
Step 2: Register a Query Factory Function

Add your query factory function to the Risksheet configuration or a custom script. Query factories are registered as named functions: 
{
  "columns": [
    {
      "header": "Requirement",
      "binding": "linkedRequirement",
      "type": "itemLink",
      "queryFactory": "filterByLinkedElement"
    }
  ]
}
The queryFactory property on a column references the registered factory name. When the user edits this column, the factory function is called to generate additional query constraints.

​
Step 3: Create a Dependent Column Filter

A common use case is filtering one upstream column based on the value selected in another. For example, filtering Requirements based on a linked System Element:
  1. Define the first column (System Element) as a standard link column.
  2. Define the second column (Requirement) with a queryFactory that reads the selected System Element.
  3. The factory returns a query that limits Requirements to those linked to the selected System Element.
Use canCreate: false on upstream columns where items should be pre-created in the tracker. This keeps the cell active for linking and unlinking existing items while preventing creation of new ones. Combined with a query factory, this enables powerful dependent upstream filtering.
Control whether users can create new items directly from the link editor: 
{
  "columns": [
    {
      "header": "Hazardous Situation",
      "binding": "linkedHazSit",
      "type": "itemLink",
      "canCreate": false,
      "queryFactory": "filterBySequenceOfEvents"
    }
  ]
}
Setting canCreate to false allows selection and unlinking of existing items while disabling item creation from the autocomplete editor. The default value of canCreate is true. Query factories also work with multiItemLink columns. The behavior is the same — the factory function provides additional query constraints that filter the autocomplete results.
Column IDs used in levels and sortBy parameters must exactly match the id property defined in column configurations. Mismatched IDs can cause row duplication and unexpected query behavior.

​
Step 6: Combine with Velocity Top Panel

For advanced scenarios, combine a Velocity script in the top panel template with a query factory to filter items based on document-level custom fields:
  1. Use a Velocity script in risksheetTopPanel.vm to extract document custom field values into JavaScript variables.
  2. The query factory function reads these variables and constructs a Lucene query using the document field values.
This approach enables filtering linked items based on metadata that is only available at the document level.
Query factory function signatures and the exact window.risksheet.queryFactories registration mechanism may vary by Risksheet version. Test your implementation in a development environment.

​
Verification

  1. Open a Risksheet document with your query factory configured.
  2. Click on a cell in the column that uses the query factory.
  3. Type at least 3 characters to trigger autocomplete.
  4. Verify that only items matching your factory’s filter criteria appear in the dropdown.
You should now see the autocomplete dropdown showing only filtered results based on your query factory logic, with dependent columns updating their suggestions based on related column values.

​
See Also

Support TicketsSource Code
  • AppConfig.ts
  • MultiItemLinkEditor.ts
  • TextEditor.ts
  • CellEditorFormatter.ts
  • QueryBuilder.java