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

# Suggestion and Autocomplete API

> Nextedy RISKSHEET provides a suggestion and autocomplete system that delivers real-time field value suggestions, linked work item search, and inline item creation directly within the grid.

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>;
};

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/reference/api/suggestion-api/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=8c8f16d5fdd321cb7776306feb670b41" alt="diagram" style={{ maxWidth: "700px", width: "100%" }} width="700" height="240" data-path="risksheet/diagrams/reference/api/suggestion-api/diagram-1.svg" />
</Frame>

## Text Field Suggestions

When you type in a text column, Risksheet queries the server for existing values used in the same field on other risk items. This makes it easy to reuse terminology and keep the analysis consistent.

### Request Parameters

The autocomplete request from the grid carries the following parameters. They are produced automatically by the editor.

| Parameter | Type    | Default  | Description                                                                 |
| --------- | ------- | -------- | --------------------------------------------------------------------------- |
| `field`   | string  | required | Field identifier to suggest values for                                      |
| `query`   | string  | required | Partial input text to match against                                         |
| `type`    | string  | none     | Work item type filter for type-specific suggestions                         |
| `project` | string  | required | Polarion project identifier (auto-scoped)                                   |
| `limit`   | integer | `50`     | Maximum number of suggestion results returned                               |
| `fuzzy`   | boolean | `true`   | Enable fuzzy matching for approximate searches                              |
| `star`    | boolean | `true`   | Enable wildcard search with `*` characters                                  |
| `all`     | boolean | `false`  | Require all keywords to match (AND logic) instead of any keyword (OR logic) |

<Tip title="Enabling text field autocomplete">
  Text field autocomplete is controlled by the `global.suggestTextFields` property in the sheet configuration (default: `true`). When enabled, the server queries existing field values and suggests matching entries as you type.
</Tip>

### Search Behavior

| Feature              | Description                                                                          |
| -------------------- | ------------------------------------------------------------------------------------ |
| Fuzzy search         | Matches values even with minor typos or spelling variations                          |
| Wildcard search      | Use `*` as a wildcard to match partial text (e.g. `*brake*` matches `Brake Failure`) |
| Keyword filtering    | When `all` is `true`, all search terms must appear in results (AND logic)            |
| Project scoping      | Suggestions are automatically scoped to the current project                          |
| Column-specific      | Each column provides suggestions tailored to its field type                          |
| Type-based filtering | Suggestions vary based on the work item type being edited                            |

## Project-Level Configuration

Several aspects of suggestion behavior are configured per Polarion project under **Administration > Nextedy Risksheet > Setup**. These defaults apply across every Risksheet document in the project unless overridden in the sheet configuration.

| Property                                         | Type    | Default | Description                                                              |
| ------------------------------------------------ | ------- | ------- | ------------------------------------------------------------------------ |
| `nextedy.risksheet.isSuggesterKeywordsMandatory` | boolean | `false` | When enabled, you must provide keywords when searching for items to link |
| `nextedy.risksheet.isSuggesterFuzzySearching`    | boolean | `true`  | Enables fuzzy matching in the item suggester                             |
| Suggester result limit                           | integer | `20`    | Maximum number of suggestions shown in dropdowns                         |
| `nextedy.risksheet.isSuggesterWildcardSearching` | boolean | `true`  | Enables wildcard searching with `*` and `?` characters                   |
| All-field search                                 | boolean | `false` | Searches all fields of linked items instead of just the primary fields   |

<Info title="Verify in application">
  Project-level suggestion settings are configured in the Polarion project administration. Contact your administrator to adjust these defaults.
</Info>

## Link Column Autocomplete

### Item Link Columns

Link columns (such as `itemLink` and `multiItemLink`) use the server's search interface to find linkable work items. All data comes from Polarion under the current user's authorization — Risksheet does not cache a separate copy.

| Feature              | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| Minimum query length | 3 characters required before the search executes                      |
| Search method        | Substring match on work item ID, title, and configured fields         |
| Dropdown arrow       | Click to browse all available items or toggle the suggestion dropdown |
| Empty field prompt   | Shows "Start typing" when clicking the dropdown on an empty field     |
| `SEARCH_ALL` token   | Special query that retrieves the full item list (when supported)      |

