AI Action Configuration

AI Assistant actions are defined in a YAML file held in Polarion’s configuration repository. This page is the field-by-field reference. For how the pieces fit together, see Configure the AI Assistant.

File location and resolution

Action files live in the configuration folder .polarion/nextedy/ai/ — either under a project, or globally so that several projects can share one file. Administration → Nextedy AI → AI Assistant Actions lists the files found there. A sheet selects its file through the assistantConfig property in the global block of the Risksheet configuration:

global:
  assistantConfig: actions

Form	Resolves to
`actions`	`actions.yaml` in the current project’s `.polarion/nextedy/ai/`
`actions.yaml`	the same file — the extension is optional
`OtherProject/actions`	`actions.yaml` in another project’s folder

When assistantConfig is unset, the assistant offers no actions.

File structure

The file has exactly two top-level keys, and both are optional.

globals:
  <key>: <string>

actions:
  <action-id>:
    ...

Key	Type	Description
`globals`	map of string to string	Reusable strings, substituted into prompts through `${globals.<key>}`.
`actions`	map of action id to action	The actions offered on a sheet. The map key is the action id.

Action fields

Required

Field	Type	Description
`label`	string	The entry text in the cell context menu and in the assistant panel’s action list. Shown verbatim.
`message`	string	The prompt title displayed above the results, describing to the analyst what was asked.

The action id is the map key, not a field inside the action body.

`scope`

Field	Type	Default	Description
`scope.columns`	list of column ids	absent	Restricts the action to these columns in the cell context menu. When absent, the action is offered on every column.

scope never filters the assistant panel’s own list — that always shows every configured action for the sheet.

`contextSources`

Field	Type	Default	Description
`contextSources.row.fields`	map of Risksheet column id to label	absent	Sheet fields to send with the action. The key is the sheet field id; the value is the label the assistant sees that value under. Fields with no value on the row are skipped.
`contextSources.document.fields`	map of document field id to label	absent	Document fields to send with the action. The key is the document field id; the value is the label the assistant sees that value under.
`contextSources.project.fields`	map of context property name field to label	absent	Context property values to send with the action. The key is the property name (whether project- or global-level); the value is the label the assistant sees that value under.

contextSources:
  row:
    fields:
      item_title: "Characteristic"
      failureMode: "Failure Mode"
      effectOfFailure: "Effect(s) of Failure"
      causes: "Cause(s) of Failure"
  document:
    fields:
      name: "Document name"
      projectName: "Project"
      customFields.riskLevel: "Risk level"
  project:
    fields:
      ai.context.industry: "Industry domain"
      ai.context.standards: "Applicable standards"

The labels are prose read by the assistant, not identifiers. "Hazardous situation" describes the value usefully; "hs_col_2" does not. This is the main lever over how well an action performs.An action sends the values you map here together with the selected row’s id and title. A project script can add further values at run time through the customAiContext hook — see Customize the Top Panel.Other contextSources blocks exist for context beyond the current row; they are not covered on this page.

`discover`

Field	Type	Default	Description
`discover.keywordPrompt`	string	absent	Tells the assistant what to look for. Describe the kind of item the action should propose.
`discover.rankPrompt`	string	absent	Tells the assistant which of the items it finds to propose, and on what grounds. When absent, a built-in default applies.
`discover.search.maxCandidates`	integer	none	How many work items an action may consider. Always set it explicitly — an action without it proposes nothing.

30 is the highest value maxCandidates accepts. A larger number behaves the same as 30.

Both prompts support ${globals.<key>} substitution. An unknown key resolves to an empty string.

`output`

Field	Type	Default	Description
`output.limit`	integer	none	How many recommendations to ask for at most. Omit it and the assistant decides how many to offer.
`output.sortBy`	string	absent	How the recommendations should be ordered, for example `relevance`.

Both are asked of the assistant rather than enforced — a result may not honour them exactly.

`apply`

Field	Type	Default	Description
`apply.field`	column id	absent	The sheet column a recommendation is written into. With no `apply.field`, nothing can be applied.

apply.field does double duty: it also determines which work-item types an action can propose. Those types come from the column’s own configuration — the task data type for a task-link column, the column’s link types for an item-link column — so a recommendation is always something the column can legitimately hold.

Target column type	Applying to an empty cell	Applying to a filled cell
Task link	Written into the current row, undoable.	A new task row is created and the link written there.
Item link	Written into the current row, undoable.	A new row is added at the level owning the column.
Multi item link	Added to the cell.	Appended to the existing values.

