Vergleichsreport

Der KI-Assistent ist ein Chat im Seitenpanel von Webdesk. Er beantwortet Fragen des angemeldeten Benutzers und kann dafür vordefinierte Tools aufrufen, mit denen er Daten aus Webdesk liest (Personen, Gruppen, Zeiterfassung, Projektzeit) und in einem Fall auch schreibt (Anwesenheitsbuchung). Die Antworten erzeugt ein externes Sprachmodell, das der Administrator über ein Modell (Zugangsdaten und Endpunkt) anbindet. Optional fassen Agenten Modell, Zusatz-Anweisungen und erlaubte Tools zusammen.

Die Seite richtet sich an Administratoren und Consultants und beschreibt die Einrichtung, die Reihenfolge, in der Schlüssel, Modell und Endpunkt ermittelt werden, den Werkzeugkatalog, die Berechtigungsprüfung und die Datenflüsse zum externen Anbieter. Eine kurze Erwähnung der Funktion findet sich in Neue Features; die allgemeine Bedienung der Systemparameter ist in Systemparameter beschrieben.

Achtung: Sobald der Assistent konfiguriert ist, werden Texte des Benutzers, Angaben zu seiner Person und die Ergebnisse der aufgerufenen Tools an den konfigurierten externen Anbieter übertragen (Details im Abschnitt Datenschutz). Vor der Aktivierung muss geklärt sein, ob dies für das Unternehmen zulässig ist.

Voraussetzungen

Lizenz: Die Lizenzdefinition ai-impl.ldef.xml definiert die Lizenz ai (Modul ai) mit der Beschreibung "Anzahl der Benutzer, die mit benutzerdefinierten AI Agenten chatten dürfen". Die Lizenz ordnet dem Modul seine Spring-Kontexte und alle seine Aktionen zu (keine Aktion ist ausgeschlossen). Die Lizenzauslastung ist unter System > Aktuelle Lizenz einsehbar (siehe Lizenz-Information).

Netzwerk: Der Webdesk-Server muss den Endpunkt des Anbieters (Standard

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) per via HTTP(S) erreichen können.
• ZugangsdatenCredentials: Ein API-Schlüssel des Anbieters, der Modellname (bei Azure OpenAI: der Deployment-Name) und bei anderen Anbietern als OpenAI die Basis-URL. Berechtigungen: Administratoren benötigen die Aktionen 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 und and ai_showAgents.act (Bearbeiten über editing via ai_editModel.act bzw. and ai_editAgent.act), Benutzer die Aktion ; users need the action ai_assistant.act. Die Berechtigungen werden wie bei jeder anderen Aktion vergeben.

Menü und Aktionen

Im Administrationsmenü gibt es unter Module > AI Administration drei Einträge:

Menüeintrag

Aktion

Zweck

AI Modelle

• Permissions are granted like for any other action.

Menu and actions

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

