Administration Guide

AI Knowledge Index

On this page

AI in Alloy Navigator can answer from your own Incidents and Knowledge Base articles. For this, Alloy Navigator keeps a vector index of Incidents and articles. Of the ticket classes, only Incidents are indexed. The index is built by a scheduled task, AI Search Index Maintenance in the supplied configuration; see The index task in the supplied configuration. You start and stop the task from the AI Configuration page of the Admin Center, where you also follow the indexing progress. In the Settings App, you enable, run, and follow the task under Services > Scheduled Tasks.

The AI provider, Enable AI features, the AI models, including the embeddings model, and who may open the AI Configuration page are described in AI Configuration.

Knowledge indexing in the Admin Center

Before you begin

  • The AI Configuration form must load; see If the AI Configuration form does not appear.
  • To save with Allow AI to access internal knowledge selected, the drive that holds the index file needs free space for the estimated index plus 10%; otherwise Save is disabled (see the disk space check below).

Start or stop indexing

On the AI Configuration page of the Admin Center:

  1. Select Allow AI to access internal knowledge to start indexing, or clear it to stop indexing.
  2. Click Save.

What the save does depends on how the box changed compared with the value the page loaded:

Change Effect on the AI Search Index Maintenance task
The box is now selected The task is enabled, and a run of it is requested.
The box is now cleared A request to terminate the task is sent, and the task is disabled.
The box is as it was loaded The task is left as it is, whatever else the save changes.

Once enabled, the task runs on its schedule. It refuses to run while any of the conditions listed in The index task in the supplied configuration holds. So if you select Allow AI to access internal knowledge and save while Enable AI features is cleared, the task is enabled and a run is requested, but the task refuses to run.

While Allow AI to access internal knowledge is selected, the page checks the free space on the drive that holds the index file. It estimates the size of the index as 8,192 bytes for each Incident and article to index, the total shown under Indexed:

  • When the estimate plus 10% is more than the free space, the page shows "Not enough disk space for embeddings database" and disables Save.
  • Otherwise, when the estimate plus 10% plus 5 GiB is more than the free space, the page shows "Disk space is running low for embeddings database".

With the box cleared, neither check runs.

Check indexing progress

The Vector indexing progress panel sits under the embeddings option of the AI Configuration page. While Enable AI features is cleared, the panel is dimmed and does not respond to the pointer.

Item What it shows
Last run The date of the task's last run, or Never.
Status Running, Success, or Error for the task's last run status, and Not running otherwise.
Indexed Indexed Incidents and articles against the total, as processed / total (percent%). The percentage is rounded, and it is 0 when the total is zero.
Free space The free space on the drive of the index file, in gigabytes with at most one decimal.
Database The path of the index file.
Learn more A link to a help topic.

The total under Indexed counts the Incidents that have a description, a resolution, or notes, plus the active Knowledge Base articles that have content or notes. The processed figure counts the distinct Incidents and articles that have entries in the index file, and it never exceeds the total. When the index file does not exist, the processed figure is 0.

The task's runs are also listed on the Admin Center's Scheduled Tasks page: its Tasks tab shows the task's Last Run Status and Next Run Date, and the task's Sessions tab lists its runs. See Scheduled Tasks.

If the AI Configuration form does not appear

Until both the AI provider and the index information have loaded, the page shows only its progress bar, and the form appears only when both succeed. The index information fails to load in any of these cases:

  • The map file C:\ProgramData\Alloy Software\SQLite\sqlite.json is missing or cannot be read as JSON.
  • The Admin Center's Database:Database configuration setting is missing.
  • The map file has no entry for that database, or the entry is empty.
  • The AI Search Index Maintenance task does not exist.

On such a server, you cannot edit the AI provider in the Admin Center. A missing index file is not one of these cases: the page opens and shows 0 as the processed figure.

Knowledge indexing in the Settings App

Before you begin

  • The Services > Scheduled Tasks branch, with its Tasks and Logs nodes, requires the permission of the Scheduled Tasks branch. See Scheduled Tasks.

Set the embeddings model

The Settings App's AI editor holds the embeddings model together with the other AI models. With OpenAI as the provider, the embeddings field offers text-embedding-3-small and text-embedding-3-large and also accepts other text; a new provider starts with text-embedding-3-large. With Azure as the provider, the field offers no list and is labeled Deployment name. For the rest of the editor, see AI Configuration.

Embeddings have their own check box in the editor. While it is selected, the Settings App does not save the provider with an empty embeddings model or deployment name. For a provider that has never been saved, the editor starts with the check box selected. While embeddings are turned off, the index task refuses to run.

