AI Assistant Reference - Nextedy Documentation

Configuration for the in-sheet AI Assistant, in three layers: project context properties that decide whether the assistant is shown, one sheet configuration key that points at an action configuration, and the action configuration itself. For the task-oriented walkthrough, see Configure the AI Assistant.

Project context properties

Set in the project’s com.polarion.context.properties. All are booleans and all default to true.

Property	Type	Default	Description
`nextedy.powersheet.aiAssistant`	boolean	`true`	When `false`, removes the AI Assistant — the Menu › AI Assistant entry, the levels’ sparkle buttons and the panel — from every sheet in the project.
`nextedy.powersheet.promotions`	boolean	`true`	Whenever the availability status is not `ok` — the plugin is unlicensed, unreachable, or has no model key — the disabled entry points and their invitation tooltip appear only while this is `true`. Setting it to `false` hides them in all of those cases.
`nextedy.powersheet.adminAssistant`	boolean	`true`	Read by the configuration editor rather than by the sheet. Governs the Admin AI Assistant.

nextedy.powersheet.aiAssistant and nextedy.powersheet.promotions are read from the project configuration and returned to the client together with the sheet configuration JSON.

Sheet configuration key

Key	Type	Default	Description
`assistantConfig`	string	(unset)	Names the Nextedy AI action configuration the sheet loads its actions from. While unset, Menu › AI Assistant and the Edit AI Actions document menu entry are both disabled.

assistantConfig: requirements-assistant

Availability statuses

Powersheet probes the Nextedy AI plugin’s health endpoint for the current project and resolves one of three statuses. The entry points — Menu › AI Assistant and the levels’ sparkle buttons — are usable only when the status is ok and at least one AI action is defined for the sheet.

Status	Resolved when	Tooltip on the disabled entry points
`ok`	The plugin is installed and licensed, and a model key is configured	AI Assistant (enabled)
`unauthorized`	The plugin is installed but answered with HTTP 401 — the Nextedy AI license is invalid	AI Assistant — your Nextedy AI license is invalid. Contact your administrator.
`unavailable`	The plugin is not installed or could not be reached, or no model key is configured	This could be your Powersheet AI Assistant, helping you fill sheets faster by surfacing relevant items and justification. Want to see it in action? Contact us. (a promotional message, not an error)

When the status is ok but the sheet defines no actions, the tooltip reads AI Assistant — configure AI actions for this powersheet to enable it. Installing the plugin and its license, and configuring the model key, are covered in Install Nextedy AI.

Action configuration

An action configuration is a YAML file in the project’s own repository at .polarion/nextedy/ai/<name>.yaml, where <name> is the value of assistantConfig. It holds a globals block and an actions block. actions is a map keyed by action id — the key identifies the action in the request the sheet sends, and is not repeated inside the action body. Each action supports the following keys.

Key	Type	Default	Description
`label`	string	—	The name shown in the menu of the level’s sparkle button and in the panel’s action list.
`message`	string	—	The instruction the action sends to the model.
`scope.levels`	list of numbers	—	Not applied yet: an action that sets it is offered as if it were absent, on every level. Limit an action with `scope.columns` instead.
`scope.columns`	list of strings	(every column)	The column bindings the action is offered on, for example `systemRequirements.systemRequirement`. Absent, the action is offered on every column. An action is listed first for a column named here or in `apply.field`.
`contextSources.row.fields`	map of string to string	—	Values from the row sent as context, as a map of key to label. A key that matches a column binding on the sheet — `systemRequirements.systemRequirement.description`, or a plain `title` when a top-level column is bound to it — is read from the work item at that column’s level, so any level of the row can contribute; when that field has no value, or the column is a link or reference column, the id of the work item at that level is sent instead, and the key is left out only when the row has no work item at that level. A key that matches no column is read as a field of the row’s top-level work item and is left out when it has no value. The label is what the model and the Show context sent list show.
`contextSources.project.fields`	map of string to string	—	Fields of the project sent as context, as a map of field name to label.
`discover.search.maxCandidates`	number	`30` when `discover.search` is absent	How many candidates the search returns, at most `30` — a larger value behaves as `30`. Set it in every `discover.search` block: a block without it searches for a single candidate.
`discover.search.type`	string	derived	Polarion work item types to search, comma- or space-separated. When absent, the types are derived from the entity type bound to the column named by `apply.field`.
`discover.search.query`	string	(none)	An extra Lucene clause appended to the candidate query.
`discover.keywordPrompt`	string	—	Instructs the model how to derive search keywords. Supports `${globals.<key>}`.
`discover.rankPrompt`	string	—	Instructs the model how to rank the candidates. Supports `${globals.<key>}`.
`output.limit`	number	—	Passed to the model as Maximum number of items to select.
`output.sortBy`	string	—	Passed to the model as Sort candidates by.
`apply.field`	string	—	The column binding an accepted recommendation is written to — matched against the sheet’s column bindings, so it is a binding expression such as `systemRequirements.systemRequirement`, not a bare field name. This is also the column the action’s Polarion types are derived from and whose candidate filter constrains the result.