### Auto-Selection

When autocomplete returns exactly one matching item for non-task columns, the system automatically selects it. This speeds up data entry for unambiguous searches.

### Inline Item Creation

When `canCreate` is `true` on a link column, you can create a new linked work item directly from the autocomplete dropdown. The new item is created with the typed text as its title.

| Property    | Type    | Default | Description                                                       |
| ----------- | ------- | ------- | ----------------------------------------------------------------- |
| `canCreate` | boolean | `true`  | Enables the "Add new \<type>" option in the autocomplete dropdown |

A global switch also exists on the downstream task data type: when `dataTypes.task.canCreate` is set to `false`, no new task items can be created from any column — users can only link to existing items from a library.

## Multi-Item Link Editor

The multi-item link editor extends the autocomplete system for columns that reference multiple linked work items.

| Feature              | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| Minimum query length | 3 characters required to trigger the search                          |
| Duplicate prevention | Selecting an already-linked item shows a toast notification          |
| Local changes        | Newly created items appear in search results before saving           |
| Change tracking      | A `changed` flag enables dirty-state indicators                      |
| Custom filtering     | A `queryFactory` applies context-aware filters to narrow suggestions |

## Query Factory Integration

Columns can use a `queryFactory` to apply a custom Lucene query to autocomplete results. The factory function receives an `info` object with context data and returns a Lucene query string that filters which work items appear in the dropdown.

```yaml theme={null}
columns:
  - id: linkedReqs
    header: Requirements
    type: multiItemLink
    bindings: linkedReqs
    typeProperties:
      linkRole: relates_to
      linkTypes: requirement
      queryFactory: filterByProject
```

Query factories are defined in the top-level `queryFactories` section of the sheet configuration and enable context-aware filtering such as:

* Restricting items to a specific project or document
* Filtering by work item state, status, or custom field value
* Reading values from the top panel (for example, a dropdown the user has selected) and folding them into the query

See [Query Syntax](/risksheet/reference/query-syntax) for the supported filter expressions.

## Suggestion Validation

Suggested items can be validated through column configuration. The grid uses the result to decide whether a suggestion is offered, accepted, or marked as invalid.

| Validation             | Behavior                                                             |
| ---------------------- | -------------------------------------------------------------------- |
| Valid suggestion       | Displayed in the dropdown as normal                                  |
| Invalid suggestion     | Filtered out of the results                                          |
| Invalid user selection | The cell is marked with the `cell-invalid` CSS class (red highlight) |

## Local Changes Integration

Autocomplete results include items created in the current session but not yet saved to Polarion.

| Source        | Behavior                                         |
| ------------- | ------------------------------------------------ |
| Server data   | Queried from the Polarion work item store        |
| Local changes | Merged in from the in-memory session state       |
| Combined      | Both sources are displayed in a unified dropdown |

This lets you link to newly created items immediately, without first saving the document.

## Complete Example

```yaml theme={null}
global:
  suggestTextFields: true
columns:
  - id: failureMode
    header: Failure Mode
    bindings: title
    type: text
  - id: linkedReqs
    header: Requirements
    bindings: linkedReqs
    type: multiItemLink
    canCreate: true
    typeProperties:
      linkRole: relates_to
      linkTypes: requirement
      queryFactory: filterByProject
  - id: mitigationTask
    header: Mitigation
    bindings: task.id
    type: taskLink
```

In this configuration:

* The `failureMode` text column shows autocomplete suggestions from existing failure mode values used in the same project.
* The `linkedReqs` multi-item link column searches for `requirement` work items with a custom query filter and allows inline creation.
* The `mitigationTask` task link column provides autocomplete with uniqueness validation to prevent duplicate task assignments.

## Related Pages

* [Multi-Item Link Columns](/risksheet/reference/columns/multi-item-link-columns) — multi-item link column configuration
* [Item Link Columns](/risksheet/reference/columns/item-link-columns) — single item link column reference
* [Task Link Columns](/risksheet/reference/columns/task-link-columns) — task link column configuration
* [Query Syntax](/risksheet/reference/query-syntax) — query filter syntax reference

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