Administration Guide

Portal AI Assistant

On this page

The Self Service Portal has an AI Assistant. You configure it in the Admin Center, on the AI Assistant tab of a Self Service Portal instance. For the AI features as a whole, see AI Features; for the portal assistant as users see it, see AI Assistant.

Before you begin

  • The portal assistant requires globally enabled AI features and a configured AI integration, including the API key.
  • The SSP AI Assistant log requires the log-management permission.

In the Admin Center

Configure the portal AI Assistant

A Self Service Portal instance's AI Assistant tab starts with the Enable AI Assistant checkbox and a readiness banner, followed by four sub-tabs: General, Skills, Commands and Placeholders. Each sub-tab has its own address, so a direct link opens that sub-tab without visiting General first.

The banner reads "AI Assistant is currently unavailable" when AI features are not enabled or no API key is configured, and "AI Assistant is ready to use" otherwise. Both messages add "AI Assistant requires globally enabled AI features and relies on a properly configured AI integration, including the API key." and a Configure AI integration link.

General

  1. Select Enable AI Assistant.
  2. To use your own system prompt, select Enable system prompt editing and edit the prompt. The checkbox is disabled until Enable AI Assistant is selected, and the prompt field until both are selected.
  3. Under Incident Create Action, select in Action the workflow action the assistant uses to create a ticket ("Select a workflow action for the assistant to use as the ticket constructor. This avoids asking the user when multiple actions exist."). The list offers the enabled Self Service Portal create actions of the Incident class. The section is hidden when no such action exists, and the list stays available while Enable AI Assistant is cleared.
  4. Save the page. The portal picks up Enable AI Assistant and the settings saved with the page without a restart.

Enable system prompt editing is selected when the page opens only if a custom prompt is stored; otherwise the field shows the default prompt, which begins "You are a helpful AI assistant for the 'Self Service Portal'." and carries the current-user name and locale placeholders. Clearing the checkbox, or selecting it while the field is blank, replaces the text with that default; selecting it over existing custom text leaves the text as it is. Restore Default is disabled when the field already equals the default and whenever the field is disabled. A custom prompt is stored only when editing is on and the text is neither blank nor equal to the default.

This prompt is not all the portal sends to the AI. The portal follows it with fixed instructions of its own, such as the user's local time, how to navigate the portal, how to handle a password change and a reminder to ask for feedback, and, last, the instructions of the enabled skills.

In the portal, the action selected under Incident Create Action is the only one the assistant uses to create a ticket, so the assistant does not ask the user to choose one. When no action is selected, the assistant uses the create actions the portal offers for tickets: it takes the only one at once, or lets the user choose when there are several. When the selected action is not among them, the assistant has no action to use and shows an error message.

Skills

The Skills table shows Display name, Description, System and Enabled. The skill editor has Display name (required), Skill ID (required, and locked once the skill exists), Description, Instructions and Required modules; for an existing skill it also has a read-only System box and an Enabled box. For a system skill, the text fields and the module list are disabled.

When you add a skill, Skill ID fills in from Display name: the display name in lowercase, with its runs of letters and digits joined by hyphens. It stops following Display name once you edit Skill ID yourself. Skill ID accepts only lowercase letters, digits and hyphens, in groups of letters and digits separated by single hyphens, and no other skill can use the same ID. The skill form checks its fields as you type; its messages are "Name must be in kebab-case format (e.g. your-custom-name)" and "Another skill already uses this ID".

An enabled skill whose required module or embedding is missing shows a warning tooltip naming what is missing.

In a new database created with the Default Workflow (see Default Workflow Configuration), the portal has five skills, all of them system skills: equipment-reservation, global-search, kb-search, service-request and ticket-creation. A database upgraded from an earlier version need not have these skills.

Commands

The Commands editor has Display name (required), Display name localization key, AI prompt (required), Prompt localization key and Required skills; for an existing command it also has a read-only System box and an Enabled box. The fields of a system command are disabled. The table's Enabled column shows a check mark. An enabled command that requires an unavailable skill shows a warning tooltip that lists the unavailable skills and adds "See Skills tab".

