Configure the AI Assistant - Nextedy Documentation

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

Prerequisites

The Nextedy AI plugin installed on your Polarion server, with a valid Nextedy AI license
Administration rights on the Polarion project (to edit com.polarion.context.properties)
Document administration write permission, to reach the Edit AI Actions entry from a document
A powersheet document whose sheet configuration you can edit

Enable it for the project

Check the project context properties

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.

nextedy.powersheet.aiAssistant=true
nextedy.powersheet.promotions=true
nextedy.powersheet.adminAssistant=true

Property	Effect when set to `false`
`nextedy.powersheet.aiAssistant`	Removes the AI Assistant button from every sheet in the project
`nextedy.powersheet.promotions`	Hides the disabled button, and its 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.

Decide what an unlicensed project should show

On a project without a valid Nextedy AI license, the default behaviour is a greyed-out sparkle button whose tooltip invites the reader to get in touch. If you would rather it were not visible at all on such a project, 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 button is shown regardless of it, and nextedy.powersheet.aiAssistant=false is the switch that removes it unconditionally.

Point the sheet at an action configuration

Set assistantConfig in the sheet configuration

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, the AI Assistant button 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.

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.

Define the actions

Each action describes one job: what context it sends, how it searches Polarion, how it ranks the candidates, and — through apply.field — which column it is bound to.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.
    contextSources:
      row:
        fields:
          title: Title
          description: Rationale
    discover:
      search:
        maxCandidates: 100
        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 is an entity field name mapped to the label the model sees it under. A field whose value is empty on the current row is left out of the context.apply.field does more than name the write target — it is what binds the action to a column, so it must match a column binding on the sheet, not merely a field name. 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.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.

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. You do not need to reproduce a column’s document scoping or picker filter in discover.search.query — it is already enforced. If users report that an action returns nothing and the assistant says “No suggestions match this column’s allowed values.”, the column’s filter and the action’s search disagree; widen the search or check the column’s constraints.

Verify

Open a powersheet document in the project. The sparkle AI Assistant button is enabled in the sheet toolbar.
Hovering it shows the plain tooltip “AI Assistant” rather than an explanation.
Opening it on an empty conversation lists the actions you defined.
The document menu shows Edit AI Actions, enabled.

Troubleshooting

Symptom	Cause
No sparkle button anywhere in the project	`nextedy.powersheet.aiAssistant=false`, or `nextedy.powersheet.promotions=false` while the availability status is not `ok`
Button greyed, tooltip “…your Nextedy AI license is invalid…”	The Nextedy AI plugin answered the health probe with HTTP 401
Button greyed, tooltip inviting you to get in touch	The Nextedy AI plugin could not be reached, is not installed, or has no model key configured
Button greyed, tooltip “…configure AI actions for this powersheet…”	`assistantConfig` is unset, or the configuration it names defines no actions
Edit AI Actions missing or disabled	You lack document administration write permission, or `assistantConfig` is unset

​Prerequisites

​Enable it for the project

​Point the sheet at an action configuration

​Verify

​Troubleshooting

​See Also

Prerequisites

Enable it for the project

Point the sheet at an action configuration

Verify

Troubleshooting

See Also