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. Setting up the model connection, the key and the Nextedy AI license step by step is covered in Install Nextedy AI.

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 shows the disabled sparkle button while the assistant is not ready — no package, no model key, or no valid license. Has no effect once all three are in place.

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

FMEA Example

This action file proposes mitigation tasks on a design FMEA sheet. The sheet links each row’s failure mode and cause to tasks in a task-link column with the id task, and selects the file with assistantConfig: fmea_actions.

fmea_actions.yaml

globals:
  systemContext: >
    System under analysis: the 09.02.01 Catalytic Converter Assembly of the
    vehicle exhaust system (model MY21_Gxy9_2-8). The assembly comprises the
    catalyst substrate and its wash coat (precious-metal loading, ceria and
    scavenger content such as NiO), the internal cones and insulation, and the
    canning and connection into the exhaust system. Its function is to convert
    engine-out emissions within the calibrated air/fuel and temperature window
    without releasing secondary emissions such as H2S, which the customer
    perceives as a rotten-egg (sulfur) odour. Design is governed by the System
    Design Specification (SDS), engine and catalyst calibration, and design
    verification methods (DVM) and engineering test procedures (CETP),
    including emissions and objective / subjective H2S odour tests. Field
    knowledge comes from Global 8D (G8D) reports, Technical Service Bulletins
    (TSB) and campaign prevention reviews.

  keywordRules: >
    Avoid generic terms like 'failure', 'issue', 'improve' or 'task' alone.
    Use precise exhaust and catalyst engineering terminology - H2S release,
    sulfur storage and release, wash coat formulation, NiO scavenger, ceria
    loading, rich A/F excursion, catalyst temperature, canister purge,
    calibration, SDS requirement, DVM, CETP test procedure - and name the work
    to be done (calibration release, SDS or specification update, wash coat or
    design change, test procedure update, test sign-off, verification on
    vehicle) explicitly.

actions:
  find-tasks:
    label: "📋 Find Tasks"
    message: "Suggest mitigation tasks for this failure mode and cause"

    scope:
      columns:
        - task
        - taskTitle
        - taskStatus

    contextSources:
      row:
        fields:
          item_title: "Item / Function (system element or requirement)"
          failureMode: "Failure Mode"
          effects: "Effect(s) of Failure on the customer"
          causes: "Cause(s) of Failure"
          controlsPrevention: "Current Prevention Controls"
          controlsDetection: "Current Detection Controls"
          sev: "Severity (1-10)"
          occ: "Occurrence (1-10)"
          det: "Detection (1-10)"
          rpn: "RPN (Severity x Occurrence x Detection)"

    discover:
      search:
        maxCandidates: 30

      keywordPrompt: |
        You are assisting with an FMEA in a Risksheet. Each row links
        an item (a system element such as the exhaust system or internal
        cones & insulation, or a system / software requirement) to a failure
        mode, its effects on the customer, and its causes, with the current
        prevention and detection controls and a Severity / Occurrence /
        Detection ranking.

        Generate keywords naming the mitigation tasks that would lower the
        Occurrence or Detection ranking for this cause: calibration changes
        and releases (A/F control, catalyst temperature, canister purge),
        SDS or specification updates, wash coat and catalyst design changes,
        new or updated DVM / CETP test procedures and their sign-off,
        replacement of subjective tests by objective ones, and lessons from
        G8D or TSB records. Prefer tasks that remove the cause over tasks that
        only improve detection, and do not restate a task already linked to
        the row.
        ${globals.systemContext}
        ${globals.keywordRules}

      rankPrompt: |
        Select tasks whose completion most directly mitigates this failure
        mode at the stated cause and would lower its Occurrence or Detection
        ranking, so the final RPN drops below the initial one. Prefer tasks
        that act on the cause (calibration, specification or design change),
        then tasks that add or strengthen verification (objective test
        procedures, test sign-off), over general reviews or documentation.
        A task written for a different cause of the same failure mode fits
        only if it clearly addresses this cause too. If none of the
        candidates applies, return none rather than the closest match.

    output:
      limit: 5
      sortBy: relevance

    apply:
      field: task

What this example shows:

Part	What it does here
Two `globals`	`systemContext` describes the system under analysis once; `keywordRules` sets the vocabulary the keywords must use. Both are placed into `keywordPrompt` through `${globals.<key>}`.
`scope.columns`	Offers the action only on the task columns — the link column and the task title and status shown beside it — so it never appears on the failure mode or cause the row starts from.
`contextSources.row.fields`	Sends the whole FMEA row, including the current controls and the Severity, Occurrence, Detection and RPN values, so the ranking can favour tasks that lower Occurrence or Detection.
`rankPrompt`	Puts tasks that remove the cause ahead of tasks that only improve detection, and lets the assistant return nothing rather than a weak match.
`apply.field: task`	Writes the chosen task into the `task` column. The task types the action can propose come from that column’s own configuration, so the file names no work-item type.

To use the example in your own project, replace the column ids with the ids of your sheet’s columns, and rewrite systemContext and keywordRules for your own system — the prompts are only as useful as the description they are given.

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

FMEA 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

​FMEA 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

FMEA Example

See Also