AI-Service documentation

The OX AI-Service integrates 3rd party AIs in App Suite UI, currently ChatGPT from OpenAI, Anthropic Claude on AWS Bedrock or localAI compatible models.

Configuration

The AI Service delivers the App Suite UI plugin, it needs to be added to the baseUrls configuration to ensure the UI Service can fetch the frontend code.

Add the AI Service url (K8s url) to the list of baseUrls of the UI Service configuration. This is needed to ensure that the AI integration's code is send to the user's browser.

Example config map

# hostnames may differ in your setup
baseUrls:
  - http://core-ui
  - http://ai-service
  - http://switchboard

Further reading: UI Service Config map

Capability and Feature toggle

Capability: ai-service

Feature toggle: ai

Requirements

Ensure the following prerequisites are met to run the AI-Service App Suite plugin:

1. A running Switchboard in your stack is needed to run the AI Service. (Switchboard is needed for service-to-service authentication)
2. You are using the Provider Edition (PE) of OX App Suite. This needs a paid App Suite Subscription (For more information contact Sales)
3. The mandatory user config is set for each user that should be able to use the AI integration, see the next chapter

How to enable for users

By default, AI integration is disabled for all users. To enable the feature for users, add the following configurations:

1. Add capability ai-service which indicates a running AI-Service in your deployment
2. Enable the feature toggle for users via

io.ox/core//features/ai = true

3. Set the public available hostname for AI service in the user configuration

io.ox/core//ai/baseURL = https://ai-service.your.deployment.com

Additional AI features

Besides the basic feature set, more advanced features can be turned on via separate switches

Chat

The AI chat allows a user to chat with the AI. There is a separate feature toggle for this.

io.ox/core//features/ai-chat=<bool>
default: true

This enables or disables the chat in App Suite UI.

You can also configure the assistant globally by providing context with a system prompt. This prompt will be injected in every conversation as a start message invisible to the end user. Set chatAssistantContext on AI Service config, default is "You are a helpful AI assistant."

Example:

chatAssistantContext: "You are a helpful AI assistant. Your name is Hal 9000."

The frontend part can be configured via the following settings:

io.ox/core//ai/chat/showLauncher=<bool> (default: true)

Add the AI Chat as App in the the App Launcher

io.ox/core//ai/chat/showTopRightIcon=<bool> (default: true)

Add the AI Chat as Icon on the right side in the App Suite toolbar (next to the notification icon)

io.ox/core//ai/chat/autoOpenOnFirstRun=<bool> (default: true)

Automatically open the Chat window for all users with the AI feature on the first run, e.g. after updating to the most recent AI Service. This is helpful to boost AI engagement and make the feature visible.

Typeahead for mail compose

The typeahead feature provides automatic text predictions while composing emails. Using AI, it generates text that either completes a sentence or aligns with the overall context. Predictions can be triggered manually by pressing Ctrl+Space during mail composition or will appear automatically after the cursor remains idle for a set period (e.g., 3, 5, or 10 seconds).

This feature includes a dedicated toggle, allowing it to be enabled or disabled for all users.

io.ox/core//features/ai-typeahead=<bool> (default: false)

When enabled, this feature is opt-in, requiring users to acknowledge that the AI will process their email text to generate predictions.

The AI settings panel provides additional user options for this feature, allowing control over whether predictions are shown automatically, only when using a keyboard shortcut, or not at all.

Automatic mail translation

With the automatic mail translation feature the user can translate mails into their set language automatically.

This feature includes a dedicated toggle, allowing it to be enabled or disabled for all users.

io.ox/core//ai/features/ai-autotranslate=<bool> (default: true)

The feature can detect the language of a mail and will translate it based on the settings for this language. The user can set which language they want to always translate and which languages should never be translated. Currently the following languages can be detected: German, French, English, Spanish, Italian There is a dedicated settings section to manage this. If the language of a mail is not detected automatically the user can always choose to manually translate a mail via the ai dropdown menu.

Engage Idle AI Users

To encourage users to explore AI features, it may be helpful to remind them about these features. A simple approach is to display the AI Tour again after a certain period of inactivity.

io.ox/core//ai/tour/remindAfterIdleDays=<number> (default: -1 (disabled))

If a user has already seen the tour but does not use any AI feature within the specified number of days, the tour will reappear exactly once.

Note: This feature relies on the date of the user's initial consent to determine whether any AI features have been used during the defined period.

Upsell configuration

AI integration supports the App Suite UI upsell functionality. To enable upsell for the AI features, set the following frontend configuration:

io.ox/core//upsell/activated = true
io.ox/core//upsell/enabled/ai-service = true
io.ox/core//features/ai = true

Remove the capability ai-service for all users that should see the upsell triggers. When enabled, all AI buttons and dropdowns are shown in the UI but will trigger an upsell event on the ox object.

Consent dialog

The consent text can be customized via the following settings. For each locale that needs to be customized you must place a key in the custom strings config, eg. "en_US" or "de_DE".

It is also possible to set this language based eg. "en" or "de".

This applies to all settings under io.ox/core//customStrings.

e.g.:

io.ox/core//customStrings/ai/consent/title/en_US = "Your consent is required"
io.ox/core//customStrings/ai/consent/title/de_DE = "Bitte stimme den Bedingungen zu"

Consent Dialog Settings

Default Consent Text:

By using any of the AI-based features, you agree to submit the subject data to an external artificial intelligence-based text transformer operated by %1$s located in %2$s. This process will only occur upon your proactive engagement to ensure that no data is automatically transmitted. It will not be used to train the underlying AI model, but is subject to %3$s's Data Use Policy. Please note that you may be restricted by law or contract from providing confidential information (including personal information) to any third party, including an AI and its operator. You may return to this consent dialog at any time to review and change your consent status under Settings > Mail > AI Integration.

• %1$s: Injects a link to the AI service website (io.ox/core//ai/config/default/serviceName as link text, io.ox/core//ai/config/default/serviceLink as link target).
• %2$s: Uses io.ox/core//customStrings/ai/consent/location for the AI service's location.
• %3$s: Uses io.ox/core//ai/config/default/serviceName to refer to the AI service.
• %4$s: Uses io.ox/core//ai/config/default/dataUsagePolicy as the link to the data usage policy.

Error Messages

User facing error messages can be customized:

Language support and i18n

Supported languages in the AI frontend

The AI frontend is translated in the following languages

Fallback language is always English (en_US)

LLM language support

Not every LLM that can be connected offers the same level of language support. This is important, as users interact directly with the LLM through AI Chat and other user-generated input (e.g., when composing emails).

For ChatGPT 4o and newer, the following table categorizes languages based on their level of support:

For reference:

• The LLM supports many languages, categorized by proficiency levels (e.g., Top Tier, Strong, Functional).
• The UI is translated into a subset of these languages, covering those with strong user demand and reliable localization and matching the most important languages in App Suite

This means that while users can interact with the LLM in many languages, the application interface itself is only available in the languages listed above. As a fallback users are always able to interact with the Chat e.g in English.

Translation feature

The AI Integration includes a dedicated translation feature for emails. By clicking on the AI dropdown in the email toolbar, users can choose to translate emails into their preferred language.

The first option always translates the email into the user's currently set locale. For example, if the user's UI language is set to German, we assume this is their preferred language for translations. The second option is always English, as it is the most commonly used language in our context and serves as a reliable intermediary for translating foreign languages using the LLM.

The following languages are currently supported for translation. This list may change in the future. For UX reasons, we do not include every possible language, as an excessively long dropdown would negatively impact usability.