Setting up the AI assistant

The AI assistant is a chat in the side panel of Webdesk. It answers questions of the logged-in user and can call predefined tools for this purpose. The tools read data from Webdesk (persons, groups, time and attendance, project time) and, in one case, also write data (attendance booking). The answers are generated by an external language model that the administrator connects through a model (credentials and endpoint). Optionally, agents combine a model, additional instructions and permitted tools.

This page is intended for administrators and consultants. It describes the setup, the order in which key, model and endpoint are determined, the tool catalog, the authorization checks and the data flows to the external provider. The feature is mentioned briefly in New Features; the general handling of system parameters is described in System parameters.

Warning: Once the assistant is configured, texts entered by the user, information about the user and the results of the tools that were called are transmitted to the configured external provider (details in the section Data protection). Before activating it, clarify whether this is permitted for the company.

Prerequisites

• Licence: The licence definition ai-impl.ldef.xml defines the licence ai (module ai) with the description "Number of users allowed to chat with custom AI agents". The licence assigns the module its Spring contexts and all of its actions (no action is excluded). The licence usage can be viewed under System > Current licence (see Licence information).
• Network: The Webdesk server must be able to reach the provider endpoint (default: https://api.openai.com/v1) via HTTP(S).
• Credentials: An API key of the provider, the model name (for Azure OpenAI: the deployment name) and, for providers other than OpenAI, the base URL.
• Permissions: Administrators need the actions ai_showModels.act and ai_showAgents.act (editing via ai_editModel.act and ai_editAgent.act); users need the action ai_assistant.act. Permissions are granted like for any other action.

Menu and actions

The administration menu contains three entries under Modules > AI Administration:

The lists show entries of the accessible clients as well as the public entries (no client set, displayed as "Public"). The link for editing public entries is only shown to users who may view the data of all clients.

Icon in the side panel

The assistant icon (tooltip "Assistant") appears in the header only if the action ai_assistant.act exists and the user is authorized for it. Clicking it opens or closes the side panel, which can be pinned (from a window width of 1200 pixels), minimized and opened in full screen. If the icon is missing, the permission or the licence ai is missing.

Setup

1. Create a model: AI Models > "New AI Model" (fields see next section) and save.
2. Optionally create an agent: AI Agents > "New AI Agent", select the model and, if required, define the system prompt and tools.
3. Alternatively set global defaults: Store the API key, model and base URL as environment variable, JVM parameter or system parameter AiOptions (order see below). These defaults apply if no agent or no model is used, and they replace an empty API key in the model.
4. Grant permissions: Give the users or roles the action ai_assistant.act as well as the actions of the modules whose tools are to be used (see tool catalog).
5. Test: Open the panel as a user and ask a question, e.g. about the remaining vacation. The replies for error cases are listed in the section Troubleshooting.

Model ("AI Model")

A model describes how Webdesk addresses a language model of a provider. Name, Provider and Model ID are required fields.

Note: In the code, the model field "API Key" is not encrypted when saved. The system parameter AiOptions.defaultAiApiKey, in contrast, is stored encrypted and displayed as a password in the mask. For installations with a single provider it is therefore advisable to store the key there (or as an environment variable) and leave the model field empty.

Agent ("AI Agent")

An agent defines which model the assistant works with, which additional instructions it receives and which tools it may use. Name and Model are required fields.

Which agent is used?

• If the user selects an agent in the agent selection of the chat, it is used provided it is public or belongs to the user's client. Otherwise Webdesk falls back to the default agent: the alphabetically first agent of the client, otherwise the alphabetically first public agent, otherwise the first accessible agent.
• If the selection stays at "Default agent (auto)" (empty value), Webdesk uses an internal default assistant without a model and without tool restriction. Model, base URL and key then come exclusively from the global defaults, and all tools are available that the user may use according to his or her permissions. If the call fails in this mode with "model not found" (HTTP 404), Webdesk repeats it once with the default agent of the client.

Warning: The tool selection of an agent is not a security boundary. Any user can choose "Default agent (auto)" in the agent selection, which removes the restriction of the agent. The action permissions are decisive for security (see authorization checks).

Order of the settings (fallback)

Webdesk determines API key, model name and base URL for every request. The first non-empty value of the respective list applies. Regardless of the provider, the environment variables and JVM parameters are called OPENAI_API_KEY, OPENAI_MODEL and OPENAI_BASE_URL, and they take precedence over the system parameter AiOptions.

The field of the model is only considered if the chat uses an agent with an accessible model. In all other cases ("Default agent (auto)", model of a different client) step 1 is skipped and the provider "OpenAI-compatible" and the global defaults are used. If the model contains a model name but no key, the key is determined by steps 2 to 4.

System parameter AiOptions

The bean AiOptions contains the global defaults. They only apply if neither the model nor an environment variable or JVM parameter supplies a value.

Tool catalog

Tools are defined in the program and cannot be created in the user interface. They are provided by the modules Portal & Organization (PO), Time & Attendance (TA) and Project Time Management (PTM). All tools run on behalf of the logged-in user: the "getMy..." tools return only his or her own data, the other tools only data that he or she may see according to the checks described below. Tools that change data are marked "Writing".

Portal & Organization

Time & Attendance

Project Time Management

The only writing tool is doBooking. All other tools are read-only.

Authorization checks for tools

1. Action permission (offering): Each tool names one or more required actions. A tool is only offered to the language model if the user is authorized for at least one of them; permissions on derived configurations of the action count as well. If a tool refers to an action that does not exist in the system, that action is skipped (warning in the log); if no known action remains, the tool is blocked. Tools of modules whose actions are not present or not authorized are therefore not available.
2. Restriction by the agent: The list is then reduced to the agent's "Allowed Tools" (only if an agent is selected and the list is not empty).
3. Target check (execution): When a tool is called, Webdesk checks all arguments whose name ends in uid or uids (e.g. personUid, groupUid) for permission on the object concerned. For every UID passed, the user must be authorized for at least one of the required actions for exactly this object (permission on object level or a matching configuration of the action for this person). Otherwise the model receives the error message "Tool not permitted for requested target." and the tool is not executed.

The tools are thus bound to the permissions of the user. Errors and rejections are part of the tool display in the chat (Arguments / Result).

Interfaces (REST)

The chat user interface communicates with endpoints under /rest/ai. They always work on behalf of the logged-in user.

The mcp endpoints are a simple MCP-style interface and use the same authorization checks as the chat, but without agents and without a language model: doBooking can also be called there. For internal calls from the user interface, the REST access rights of the action ai_assistant.act (/rest/ai/*, GET and POST) are used; external callers (e.g. with an API key) need role-based REST access rights.

Conversation history

• Each conversation belongs to exactly one user and his or her client; other users cannot retrieve it via the interfaces. There is no administration mask for conversations.
• Stored are the conversation (title, owner, client, selected agent and model, timestamps) and, per message, role (user, assistant, tool result), text, tool name, tool arguments, tool result (JSON), error text, agent, model and timestamp (table AiConversationMessage). Tool results therefore also contain the data that was queried, e.g. names and e-mail addresses of colleagues.
• The title is built from the first 80 characters of the first question and can be renamed.
• For every message the chat calls the language model with the previous history (last 30 messages; older parts are removed when an estimated size of about 3500 tokens is exceeded). If an existing conversation is restarted with the flag "fresh" (menu "Regenerate fresh" in the chat), its stored messages are deleted.
• The code has no automatic deletion or retention period and no function to delete whole conversations. Cleanup, if required, must be done in the database.
• Error replies of the chat (see Troubleshooting) are also stored as assistant messages in the history.

Data protection: what leaves the system?

With every chat request Webdesk sends the following to the configured endpoint (base URL of the model or of the global default):

• The standard prompt with the current time, the user name and rules for using the tools, extended by the agent's System Prompt.
• Information about the logged-in user: UID, user name, first and last name, employee ID, validity (from/to), download address of the person photo, language, TA ID, time zone, e-mail address, active flag and short name of the organizational unit.
• The page context of the currently opened page: action name, menu path, page title, full page URL, action type, process definition as well as the object ID and URL parameters of the page. The user can display this context in the panel via the eye icon ("Show shared context").
• The messages of the user including the conversation history (see above) and the results of all tools called (e.g. personal data of colleagues, bookings, absences, vacation days, project times) as well as the descriptions and parameters of the tools offered.

The API key serves exclusively as credentials for the configured endpoint. Processing at the provider is governed by the provider's terms and lies outside Webdesk; this page makes no statement about it.

In the server log (logger of the class at.workflow.webdesk.ai.impl.AiChatServiceImpl) the user name, the chosen provider with model, base URL and agent name, as well as the tool calls with arguments and results (each truncated to 500 characters) appear at level INFO. The API key is not logged.

Ways to restrict

Troubleshooting