Enable the in-sheet AI Assistant for a Nextedy POWERSHEET project, point a sheet at a Nextedy AI action configuration, and define the actions each level of the sheet offers.
The in-sheet AI Assistant is off until two things are in place: the project allows it, and the sheet names an action configuration to load its actions from. This guide covers both, plus the project context properties that decide whether the assistant is shown at all.For what an action is and how a proposal is constrained before a user sees it, see AI Assistant. Every key mentioned here is listed with its default in the AI Assistant reference.
Three boolean properties in the project’s com.polarion.context.properties govern the assistants. All three default to true, so a project that has never set them already allows everything — you only need to edit this file to turn something off.
Removes the AI Assistant — its menu entry, the levels’ sparkle buttons and the panel — from every sheet in the project
nextedy.powersheet.promotions
Hides the disabled entry points, and their invitation tooltip, whenever the assistant’s availability status is not ok
nextedy.powersheet.adminAssistant
Read by the configuration editor, not by the sheet — it governs the Admin AI Assistant
nextedy.powersheet.aiAssistant and nextedy.powersheet.promotions are read from the project configuration and returned to the sheet together with the sheet configuration.
2
Decide what a project shows before the assistant is ready
Until the assistant is ready, the default behaviour is a greyed-out Menu › AI Assistant entry whose tooltip says what is missing: an invitation to get in touch while the Nextedy AI plugin cannot be reached or no model key is configured — licensed or not — and a notice that the license is invalid once a key is configured. If you would rather the entry were not visible at all until then, set nextedy.powersheet.promotions=false.Note the division: promotions applies whenever the availability status is not ok — unlicensed, unreachable, or missing a model key. Once the status is ok the assistant is shown regardless of it, and nextedy.powersheet.aiAssistant=false is the switch that removes it unconditionally.
The sheet loads its actions from a Nextedy AI action configuration, named on the sheet configuration through the assistantConfig key:
assistantConfig: requirements-assistant
Until this key is set, Menu › AI Assistant stays disabled with the tooltip “AI Assistant — configure AI actions for this powersheet to enable it.”, and the Edit AI Actions document menu entry is disabled too.
2
Open Edit AI Actions
With assistantConfig set, the document menu carries an Edit AI Actions entry, shown to users with document administration write permission. It opens the named action configuration for editing in a new tab, in the Nextedy AI configuration editor.The configuration itself is a YAML file in the project’s own repository, under .polarion/nextedy/ai/<name>.yaml — so assistantConfig: requirements-assistant resolves to .polarion/nextedy/ai/requirements-assistant.yaml. You can create it there directly, or through the Nextedy AI file manager scoped to the current project (/polarion/nx_ai/filemanager/index.html?scope=project/<projectId>/), which is also where Edit AI Actions lands when the assistant cannot resolve a direct link to the configuration.
3
Define the actions
Each action describes one job: where it is offered, what context it sends, how it searches Polarion, how it ranks the candidates, and — through apply.field — which column it writes into.actions is a map keyed by action id, not a list. The key is the id the sheet sends back when a reader picks the action, so it has to be unique within the configuration; it is not repeated inside the action body.
globals: domain: >- This is a medical-device requirements project. A good match is a system requirement that is implementable, testable and traceable to the user need.actions: suggest-system-requirements: label: Suggest system requirements message: Propose system requirements that satisfy this user need. scope: columns: - systemRequirements.systemRequirement contextSources: row: fields: title: Title description: Rationale discover: search: maxCandidates: 30 type: systemRequirement query: NOT status.id:rejected keywordPrompt: >- ${globals.domain} Extract search keywords from the user need below. rankPrompt: >- ${globals.domain} Rank the candidates by how completely each one satisfies the user need. output: limit: 5 sortBy: relevance apply: field: systemRequirements.systemRequirement
contextSources.row.fields is a map, not a list: each entry maps a key to the label the model sees it under. A key is first matched against the sheet’s column bindings. A plain field name such as title matches the top-level column bound to it; to send a value from another level of the row, use that column’s binding as the key — systemRequirements.systemRequirement.description: System requirement sends the system requirement’s description, even when the action runs on a design requirement below it. For a key that matches a column, an empty field sends the work item’s id in its place — so on a sheet with a Title column, title sends the id when the title is empty — 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 from the row’s top-level work item and left out when it has no value. Users never see the binding itself — only its label, in the run card’s Show context sent list.apply.field names the column an accepted suggestion is written into, so it must match a column binding on the sheet, not merely a field name. Where the action is offered is a separate decision, made with scope in the next step. The column’s entity type supplies the work item types to search when discover.search.type is absent, and the column’s own candidate filter is what constrains the result.
4
Choose where each action is offered
Users find a level’s actions behind the sparkle button ✦ on that level in the toolbar. Use scope.columns to choose where an action is offered: list the bindings of the columns whose cells should offer it — the columns of the level the action works on, and the column it writes into.
scope.levels is not applied yet: an action that sets it is still offered on every level, so limit an action with scope.columns. Without scope.columns, the action is offered on every column of every level.
Key
Offers the action on
Absent
scope.columns
The listed column bindings
Every column of every level
scope.levels
Not applied yet — the action is offered as if it were absent
Every level
Give each action only the columns where it helps. An action offered everywhere clutters every level’s list.
The actions of the system requirement level, offered from the sparkle button on that level.
5
Share phrases through globals
A phrase several actions share — your domain, a house convention for what a good match looks like — goes in the configuration’s globals block and is referenced from a prompt as ${globals.<key>}. The key names are yours to choose, and the reference is interpolated before the prompt is sent.
6
Check what the action will search
Candidates are fetched with a query built as type:(<types>) AND project.id:"<projectId>", with discover.search.query appended when present. Omit discover.search.type and the work item types are derived from the entity type bound to the apply.field column — which is usually what you want, and keeps the action correct if the data model changes. Name the types explicitly, comma- or space-separated, only when you need to widen or narrow that.If neither the key nor the column resolves a type, the type: clause is dropped and the search covers the whole project.
The column’s own filter still appliesWhatever an action returns is re-checked against the apply.field column’s candidate filter before it is offered, and anything outside it is dropped. 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. Where a Lucene clause can express the column’s document scoping or picker filter, repeat it in discover.search.query, so that the places go to items the column accepts. If users report that an action returns nothing and the assistant says “All N suggestions were filtered out by this column’s allowed values.”, the column’s filter and the action’s search disagree; repeat the column’s constraints in the search, or check them.
Open a powersheet document in the project. Menu › AI Assistant is enabled, and hovering it shows the plain tooltip “AI Assistant” rather than an explanation.
Select a cell on a level an action is offered on. That level in the toolbar shows the sparkle button, and it lists the action.
Opening the panel with that cell selected lists the action under Actions for this cell.
Run an action and open Show context sent on its run card: the fields you configured are listed under their labels.