How skill and command changes are saved

  • Enabled in a skill or command editor applies to this portal instance only and is stored when you save the page.
  • Ok in the editor sends its other fields at once to the shared skill or command, which changes it for every portal instance.
  • A skill or command you add is not a system one. A system skill or command has no delete icon. Deleting a skill also removes it from every portal instance's list of disabled skills and from the Required skills of every command; deleting a command removes it from every instance's list of disabled commands.
  • Ok in a command editor also clears the command's internal name, even for a system command whose fields are disabled. The portal uses that name only to order its commands.

Placeholders

The Placeholders sub-tab is a reference with nothing to edit. It has three sections, each a table of placeholders and their descriptions:

  • a user context section with {{$currentUser.name}} and {{$currentUser.locale}};
  • a skills section with one placeholder for each of the five built-in skills;
  • a tools section with one placeholder for each of the ten built-in tools.

The tables are fixed: they do not change with the skills and commands you configure.

The five built-in skills are kb-search, ticket-creation, equipment-reservation, service-request and global-search. The ten built-in tools are navigate-to-page, go-to-object, global-search, knowledge-base-vector-search, get-ticket-constructor, create-ticket, find-equipment, reserve-equipment, find-service and create-service-request.

The portal replaces the placeholders as follows:

  • {{$currentUser.name}} becomes the user's name, and {{$currentUser.locale}} the language of the portal's interface.
  • {{$skill.<id>}} becomes '<id>' skill and {{$tool.<id>}} becomes '<id>' tool, but only when the id is one of the built-in skills or tools. Any other {{$...}} token stays as written.
  • Placeholders are replaced in a command's AI prompt, in the system prompt and in skill instructions. A command with a Prompt localization key sends the translation of that key instead of its AI prompt, and placeholders in a translation are not replaced.

Apart from navigate-to-page and go-to-object, the assistant can use a tool only when an enabled skill names it with a {{$tool.<id>}} placeholder in its Instructions.

Review the portal AI Assistant log

Open Logs > SSP AI Assistant (see Logs). The list shows one record per portal conversation, updated as the conversation continues, newest first, in the columns Run Date, Title, User and Was helpful ("Helpful", "Not helpful" or "Unknown"). User shows Anonymous when the user is not known. A conversation is logged once it holds a message from the user, and only while AI features and the portal assistant are enabled. The knowledge base searches of an AI control on a portal action form are not logged.

Click a record's Run Date to open its details, titled with the conversation title or "SSP AI Assistant Log Details". The details show Run Date: and Was helpful: above two tabs:

  • Chat shows the conversation's messages from the user and the assistant that hold text, with the user's messages on the right and the assistant's on the left; other entries of the transcript are not shown. It lists under References the knowledge base links the assistant's searches returned. With nothing to show, it reads "No messages found.".
  • Relevant Search loads when you open it and lists the knowledge base searches the conversation ran, newest first, in the columns Search Date, Results and Has Error (Yes or No). Click a search date to open Vector Search Log Details, which repeats the three values and shows Data:. The data holds the date, user, prompt, provider type, completion and embedding models, search query, vector search count and one line per retrieved article with its relevance, marked "(access denied)" when the article failed the Knowledge Base class filter or "(skipped)" when it fell beyond the search's result limit, and ends with the error when there was one, for example "AI feature is not configured or embeddings are not enabled.", "Knowledge base module is not enabled or user is not authenticated." or "Search query is empty.". With no data it reads "No data available.".

Download JSON saves the conversation transcript as ssp-ai-chat-log-<id>.json. Deleting records requires a separate log-management permission.

The log and its Relevant Search table each have a Settings form for retention. When no value is stored, the forms show 7 days. In Alloy Navigator Cloud, the retention controls are unavailable and both logs are kept for 7 days.

  • AI Features - the AI features the portal assistant depends on.
  • AI Assistant - the portal assistant as users see it.