What a recommendation contains

Field	Description
`id`	The work-item id. A suggestion that does not match a real work item is discarded.
`title`	Always the title Polarion holds, so an invented title cannot reach the analyst.
`description`	A one-sentence rationale for the match.
`source`	The origin of the item.

Context properties

All of these are Polarion context properties. The nextedy.ai.* properties are read from the global context only and cannot be varied per project.

Model connection

Property	Default	Description
`nextedy.ai.baseUrl`	`https://api.openai.com/v1`	Base URL of the model API.
`nextedy.ai.model`	`gpt-4o-mini`	Model identifier sent with each request.

The API key is taken from the first of these that holds a value: the Polarion User Account Vault credential nextedy-openai-apikey, the JVM system property nextedy-openai-apikey, then the environment variable OPENAI_API_KEY. If none resolves, the assistant reports itself unavailable. All three are re-read per request, so a change applies to the next action without restarting Polarion.

Feature switches

Property	Default	Description
`nextedy.risksheet.aiAssistant`	`true`	The in-sheet AI Assistant in Risksheet documents. `false` removes it from that project — no toolbar button and no cell-menu entries.
`nextedy.risksheet.adminAssistant`	`true`	The assistant in the Risksheet configuration editor.
`nextedy.risksheet.promotions`	`true`	Whether the toolbar advertises the assistant on installations not licensed for it. Only has an effect while unlicensed.

Prompt overrides

Each replaces one of the assistant’s built-in instructions, for every action. Leave unset to keep the default.

Property	Replaces
`nextedy.ai.keywordPrompt`	The built-in counterpart of an action’s `discover.keywordPrompt`.
`nextedy.ai.processorPrompt`	The built-in counterpart of `discover.rankPrompt`, used when an action sets none.
`nextedy.ai.relevancePrompt`	The built-in wording that keeps loosely related items out of the results.
`nextedy.ai.jsonPrompt`	The built-in wording that fixes the shape of the assistant’s answer. Changing it can stop results appearing.

Logging

Property	Default	Description
`nextedy.ai.telemetry`	`false`	Logs action requests and results at INFO. Safe in production.

Warnings and errors are logged regardless of both switches.

Complete example

actions.yaml

globals:
  systemContext: "An infusion pump delivering medication intravenously in a clinical setting."

actions:
  find-harms:
    label: "Find Harms"
    message: "Suggest potential harms for this hazardous situation"
    scope:
      columns:
        - hazardousSituation
        - hazard_title
    contextSources:
      row:
        fields:
          useStep: "Use step"
          hazardousSituation: "Hazardous situation"
          hazard_title: "Hazard"
    discover:
      keywordPrompt: >
        ${globals.systemContext}
        Generate keywords naming the types of harm a patient or operator could suffer
        as a consequence of the hazardous situation described in the context.
      rankPrompt: >
        Select the harms that could plausibly result from this hazardous situation.
        If none of the candidates applies, return none rather than the closest match.
      search:
        maxCandidates: 30
    output:
      limit: 5
      sortBy: "relevance"
    apply:
      field: harm

  find-risk-controls:
    label: "Find Risk Control Measures"
    message: "Suggest existing risk control measures for this failure mode"
    scope:
      columns:
        - failureMode
        - cause
    contextSources:
      row:
        fields:
          failureMode: "Failure mode"
          cause: "Cause"
          effect: "Effect"
    discover:
      keywordPrompt: >
        ${globals.systemContext}
        Generate keywords naming control measures that would reduce or detect the
        failure mode described in the context.
      rankPrompt: >
        Select the control measures that address this specific failure mode and cause.
        Return none rather than a generic measure.
      search:
        maxCandidates: 30
    output:
      limit: 5
    apply:
      field: mitigationTask

FAQ

File location and resolution

File structure

Action fields

Required

`scope`

`contextSources`

`discover`

`output`

`apply`

What a recommendation contains

Context properties

Model connection

Feature switches

Prompt overrides

Logging

Complete example

See Also

​File location and resolution

​File structure

​Action fields

​Required

​scope

​contextSources

​discover

​output

​apply

​What a recommendation contains

​Context properties

​Model connection

​Feature switches

​Prompt overrides

​Logging

​Complete example

​See Also

File location and resolution

File structure

Action fields

Required

`scope`

`contextSources`

`discover`

`output`

`apply`

What a recommendation contains

Context properties

Model connection

Feature switches

Prompt overrides

Logging

Complete example

See Also