AI Assistant Reference - Nextedy Documentation

Configuration for the in-sheet AI Assistant, in three layers: project context properties that decide whether the button exists, 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 button 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 button and its invitation tooltip appear only while this is `true`. Setting it to `false` hides the button 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, the AI Assistant button 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 toolbar button is clickable only when the status is ok and at least one AI action is defined for the sheet.

Status	Resolved when	Tooltip on the disabled button
`ok`	The plugin is installed and licensed, and a model key is configured	AI Assistant (button 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.

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 assistant’s action list.
`message`	string	—	The instruction the action sends to the model.
`contextSources.row.fields`	map of string to string	—	Fields of the selected row sent as context, as a map of field name to label.
`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	`100`	How many candidates the search may return.
`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.

apply.field is what binds an action to a columnAn action configuration may also carry a scope.columns list, but nothing in Powersheet reads it — the column an action searches, filters and writes against is resolved from apply.field throughout. Setting scope.columns has no effect. The same applies to contextSources.document.fields and contextSources.user.fields: both are accepted by the schema but neither is sent as context. Only row and project reach the model.

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>"

with discover.search.query appended when present. <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>". Whatever the model returns is re-checked against the apply.field column’s own candidate filter, and any recommendation falling outside it is dropped. When every recommendation is dropped, the assistant reports “No suggestions match this column’s allowed values.”

Applying a recommendation

Column cardinality	Effect	Undo stack entry
Many-to-many, one-to-many	Adds a row and links it	Changed link
Scalar reference	Sets the reference on the current row	Set reference

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.

Conversation storage

Aspect	Value
Scope	Per project and per document
Storage key	`ai-conversation-id:<projectId>:<documentPath>`
Refine context	Truncated to 4000 characters
Reset	The New conversation action in the window’s title bar

​Project context properties

​Sheet configuration key

​Availability statuses

​Action configuration

​Globals interpolation

​Candidate query

​Applying a recommendation

​Conversation storage

​See Also

Project context properties

Sheet configuration key

Availability statuses

Action configuration

Globals interpolation

Candidate query

Applying a recommendation

Conversation storage

See Also