Administration Guide

AI Configuration

On this page

Alloy Navigator's AI features use one language-model provider for the whole system: OpenAI or Azure OpenAI. You connect the provider, choose its models, and switch AI features on or off in the Settings App or in the Admin Center; see Admin Center and Settings App. No license module gates AI as a whole: whether AI is available at all depends on the master switch, the presence of an API key, and the switches of the individual features. The license does narrow the Self Service Portal AI Assistant: its skills and tools follow the modules the license covers.

The writing-assistance actions that AI offers are set up separately, in AI Actions.

What is on in a new database

A new database starts with AI switched on but not connected:

  • The master switch is on: AI features are enabled.
  • No provider and no API key exist. The AI features that are on do not work until you store an API key.
  • Embeddings are off.

AI content of the Default Workflow

A new database created with the Default Workflow also contains the following AI content; see Default Workflow Configuration.

  • The writing-assistance actions are enabled; see AI Actions. They start working once an API key is stored.
  • The workflow actions of the AI-Powered group, listed in the table below, are enabled. Each one opens a form with an AI control, which starts working once an API key is stored. Their condition requires AI features to be enabled.
  • The AI Search Index Maintenance scheduled task is disabled. Retrieval over Knowledge Base articles and tickets needs embeddings switched on, and then this task enabled; see AI Knowledge Index and Scheduled Tasks.
  • The Self Service Portal AI Assistant's commands and skills are enabled, but the AI Assistant itself is off: Enable AI Assistant, on a portal instance's AI Assistant page in the Admin Center, is cleared; see Portal AI Assistant readiness. Besides this setting, the AI Assistant needs AI features enabled, an API key, and a completion model, and its Knowledge Base search needs embeddings.
Class AI-Powered actions
Incident Summarize Incident, Suggest Solution, Suggest Category
Request Summarize Request, Suggest Next Steps, Suggest Category
Problem Summarize Problem, Suggest Solution, Suggest Category
Change Request Summarize Request, Suggest Action Plan, Suggest Category, Analyze Risks
Work Order Summarize Work Order, Suggest Next Steps, Suggest Category

An upgraded database may contain different AI actions and assistant settings, and an administrator may have changed them. For how upgrades affect the supplied workflow, see Default Workflow Configuration. An upgrade does not change whether an existing workflow action or scheduled task is enabled.

The provider record

There is exactly one provider record for the whole system. It holds:

Setting What it is
Provider type OpenAI or Azure OpenAI.
API key The provider's API key. It is stored encrypted.
Endpoint URL The Azure resource URL. Required for Azure, not used for OpenAI.
Completion model The chat-completion model. It is required whenever AI is used and has no switch of its own: an API key is what turns completion on.
Text-to-speech model Used for read-aloud. It has its own switch, on in a new database.
Transcription model Used for voice input. It has its own switch, on in a new database.
Embeddings model Used for the vector index and retrieval. It has its own switch, off in a new database.

When a capability's switch is on, its model is required. In the Admin Center, this applies only while AI features are enabled; see Configure AI in the Admin Center.

For Azure, the model fields take deployment names instead of model names. The Azure option is the service Microsoft now calls Microsoft AI Foundry, formerly Azure OpenAI Service; see Microsoft AI Foundry.

Models

With OpenAI selected, both applications offer a list of models in each model field, and you can also type another name. With Azure selected, there is no list: you enter the deployment names.

To use a GPT-6 model, enter its model ID. For example, in the Admin Center, type gpt-6-luna in Completion model.

Model field Offered for OpenAI Proposed for a new provider
Completion gpt-5.4-nano, gpt-5-mini, gpt-5.4-mini, gpt-5.4; the Admin Center also offers gpt-5.5 gpt-5.4-nano
Text-to-speech tts-1, tts-1-hd tts-1
Transcription whisper-1 whisper-1
Embeddings text-embedding-3-small, text-embedding-3-large text-embedding-3-large

The Settings App proposes these values for a provider that has never been saved. The Admin Center shows them when no model is stored.

The embeddings model is optional: it is used only while embeddings are switched on. In the Admin Center, the embeddings switch is Allow AI to access internal knowledge ("Enables the creation of a private vector index that allows AI to search across your internal Service Desk content such as tickets and knowledge base articles."). Switching embeddings on is recommended, because without them:

  • Retrieval over Knowledge Base articles and tickets is unavailable. It also needs the AI Search Index Maintenance scheduled task enabled; see AI Knowledge Index.
  • The Self Service Portal AI Assistant cannot search the Knowledge Base.

For the Self Service Portal AI Assistant, choose a completion model that supports the provider's Responses API. A successful Test Connection does not check that API, so also test the assistant in the portal.

The master switch and AI states

The master switch is Enabled AI Features in the Settings App and Enable AI features in the Admin Center. Both set the same system setting.

The Web App shows AI in one of three states:

State When In the Web App
Hidden The master switch is off. The writing-assistance and voice buttons are not shown. An AI control on a workflow action form is not hidden: the control reacts only to the Disabled state.
Disabled The master switch is on, but no API key is stored. The writing-assistance and voice buttons are shown disabled, with a tooltip that explains why. An AI control on a workflow action form still opens, shows an explanation in place of the answer, disables its copy, regenerate, and chat buttons, and does not send its automatic first request.
Enabled The master switch is on and an API key is stored. AI features are available.

Turning AI off therefore removes the buttons rather than graying them. In workflow, the AI Features Enabled macro returns whether the switch is on; see Macros Reference.