Menu entry	Action	Purpose
AI Models	ai_showModels.act (Bearbeitenediting: ai_editModel.act)	Liste der Modelle (Spalten List of models (columns Name, Provider, Model ID, Basis Base URL, MandantClient); Schaltfläche button "Neues New AI ModellModel".
AI AgentenAgents	ai_showAgents.act (Bearbeitenediting: ai_editAgent.act)	Liste der Agenten (Spalten List of agents (columns Name, BeschreibungDescription, Model ID, MandantClient); Schaltfläche button "Neuer New AI Agent".
Assistent	Assistant	ai_assistant.act	Der Chat selbst (Beschreibung The chat itself (description "AI Assistent ChatAssistant chat"). Zugriff auf die REST-Schnittstelle Grants access to the REST interface /rest/ai/... für for GET und POST.

Die Listen zeigen Einträge der zugänglichen Mandanten sowie die öffentlichen Einträge (kein Mandant gesetzt, Anzeige "Öffentlich"). Der Link zum Bearbeiten öffentlicher Einträge erscheint nur für Benutzer, die die Daten aller Mandanten ansehen dürfen.

Symbol im Seitenpanel

In der Kopfzeile erscheint das Assistent-Symbol (Tooltip "Assistent") nur, wenn die Aktion ai_assistant.act existiert und der Benutzer dafür berechtigt ist. Ein Klick öffnet bzw. schließt das Seitenpanel, das sich anheften (ab einer Fensterbreite von 1200 Pixeln), minimieren und im Vollbild öffnen lässt. Fehlt das Symbol, fehlt die Berechtigung oder die Lizenz ai.

Einrichtung

1. Modell anlegen: AI Modelle > "Neues AI Modell" (Felder siehe nächster Abschnitt) und speichern.
2. Optional Agent anlegen: AI Agenten > "Neuer AI Agent", das Modell auswählen, bei Bedarf System Prompt und Tools festlegen.
3. Alternativ globale Vorgaben setzen: API-Schlüssel, Modell und Basis-URL als Umgebungsvariable, JVM-Parameter oder Systemparameter AiOptions hinterlegen (Reihenfolge siehe unten). Diese Vorgaben gelten, wenn kein Agent bzw. kein Modell verwendet wird, und ersetzen einen leeren API-Schlüssel im Modell.
4. Berechtigung vergeben: Den Benutzern bzw. Rollen die Aktion ai_assistant.act sowie die Aktionen der Module geben, deren Tools genutzt werden sollen (siehe Werkzeugkatalog).
5. Testen: Als Benutzer das Panel öffnen und eine Frage stellen, z.B. nach dem Resturlaub. Die Antworten auf Fehlerfälle stehen im Abschnitt Fehlersuche.

Modell ("AI Modell")

Ein Modell beschreibt, wie Webdesk ein Sprachmodell eines Anbieters anspricht. Pflichtfelder sind Name, Provider und Model ID.

Adresse des Dienstes. Leer: Es gilt die globale Vorgabe (siehe Reihenfolge), zuletzt

Feld	Erklärung	mögliche Wert(e)
Name	Bezeichnung des Modells in Listen und Auswahldialogen.	Text, Pflichtfeld
Mandant	Bindet das Modell an einen Mandanten. Ohne Mandant ist das Modell öffentlich und steht allen Mandanten zur Verfügung. Ein Agent kann nur Modelle verwenden, die öffentlich sind oder zu seinem eigenen Mandanten gehören.	Mandant oder leer (Öffentlich)
Provider	Art der Schnittstelle. "OpenAI-kompatibel" (gespeichert als OpenAi) spricht die OpenAI-Chat-Schnittstelle an, also auch andere Dienste mit kompatibler Schnittstelle (auch über http://; es wird HTTP/1.1 verwendet). "Azure OpenAI" (gespeichert als AzureOpenAi) verwendet die Azure-Schnittstelle. Wird "OpenAI-kompatibel" gewählt, die Basis-URL aber enthält openai.azure.com oder /openai/deployments/, wechselt Webdesk automatisch auf Azure OpenAI.	OpenAI-kompatibel / Azure OpenAI, Pflichtfeld
Model ID	Kennung des Modells beim Anbieter. Bei Azure OpenAI ist es der Deployment-Name; enthält die Basis-URL einen Abschnitt /openai/deployments/<name>, hat dieser Name Vorrang vor der Model ID (Warnung im Log).	Text, Pflichtfeld, z.B. gpt-4o
Basis URL	and POST.

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.

Field	Description	Possible value(s)
Name	Designation of the model in lists and selection dialogs.	text, required
Client	Binds the model to a client. Without a client the model is public and available to all clients. An agent can only use models that are public or belong to its own client.	client or empty (Public)
Provider	Type of interface. "OpenAI-compatible" (stored as OpenAi) uses the OpenAI chat interface, i.e. also other services with a compatible interface (also via http://; HTTP/1.1 is used). "Azure OpenAI" (stored as AzureOpenAi) uses the Azure interface. If "OpenAI-compatible" is selected but the base URL contains openai.azure.com or /openai/deployments/, Webdesk automatically switches to Azure OpenAI.	OpenAI-compatible / Azure OpenAI, required
Model ID	Identifier of the model at the provider. For Azure OpenAI this is the deployment name; if the base URL contains a section /openai/deployments/<name>, this name takes precedence over the Model ID (warning in the log).	text, required, e.g. gpt-4o
Base URL	Address of the service. Empty: the global default applies (see order), finally https://api.openai.com/v1. Ein angehängtes A trailing /chat/completions wird entfernt is removed. Bei For Azure OpenAI ist die Basis-URL zwingend; die API-Version wird aus dem Parameter api-version der URL übernommen, und ein Host auf the base URL is mandatory; the API version is taken from the api-version parameter of the URL, and a host ending in .cognitiveservices.azure.com wird auf is rewritten to .openai.azure.com umgeschrieben.	URL (Standarddefault: leerempty)
Routing -Praeferenz	Wunsch an Routing-Dienste, der als Parameter preference mitgesendet wird. Wirkt nur, wenn die Basis-URL cortecs.ai enthält; für andere Endpunkte wird der Wert ignoriert (Warnung im Log). Bei Cortecs-Endpunkten sendet Webdesk zusätzlich include_metadata und schaltet parallele Tool-Aufrufe ab.	Standard (leer) / Ausgewogen (balanced) / Kostenoptimiert (cost) / Geschwindigkeitsoptimiert (speed)	API Schluessel	API-Schlüssel des Anbieters, Eingabe als Passwortfeld. Der Wert wird unmittelbar als Schlüssel verwendet (keine Referenz auf einen externen Tresor). Leer: Es gilt die globale Vorgabe (siehe Reihenfolge).	Text, z.Bpreference	Request to routing services, sent as parameter preference. It only takes effect if the base URL contains cortecs.ai; for other endpoints the value is ignored (warning in the log). For Cortecs endpoints Webdesk additionally sends include_metadata and disables parallel tool calls.	Default (empty) / Balanced (balanced) / Cost optimized (cost) / Speed optimized (speed)
API Key	API key of the provider, entered in a password field. The value is used directly as the key (it is not a reference to an external vault). Empty: the global default applies (see order).	text, e.g. <your-api-key>

Hinweis: Das Modellfeld Note: In the code, the model field "API Schluessel" hat im Code keine Verschlüsselung beim Speichern. Der Systemparameter AiOptions.defaultAiApiKey wird dagegen verschlüsselt gespeichert und in der Maske als Passwort dargestellt. Für Installationen mit einem einzigen Anbieter ist es daher sinnvoll, den Schlüssel dort (oder als Umgebungsvariable) zu hinterlegen und das Modellfeld leer zu lassenKey" 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")

Ein Agent legt fest, mit welchem Modell der Assistent arbeitet, welche zusätzlichen Anweisungen er erhält und welche Tools er verwenden darf. Pflichtfelder sind Name und Modell.

Feld	Erklärung	mögliche Wert(e)
Name	Anzeigename. Er erscheint in der Agent-Auswahl des Chats und bestimmt die Reihenfolge (alphabetisch).	Text, Pflichtfeld
Mandant	Bindet den Agenten an einen Mandanten. Ohne Mandant ist der Agent öffentlich. Ein Benutzer sieht und verwendet nur Agenten seines Mandanten und öffentliche Agenten. Der Auswahldialog für das Modell zeigt öffentliche Modelle und, wenn hier ein Mandant gewählt ist, die Modelle dieses Mandanten; ohne Mandant nur öffentliche Modelle.	Mandant oder leer (Öffentlich)
Beschreibung	Freitext zur Dokumentation (maximal 1024 Zeichen). Wird in der Agentenliste angezeigt, aber nicht an das Sprachmodell gesendet.	Text
Modell	Das zu verwendende "AI Modell". Gehört das Modell zu einem anderen Mandanten als dem des Benutzers, wird stattdessen die globale Vorgabe verwendet (Warnung im Log).	Auswahl, Pflichtfeld
System Prompt	Zusätzliche Anweisungen an das Sprachmodell (maximal 4000 Zeichen). Sie werden an den von Webdesk erzeugten Standard-Prompt angehängt und ersetzen ihn nicht.	Text
Erlaubte Tools	Zweispaltige Auswahl "Verfuegbare Tools" / "Ausgewaehlte Tools" mit allen im System registrierten Tools. Die Auswahl schränkt die Tools ein, die dem Modell angeboten werden. Bleibt die Auswahl leer, gilt keine Einschränkung: Es werden alle Tools angeboten, die der Benutzer nach seinen Berechtigungen verwenden darf. Gespeichert werden die Tool-Namen kommagetrennt (maximal 4000 Zeichen).	Tool-Namen, leer = alle erlaubten

Welcher Agent wird verwendet?

Wählt der Benutzer in der Agent-Auswahl des Chats einen Agenten, wird dieser verwendet, sofern er öffentlich ist oder zum Mandanten des Benutzers gehört. Sonst weicht Webdesk auf den Standard-Agenten aus: den alphabetisch ersten Agenten des Mandanten, ersatzweise den alphabetisch ersten öffentlichen Agenten, ersatzweise den ersten zugänglichen Agenten.

Bleibt die Auswahl bei

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.

Field	Description	Possible value(s)
Name	Display name. It appears in the agent selection of the chat and determines the order (alphabetical).	text, required
Client	Binds the agent to a client. Without a client the agent is public. A user only sees and uses agents of his or her client and public agents. The selection dialog for the model shows public models and, if a client is selected here, the models of that client; without a client only public models.	client or empty (Public)
Description	Free text for documentation (maximum 1024 characters). It is shown in the agent list but not sent to the language model.	text
Model	The "AI Model" to use. If the model belongs to a different client than the user, the global default is used instead (warning in the log).	selection, required
System Prompt	Additional instructions for the language model (maximum 4000 characters). They are appended to the standard prompt generated by Webdesk and do not replace it.	text
Allowed Tools	Two-column selection "Available tools" / "Selected tools" containing all tools registered in the system. The selection restricts the tools offered to the model. If the selection is empty, there is no restriction: all tools that the user may use according to his or her permissions are offered. The tool names are stored comma-separated (maximum 4000 characters).	tool names, empty = all permitted

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)" (leerer Wertempty value), verwendet Webdesk einen internen Standard-Assistenten ohne Modell und ohne Tool-Einschränkung. Modell, Basis-URL und Schlüssel stammen dann ausschließlich aus den globalen Vorgaben, und es stehen alle Tools zur Verfügung, die der Benutzer nach seinen Berechtigungen verwenden darf. Schlägt der Aufruf in diesem Modus mit "Modell nicht gefunden" fehl 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), wiederholt Webdesk ihn einmal mit dem Standard-Agenten des Mandanten.

Achtung: Die Tool-Auswahl eines Agenten ist keine Sicherheitsgrenze. Jeder Benutzer kann in der Agent-Auswahl

• 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)" wählen, wodurch die Einschränkung des Agenten entfällt. Maßgeblich für die Sicherheit sind die Aktionsberechtigungen (siehe Berechtigungsprüfung).

Reihenfolge der Einstellungen (Fallback)

Webdesk ermittelt API-Schlüssel, Modellname und Basis-URL bei jeder Anfrage. Der erste nicht leere Wert der jeweiligen Liste gilt. Die Umgebungsvariablen und JVM-Parameter heißen unabhängig vom Anbieter 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 und and OPENAI_BASE_URL und haben Vorrang vor dem Systemparameter AiOptions.

Einstellung

Reihenfolge (erster nicht leerer Wert gewinnt)

Ergebnis, wenn nichts gesetzt ist

API-Schlüssel

Feld "API Schluessel" des Modells des Agenten

Umgebungsvariable

, and they take precedence over the system parameter AiOptions.

Feld

Setting	Order (first non-empty value wins)	Result if nothing is set
API key	Field "API Key" of the agent's model Environment variable OPENAI_API_KEY JVM parameter -Parameter -DOPENAI_API_KEY=<your-api-key> Systemparameter System parameter AiOptions.defaultAiApiKey	Kein Aufruf des Anbieters. Der Chat antwortet No call to the provider. The chat replies "AI chat fallback is active; no API key configured."
Modellname	Model name	Field "Model ID" des Modells des Agenten (bei Azure mit URL-Deployment: der Name aus der URL) Umgebungsvariable of the agent's model (for Azure with a deployment in the URL: the name from the URL) Environment variable OPENAI_MODEL JVM parameter -Parameter -DOPENAI_MODEL=... Systemparameter System parameter AiOptions.defaultAiModel (Standarddefault: gpt-4o) fest eingebauter Wert built-in value gpt-4o	gpt-4o
Basis- Base URL	Feld Field "Basis Base URL" des Modells des Agenten Umgebungsvariable of the agent's model Environment variable OPENAI_BASE_URL JVM parameter -Parameter -DOPENAI_BASE_URL=... Systemparameter System parameter AiOptions.defaultAiBaseUrl (Standarddefault: leer) fest eingebauter Wert empty) built-in value https://api.openai.com/v1	https://api.openai.com/v1

Das Feld des Modells wird nur berücksichtigt, wenn der Chat einen Agenten mit zugänglichem Modell verwendet. In allen anderen Fällen 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)", Modell eines fremden Mandanten) entfällt Schritt 1, und es wird mit dem Provider model of a different client) step 1 is skipped and the provider "OpenAI-kompatibel" und den globalen Vorgaben gearbeitet. Ist im Modell zwar ein Modellname, aber kein Schlüssel eingetragen, wird der Schlüssel nach Schritt 2 bis 4 bestimmt.

Systemparameter AiOptions

Die Bean AiOptions enthält die globalen Vorgaben. Sie gelten nur, wenn weder Modell noch Umgebungsvariable bzw. JVM-Parameter einen Wert liefern.

Eigenschaft

Erklärung

mögliche Wert(e)

defaultAiApiKey

Standard-API-Schlüssel als Fallback, wenn keine Umgebungsvariable und kein JVM-Parameter konfiguriert ist. Wird verschlüsselt gespeichert und in der Maske als Passwort dargestellt.

Text (Standard: leer)

defaultAiModel

Standard-Modellkennung als Fallback, wenn keine Umgebungsvariable und kein JVM-Parameter konfiguriert ist.

Text (Standard: gpt-4o)

defaultAiBaseUrl

Standard-Basis-URL als Fallback, wenn keine Umgebungsvariable und kein JVM-Parameter konfiguriert ist. Leer bedeutet

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.

Property	Description	Possible value(s)
defaultAiApiKey	Default API key used as fallback when no environment variable or JVM parameter is configured. Stored encrypted and displayed as a password in the mask.	text (default: empty)
defaultAiModel	Default model identifier used as fallback when no environment variable or JVM parameter is configured.	text (default: gpt-4o)
defaultAiBaseUrl	Default base URL used as fallback when no environment variable or JVM parameter is configured. Empty means https://api.openai.com/v1.	URL (Standarddefault: leerempty)

Werkzeugkatalog (Tools)

Tools sind im Programm festgelegt und können nicht über die Oberfläche angelegt werden. Sie werden von den Modulen Portal & Organisation

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), Zeiterfassung Time & Attendance (TA) und Projektzeiterfassung and Project Time Management (PTM) bereitgestellt. Alle Tools laufen im Namen des angemeldeten Benutzers: Die Tools . All tools run on behalf of the logged-in user: the "getMy..." liefern ausschließlich seine eigenen Daten, die übrigen Tools nur Daten, die er nach den unten beschriebenen Prüfungen sehen darf. Mit "Schreibend" sind Tools markiert, die Daten verändern.