scope decides where an action is offered, apply.field where it writesThe column an action searches, filters and writes against is resolved from apply.field; scope.columns only decides which columns offer the action. An action without apply.field is still offered, but only discovers: its suggestions carry no Apply, and its run card reads Suggestions for <ID> — nothing is written. An apply.field that matches no column on the sheet leaves the action offered, and its run card reads For <ID> — the target column is not on this sheet.contextSources.document.fields and contextSources.user.fields are accepted by the schema but neither is sent as context. Only row and project reach the model.

The AI Assistant panel beside a design requirement row, with the run card expanded to list Customer requirement, System requirement and Subsystem requirement values sent as context. — The run card's context list for an action whose row fields name columns on three levels of the sheet.

Globals interpolation

${globals.<key>} references inside discover.keywordPrompt and discover.rankPrompt are replaced from the configuration’s globals block before the prompt is sent. The globals block is a flat map of string values whose key names you choose; a reference to a key the block does not define resolves to an empty string. Write a phrase once in globals and refer to it as ${globals.<key>} from every prompt that needs it, rather than repeating it in each action.

Candidate query

The query sent to Polarion is built as:

type:(<types>) AND project.id:"<projectId>" AND (<discover.search.query>)

with the last clause only when discover.search.query is present. When the target cell already holds work items, they are excluded: the query becomes (<query>) AND NOT (id:(<ids>)). The cell is read as the sheet shows it when the action runs, saved or not: a link removed without saving no longer excludes its item, and a link added without saving does. <types> comes from discover.search.type, or is derived from the entity type bound to the apply.field column when that key is absent. When neither resolves any type, the type: clause is omitted and the query is just project.id:"<projectId>", followed by any discover.search.query. Whatever the model returns is re-checked against the apply.field column’s own candidate filter, and any recommendation falling outside it is dropped; items already linked in the target cell are left out too. The run card counts the dropped ones as N dropped (not allowed here). When nothing is left, the assistant reports All N suggestions were filtered out by this column’s allowed values., or No new items found — everything suggested is already linked. when everything was already linked. The search does not apply that filter itself. It returns at most 30 candidates, and those the column would refuse still take up places among them, so an action can come back empty while items the column accepts exist. Where a Lucene clause can express the column’s constraints — its document scope, say — repeat them in discover.search.query.

Applying a recommendation

A recommendation is written into the apply.field column, on the row the action ran on — not on the row selected when Apply is clicked.

Target column	Effect	Undo stack entry
A column that introduces a level — its linked items are that level’s rows	Adds a row at that level, linked to the work item one level up on the row	Changed link
Single reference	Sets the reference; one recommendation at a time	Set reference
Multi-item cell on the row	Not supported yet; the panel reports The plan could not be executed.	—

The linked child row is inserted under every rendered instance of the parent the action ran against — deduplicated by upstream id — not only the one instance in view. This applies to every cardinality. Editing a link cell by hand is undoable through the same Changed link entry. Every write stays in the sheet’s change buffer, marked Unsaved in the panel, until the sheet is saved.

Refusal shown in the panel	Cause
The sheet is read-only — applying is disabled.	The sheet cannot be edited
The target column is read-only.	The `apply.field` column is read-only
The row has no entity at the target level yet — add it first.	The row has no work item at the level the action writes on
<IDs> is already linked in this cell. / are already linked in this cell.	The recommendation is already in the target cell
No column on this sheet matches the action’s target.	`apply.field` names no column of this sheet
This column holds a single reference — select one suggestion.	More than one recommendation was applied to a single-reference column at once

Conversation storage

Aspect	Value
Scope	Per project and per document
Storage key	`ai-conversation-id:<projectId>:<documentPath>`
New conversation	Started by every action run; Refine continues the current one
Refine context	The first 4000 characters of the conversation
Reset	New chat in the panel header
Panel width	Remembered by the browser; 384 px by default, at least 280 px

​Project context properties

​Sheet configuration key

​Availability statuses

​Action configuration

​Globals interpolation

​Candidate query

​Applying a recommendation

​Conversation storage

​See Also