The Self Service Portal follows the master switch too. While the switch is off, the portal has no AI: its AI Assistant page is not found, and Knowledge Base retrieval is refused. While the switch is on, the portal's AI is enabled only when both an API key and a completion model are stored.

Who may configure AI

  • In the Settings App, the AI Integration administrative permission ("Allows managing AI Integration") covers the AI Integration branch and both of its pages, AI Configuration and AI Actions. There is no separate right for reading the key, editing actions, or the assistant catalogs. The branch is also present in Alloy Navigator Cloud; see Administering Alloy Navigator Cloud.
  • In the Admin Center, the AI Configuration and AI Actions pages open for either of two permissions: AI Integration or Administrative Access.

See Permissions Reference.

Configure AI in the Settings App

  1. Open AI Integration > AI Configuration.
  2. Select Enabled AI Features to switch AI on, or clear it to switch AI off.
  3. Choose the provider type, OpenAI or Azure.
  4. Enter the API key.
  5. For Azure, enter the endpoint URL, the URL of your Azure resource. The field appears when Azure is selected and is required.
  6. Choose or type the completion model. For Azure, the model fields are labeled Deployment name: enter your deployment names.
  7. Switch text-to-speech, transcription, and embeddings on or off, and fill in the model or deployment name of each capability you switch on.
  8. Save your changes.

For a provider that has never been saved, all three capabilities start switched on. The Settings App refuses to save while a capability is on and its model or deployment name is blank, and it treats the completion model as mandatory as well. The Settings App has no connection test; only the Admin Center has one.

Configure AI in the Admin Center

IMPORTANT: The Admin Center works with one provider record of its own. If the provider was first saved in the Settings App, the first time you open the Admin Center's AI Configuration page, or a portal instance's AI Assistant page, the Admin Center replaces the provider record with an empty one. The API key, the endpoint, and the models are removed, and while AI features are enabled the Web App shows AI as disabled. The new record has OpenAI selected, text-to-speech and transcription switched on, and embeddings switched off. If no provider record exists yet, the first visit creates one, and later saves in the Settings App edit that same record.

  1. Open the AI Configuration page.
  2. Select Enable AI features ("Activates AI-powered features. Uncheck to turn AI off."). While it is clear, every other control on the page is disabled.
  3. Under AI Provider, choose OpenAI API or Azure OpenAI Service.
  4. Enter the API Key.
  5. Select Enable Text-to-Speech, Enable speech recognition, and Allow AI to access internal knowledge as needed. Each one enables its own model field.
  6. Fill in the models:
    • For OpenAI, choose or type the Completion model, and for each capability you selected the Text-to-Speech model, Transcription model, or Embedding model.
    • For Azure, enter the Endpoint URL and the Completion deployment name, and for each capability you selected the Text-to-Speech deployment name, Transcription deployment name, or Embeddings deployment name.
  7. Optionally, click Test Connection.
  8. Click Save.

Save and Cancel appear only once you change the form. With Enable AI features selected, the completion field is required, the Endpoint URL is required for Azure, and each other model field is required while its checkbox is selected. A missing value shows "The "field" field is mandatory, it can't be left blank", naming the field as it is labeled for the selected provider. With Enable AI features clear, nothing is required.

The API key:

  • The page never shows the stored key. The API Key field shows that a key exists only while the selected provider type is the saved one.
  • A save with the API Key field empty keeps the stored key. Nothing on the page removes a stored key. After a successful save, the field is empty again.

When you switch AI Provider, the page clears its validation errors, resets the API Key field, and exchanges the completion, text-to-speech, and transcription values with the ones last entered under the other provider type. The first switch in a visit empties them. The embeddings value stays as it is.

Test the connection

Test Connection sends one short chat request built from the values in the form, saved or not, and saves nothing. While it runs, the button reads Testing.... It is disabled when Enable AI features is clear, a test is running, the completion field is empty, Azure is selected without an endpoint, or no key is available: none is typed, and there is no stored key, or the stored key cannot be used because the selected provider type differs from the saved one or the key field was edited.

For OpenAI the test contacts https://api.openai.com; for Azure it contacts your endpoint URL. The request times out after 30 seconds and does not follow redirects.

On success, the page shows "Connection test successful!". On failure, a dialog headed "Error" shows "Connection test failed.", the message, and "Recommendation:" followed by a recommendation:

Cause Message Recommendation
No key available "No API key configured" "Verify your API key is correct, not expired, and has proper permissions."
The server returns a redirect "Invalid endpoint URL: server returned a redirect" "Check network connection and endpoint URL."
Access refused (HTTP 401 or 403) the provider's error message "Verify your API key is correct, not expired, and has proper permissions."
Model not found (HTTP 404) the provider's error message "Verify the model/deployment name matches your provider configuration."
Rate limit (HTTP 429) the provider's error message "Check your provider quota and billing settings, or wait and try again."
Any other failure status the provider's error message, or the HTTP code and reason "The AI provider service may be temporarily unavailable. Try again later."
Timeout "Connection timed out after 30 seconds" "Check firewall settings to ensure outbound traffic to the AI provider endpoint is allowed."
Connection failure "Unable to connect to AI provider" "Check network connection and endpoint URL."

If the provider answers with a failure whose body is not JSON, the test fails without showing this dialog.

Portal AI Assistant readiness

A portal instance's AI Assistant page in the Admin Center shows whether the provider is ready. It reads "AI Assistant is currently unavailable" while AI features are off or no API key is stored, 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.