Portal & Organisation

Tool

Zweck

Erforderliche Aktion (eine genügt)

searchColleagues

Sucht Kollegen im Mandanten nach Suchbegriff (Name, Mitarbeiter-ID, Kurzname, Organisationseinheit

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

Tool	Purpose	Required action (one is sufficient)
searchColleagues	Searches colleagues in the client by search term (name, employee ID, short name, organizational unit).	po_showPersons.act, po_searchPerson.act
findPersonsByName	Sucht Personen nach vollständigem oder teilweisem NamenSearches persons by full or partial name.	po_showPersons.act, po_searchPerson.act
getAllGroups	Alle Gruppen des Mandanten (Organisationseinheiten, Kostenstellen, Standorte, AbrechnungskreiseAll groups of the client (organizational units, cost centers, locations, billing circles).	po_showGroups.act
searchGroups	Sucht Gruppen nach Name oder KurznameSearches groups by name or short name.	po_showGroups.act
getPersonsAge	Alter einer Person (Parameter Age of a person (parameter personUid).	po_showPersons.act
getPersonsManager	Vorgesetzter einer Person (Standardrolle Manager of a person (default role Manager).	po_showPersons.act
getPersonsCompetence	Personen im Zuständigkeitsbereich einer Person (auch über deren GruppenPersons in the area of responsibility of a person (also via their groups).	po_showPersons.act
getPersonsGroups	Gruppen, denen eine Person zugeordnet istGroups a person is assigned to.	po_showPersons.act, po_showGroups.act, po_searchPerson.act
getPersonsOfGroup	Mitglieder einer Gruppe (Parameter Members of a group (parameter groupUid).	po_showGroups.act, po_showPersons.act, po_searchPerson.act

Zeiterfassung

Tool

Zweck

Erforderliche Aktion (eine genügt)

getMyOpenVacationDays

Offene Urlaubstage des laufenden Urlaubsjahres

Time & Attendance

Führt eine automatische Anwesenheitsbuchung (Kommen/Gehen) für den Benutzer mit dem gewählten Zeitgrund durch (Parameter timeEntryReasonId). Nach erfolgreicher Buchung lädt die Seite im Hintergrund neu. Der Aufruf erfolgt ohne Rückfrage durch Webdesk

Tool	Purpose	Required action (one is sufficient)
getMyOpenVacationDays	Open vacation days of the current vacation year.	ta_getJournalV2.act
getMyYearlyVacationDaysEntitlement	Jahresurlaubsanspruch Yearly vacation entitlement in Tagendays.	ta_getJournalV2.act
getMyPreviousVacationIntervals	Urlaubsintervalle der letzten 12 MonateVacation intervals of the last 12 months.	ta_getJournalV2.act, ta_doBooking.act
getMyWeeklyWorkingTime	In der laufenden Woche bereits gearbeitete StundenHours already worked in the current week.	ta_getJournalV2.act
getMyWeeklyTargetTime	Wöchentliche Soll-Stunden laut ZeitmodellWeekly target hours according to the time model.	ta_getJournalV2.act
getBookingsInTimeRange	Eigene Buchungen eines Tages (Parameter Own bookings of one day (parameter day).	ta_getJournalV2.act
getMyTodayBookings	Eigene Buchungen des heutigen TagesOwn bookings of today.	ta_getJournalV2.act
getAbsenceIntervals	Genehmigte vergangene und geplante eigene Abwesenheiten in einem Zeitraum (Parameter Approved past and planned own absences in a period (parameters from, to).	ta_getJournalV2.act, ta_getCalendar.act, ta_yearlyCalendar.act
listUpcomingAbsences	Eigene genehmigte künftige Abwesenheiten ab heute (Parameter daysAhead, Standard 90, höchstens 3650 TageOwn approved future absences from today (parameter daysAhead, default 90, maximum 3650 days).	ta_getJournalV2.act, ta_getCalendar.act, ta_yearlyCalendar.act
getTimeEntryReasons	Alle Zeitgründe des Mandanten, mit denen gebucht werden kann (Arbeit und AbwesenheitAll time entry reasons of the client that can be used for booking (work and absence).	ta_doBooking.act, ta_getAttendanceTableau.act
getAttendanceStateOfColleague	Anwesenheitsstatus einer Person (abwesend, anwesend, abwesend mit Grund, bucht nicht) samt letzter Buchungsmeldung (Parameter Attendance status of a person (absent, present, absent with reason, not booking) including the last booking message (parameter personUid).	ta_getAttendanceTableau.act
doBooking (Schreibend)	Writing)	Performs an automatic attendance booking (clock in/out) for the user with the chosen time entry reason (parameter timeEntryReasonId). After a successful booking the page reloads in the background. Webdesk does not ask for confirmation before the call.	ta_doBooking.act

Projektzeiterfassung

Tool

Zweck

Erforderliche Aktion (eine genügt)

getMyMonthlyEffortSummary

Monatsübersicht der eigenen Projektzeiten je Projekt (Parameter

Project Time Management

Tool	Purpose	Required action (one is sufficient)
getMyMonthlyEffortSummary	Monthly summary of own project times per project (parameters month, year).	ptm_editMonthlyTimeEfforts.act, ptm_editTimeEfforts.act
listMyOpenProjectAssignments	Projekte, auf die der Benutzer buchen und/oder Buchungen ändern darfProjects on which the user may book and/or change bookings.	ptm_editTimeEfforts.act, ptm_doProjectTimeBooking.act, ptm_editMonthlyTimeEfforts.act
searchProjects	Sucht Projekte nach Kurzname, Name oder Code und liefert nur Projekte, die der Benutzer verwenden darf (optional nur buchbareSearches projects by short name, name or code and returns only projects the user may use (optionally only bookable ones).	ptm_showProjects.act, ptm_chooseProjectDialog.act, ptm_editTimeEfforts.act

Das einzige schreibende Tool ist doBooking. Alle anderen Tools lesen nur.

Berechtigungsprüfung der Tools

Aktionsberechtigung (Angebot): Jedes Tool nennt eine oder mehrere erforderliche Aktionen. Dem Sprachmodell wird ein Tool nur angeboten, wenn der Benutzer für mindestens eine davon berechtigt ist; Berechtigungen auf abgeleitete Konfigurationen der Aktion zählen mit. Verweist ein Tool auf eine Aktion, die es im System nicht gibt, wird diese übersprungen (Warnung im Log); gibt es keine einzige bekannte Aktion, ist das Tool gesperrt. Tools von Modulen, deren Aktionen nicht vorhanden oder nicht berechtigt sind, stehen damit nicht zur Verfügung.

Einschränkung durch den Agenten: Danach wird die Liste auf die "Erlaubten Tools" des Agenten reduziert (nur wenn ein Agent ausgewählt und die Liste nicht leer ist).

Zielprüfung (Ausführung): Beim Aufruf prüft Webdesk alle Argumente, deren Name auf uid oder uids endet (z.B. personUid, groupUid), auf Berechtigung für das betreffende Objekt. Für jede genannte UID muss der Benutzer für mindestens eine der erforderlichen Aktionen für genau dieses Objekt berechtigt sein (Berechtigung auf Objektebene bzw. passende Konfiguration der Aktion für diese Person). Andernfalls erhält das Modell die Fehlermeldung

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." , und das Tool wird nicht ausgeführt.

Die Tools sind damit an die Berechtigungen des Benutzers gebunden. Fehler und Ablehnungen sind Teil der Tool-Anzeige im Chat

1. 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).

Schnittstellen Interfaces (REST)

Die Chat-Oberfläche kommuniziert mit Endpunkten unter The chat user interface communicates with endpoints under /rest/ai. Sie arbeiten immer im Namen des angemeldeten Benutzers.

Endpunkt

Zweck

Hinweise

They always work on behalf of the logged-in user.

Leere Nachrichten werden abgewiesenBefüllt die Agent-AuswahlNur Benutzername, Name und

Endpoint	Purpose	Notes
POST /rest/ai/chat	Sendet eine Nachricht (optional mit Agent, Konversation und Seitenkontext) und liefert Antwort, Tool-Aufrufe und Oberflächen-Effekte.	Sends a message (optionally with agent, conversation and page context) and returns the reply, tool calls and UI effects.	Empty messages are rejected.
GET /rest/ai/agents	Agenten des Mandanten und öffentliche Agenten, alphabetisch.	Agents of the client and public agents, alphabetically.	Fills the agent selection.
GET /rest/ai/mentions	Personen des Mandanten für die Erwähnung per @Benutzername.	Persons of the client for mentions via @username.	Only user name, name and UID.
GET /rest/ai/conversations	Eigene Konversationen Own conversations (Parameter parameters offset, limit; Standard default 50, höchstens maximum 200).	Nur eigene KonversationenOwn conversations only.
GET /rest/ai/conversations/{id}/messages	Nachrichten einer eigenen Konversation (Standard Messages of an own conversation (default 200, höchstens maximum 1000).	HTTP 404 , wenn die Konversation nicht dem Benutzer gehörtif the conversation does not belong to the user.
POST /rest/ai/conversations/{id}/title	Benennt eine eigene Konversation um (höchstens 255 ZeichenRenames an own conversation (maximum 255 characters).
GET /rest/ai/mcp/tools	Liste der Tools (Name, Beschreibung, Parameter), die der angemeldete Benutzer nach seinen Aktionsberechtigungen verwenden darf.	Agenten-Einschränkungen gelten hier nicht.	List of the tools (name, description, parameters) that the logged-in user may use according to his or her action permissions.	Agent restrictions do not apply here.
POST /rest/ai/mcp/tools/{name}	Führt ein Tool direkt ausExecutes a tool directly. Body: {"args": {...}} oder die Argumente unmittelbar als JSON-Objekt. Antwort or the arguments directly as a JSON object. Response: {"tool": ..., "result": ...}.	HTTP 404 (unbekanntes Toolunknown tool), 403 (Aktions- oder Zielberechtigung fehltaction or target permission missing), sonst otherwise 400.

Die mcp-Endpunkte sind eine einfache MCP-ähnliche Schnittstelle und nutzen dieselbe Berechtigungsprüfung wie der Chat, jedoch ohne Agenten und ohne Sprachmodell: Auch doBooking kann dort aufgerufen werden. Für interne Aufrufe aus der Oberfläche werden die REST-Zugriffsrechte der Aktion 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 und and POST) herangezogen; externe Aufrufer (z.B. mit API-Schlüssel) benötigen rollenbasierte REST-Zugriffsrechte.

Gesprächsverlauf

• Jede Konversation gehört genau einem Benutzer und seinem Mandanten; andere Benutzer können sie über die Schnittstellen nicht abrufen. Es gibt keine Administrationsmaske für Konversationen.
• Gespeichert werden Konversation (Titel, Besitzer, Mandant, gewählter Agent und Modell, Zeitstempel) und je Nachricht Rolle (Benutzer, Assistent, Tool-Ergebnis), Text, Tool-Name, Tool-Argumente, Tool-Ergebnis (JSON), Fehlertext, Agent, Modell und Zeitstempel (Tabelle AiConversationMessage). Tool-Ergebnisse enthalten damit auch die abgefragten Daten, z.B. Namen und E-Mail-Adressen von Kollegen.
• Der Titel wird aus den ersten 80 Zeichen der ersten Frage gebildet und kann umbenannt werden.
• Der Chat ruft für jede Nachricht das Sprachmodell mit dem bisherigen Verlauf auf (letzte 30 Nachrichten; ältere Teile werden bei Überschreiten eines geschätzten Umfangs von rund 3500 Token entfernt). Wird eine bestehende Konversation mit dem Kennzeichen "fresh" neu gestartet (Menü "Regenerate fresh" im Chat), werden ihre gespeicherten Nachrichten gelöscht.
• Im Code gibt es keine automatische Löschung oder Aufbewahrungsfrist und keine Löschfunktion für ganze Konversationen. Eine Bereinigung muss gegebenenfalls in der Datenbank erfolgen.
• Fehlermeldungen des Chats (siehe Fehlersuche) werden ebenfalls als Assistenten-Nachricht im Verlauf gespeichert.

Datenschutz: Was verlässt das System?

Bei jeder Chat-Anfrage sendet Webdesk an den konfigurierten Endpunkt (Basis-URL des Modells bzw. der globalen Vorgabe):

• Standard-Prompt mit dem aktuellen Zeitpunkt, dem Benutzernamen und Regeln für die Verwendung der Tools, ergänzt um den System Prompt des Agenten.
• Angaben zum angemeldeten Benutzer: UID, Benutzername, Vor- und Nachname, Mitarbeiter-ID, Gültigkeit (von/bis), Download-Adresse des Personenfotos, Sprache, TA-ID, Zeitzone, E-Mail-Adresse, Aktiv-Kennzeichen und Kurzname der Organisationseinheit.
• Seitenkontext der aktuell geöffneten Seite: Aktionsname, Menüpfad, Seitentitel, vollständige Seiten-URL, Typ der Aktion, Prozessdefinition sowie die Objekt-ID und URL-Parameter der Seite. Der Benutzer kann diesen Kontext im Panel über das Auge-Symbol ("Show shared context") einblenden.
• die Nachrichten des Benutzers samt Gesprächsverlauf (siehe oben) und die Ergebnisse aller aufgerufenen Tools (z.B. Personendaten von Kollegen, Buchungen, Abwesenheiten, Urlaubstage, Projektzeiten) sowie die Beschreibungen und Parameter der angebotenen Tools.

Der API-Schlüssel dient ausschließlich als Zugangsdaten für den konfigurierten Endpunkt. Die Verarbeitung beim Anbieter richtet sich nach dessen Bedingungen und liegt außerhalb von Webdesk; diese Seite trifft dazu keine Aussage.

Im Server-Log (Logger der Klasse 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) stehen auf Level INFO der Benutzername, der gewählte Anbieter mit Modell, Basis-URL und Agentenname sowie die Tool-Aufrufe mit Argumenten und Ergebnissen (jeweils auf 500 Zeichen gekürzt). Der API-Schlüssel wird nicht protokolliert.

Einschränkungsmöglichkeiten

Maßnahme

Wirkung

Aktion ai_assistant.act nicht vergeben

Der Benutzer sieht das Symbol nicht und erhält keinen Zugriff auf die Chat-Schnittstelle. Wirksamste Steuerung nach Benutzergruppen.

Lizenz ai nicht erwerben bzw. nicht einspielen

Das Modul steht nicht zur Verfügung.

Keinen API-Schlüssel hinterlegen (weder im Modell noch als Umgebungsvariable, JVM-Parameter oder Systemparameter)

Es erfolgt kein Aufruf an einen externen Anbieter; der Chat antwortet nur mit der Fehlermeldung.

Aktionsberechtigungen der Tools entziehen (z.B

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

Measure	Effect
Do not grant the action ai_assistant.act	The user does not see the icon and has no access to the chat interface. Most effective control per user group.
Do not purchase or install the licence ai	The module is not available.
Do not store an API key (neither in the model nor as environment variable, JVM parameter or system parameter)	No call to an external provider takes place; the chat only replies with the error message.
Withdraw the action permissions of the tools (e.g. ta_doBooking.act, po_showPersons.act)	Die zugehörigen Tools werden dem Modell nicht angeboten und sind auch über die Schnittstelle gesperrt. Dies ist die verbindliche Einschränkung.	Agenten mit Tool-Auswahl verwenden	Reduziert die angebotenen Tools und damit die übertragenen Daten für Benutzer, die den Agenten verwenden. Greift nicht, wenn der Benutzer The corresponding tools are not offered to the model and are also blocked via the interface. This is the binding restriction.
Use agents with a tool selection	Reduces the tools offered and thus the data transmitted for users who use the agent. Does not apply if the user chooses "Default agent (auto)" wählt.
Mandantenbindung von Modellen und Agenten	Begrenzt, welche Mandanten welchen Anbieter bzw. Zugang nutzen.
Datenbereinigung	Gespeicherte Konversationen bleiben bestehen, bis sie in der Datenbank entfernt werden.

Fehlersuche

Symptom	Ursache und Prüfung
Kein Assistent-Symbol in der Kopfzeile	Berechtigung für ai_assistant.act fehlt oder Lizenz ai fehlt bzw. das Modul wurde nicht geladen.
.
Client binding of models and agents	Limits which clients use which provider or access.
Data cleanup	Stored conversations remain until they are removed in the database.

Troubleshooting

Die Basis-URL enthält nicht

Symptom	Cause and check
No assistant icon in the header	Permission for ai_assistant.act is missing, or the licence ai is missing or the module was not loaded.
"AI chat fallback is active; no API key configured."	In keiner Stufe der Reihenfolge ist ein API-Schlüssel gesetzt. Beachten, dass Umgebungsvariable und JVM-Parameter vor dem Systemparameter gelten und dass im Modus No API key is set at any stage of the order. Note that the environment variable and JVM parameter come before the system parameter, and that in the mode "Default agent (auto)" das Modellfeld nicht berücksichtigt wirdthe model field is not considered.
"AI chat fallback is active; error during model invocation."	Der Aufruf des Anbieters ist fehlgeschlagen (falscher Schlüssel, Modellname, Basis-URL oder Deployment, Netzwerk, bei Azure OpenAI fehlende Basis-URL). Die Ursache steht im Server-Log The call to the provider failed (wrong key, model name, base URL or deployment, network, missing base URL for Azure OpenAI). The cause is in the server log ("AiChatService error"); die Zeile the line "AI model resolved" zeigt Anbietershows provider, Modellmodel, Basis-URL und Agentbase URL and agent.
"Model returned no text and no tool calls..."	Das Modell bzw. der Anbieter unterstützt keine Tool-Aufrufe für diese Anfrage. Anderes Modell wählen oder im Agenten die Tools reduzieren.	Ein erwartetes Tool wird nicht verwendet	Aktionsberechtigung für das Tool fehlt, das Tool ist beim gewählten Agenten nicht in den "Erlaubten Tools", oder die Zielprüfung lehnt die UID ab The model or provider does not support tool calls for this request. Choose a different model or reduce the tools in the agent.
An expected tool is not used	The action permission for the tool is missing, the tool is not among the "Allowed Tools" of the selected agent, or the target check rejects the UID ("Tool not permitted for requested target.").
Routing -Praeferenz ohne Wirkung	preference has no effect	The base URL does not contain cortecs.ai; der Wert wird ignoriertthe value is ignored.