Enable or run the index task

  1. Go to Services > Scheduled Tasks > Tasks and select AI Search Index Maintenance.
  2. Click Enable to let the task run on its schedule, or Disable to take it off its schedule.
  3. To start a run at once, click Run. Run is available for one selected task while the page shows the Automation Server as running. The Automation Server starts the run at once, outside the schedule, unless it is not active or the task is already running or locked.
  4. To stop a run in progress, click Terminate, and confirm "Are you sure you want to terminate this job?". Terminate is available for one selected task whose last status is Running.

When the Settings App cannot pass a Run or Terminate request to the Automation Server directly, it queues the request instead. For Run it shows "Since your Settings App and the Automation Server are installed on separate computers, it may take some time to test your settings. Please wait until the job has completed, and then check the session log to make sure that it runs as expected." For Terminate it shows "Please wait, the job will be terminated soon. Since your Settings App and the Automation Server are installed on separate computers, it may take some time to complete." Any other failure shows "Cannot send request to the Automation Server. Make sure the Automation Server is configured and started."

To look at the task, select it and click Open. The Scheduled Task window opens view-only and shows "This is a system task that cannot be modified. To view all details or make changes, create a copy of the task." Its Sessions tab lists the task's runs. While the Automation Server is not running, the window shows "Warning. For this job to be executed, the Automation Server must be set up and running."

Read the task's runs

The task's runs are recorded in the Scheduled Tasks log. The log opens from Services > Scheduled Tasks > Logs, and from Logs > Scheduled Tasks, which requires the permission to browse logs. Each session carries the run date, the task's name, the duration, the number of errors, and the run's remark. View Log, or opening a session, shows the session's text. A new 2026.1 database created with the Default Workflow has two shared views of the log, Last 7 days and All Time. For the log's other commands, see Scheduled Tasks.

How retrieval works

The index is a SQLite file on the web server's own disk, not part of the Alloy Navigator database. Each database served by the web server has its own index file. The file of each database is listed in the map file C:\ProgramData\Alloy Software\SQLite\sqlite.json, which is read at startup. The file's location is not set in the application.

When AI looks up internal knowledge for a technician, the search works as follows:

  1. The vector search returns up to 100 candidate entries by default, each with a distance score.
  2. Entries whose score is above the maximum distance, 0.7 by default, are dropped, and each Incident or article is kept once, closest first.
  3. An entry is admitted only when the technician may view that kind of record and may view that specific Incident or article.
  4. Only the admitted Incidents and articles are read from the Alloy Navigator database for their text. Up to five of them, by default, reach the AI.

A technician is never shown, and the AI is never shown on the technician's behalf, an Incident or an article the technician could not open.

The number of candidates, the maximum distance, and the number of entries that reach the AI are system settings. The Self Service Portal uses the same three settings, with the same defaults.

Besides the index, AI can read external context: a list of external databases held in a system setting, from which an AI Action selects the entries to read.

The index task in the supplied configuration

A new 2026.1 database created with the Default Workflow (see Default Workflow Configuration) contains the AI Search Index Maintenance scheduled task, in the Integrations group. The task is disabled in the supplied configuration, and its schedule is set to every hour. The last configuration step of an upgrade to 2026.1 imports this task into the upgraded database too. If the task already exists in the database, that import does not change whether it is enabled. An administrator may have changed whether the task is enabled, or its schedule.

The task refuses to run when any of the following holds:

  • AI is switched off (Enable AI features is cleared).
  • No API key is set for the AI provider.
  • The provider is Azure, and no endpoint URL is set.
  • Embeddings are turned off, or no embeddings model is set.

Enabling the task on a system whose AI is not configured therefore fails at once instead of building a partial index.

When it runs, the task indexes:

  • the Incidents whose description, resolution, or notes hold text;
  • the Knowledge Base articles whose content or notes hold text.

The status of an Incident or an article does not limit what is indexed, with one exception: for an article in the Retired status, the task removes the article's entries from the index instead of indexing it. Each field that holds text is indexed on its own, and a field longer than 10,240 characters is split into parts that are indexed separately.

A run reads only the Incidents and articles saved since the last change it indexed, and it removes from the index the entries of Incidents and articles deleted since then. When the last full pass is more than a day old, the run is a full pass instead: it reads every Incident and article and skips those whose entries are already up to date with their last modification. When the embeddings model differs from the one the index was built with, the task rebuilds the entries of every Incident and article; the old entries stay in the index until they are overwritten.

The task writes the index file. The file holds the identifiers of the indexed Incidents and articles, dates, the embeddings, and the name of the embeddings model; it does not hold the indexed text.

Like every scheduled task, the task is started by the Automation Server. If the Scheduled Tasks feature was never installed, the task fails at launch with "File not found".