(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Setup on new Namespace

This guide describes all steps required to configure a new Kubernetes namespace for the UPW-UI application, specifically for the Aptean AI Studio (AIS) integration and the Agent Management feature. This enables the intigration of new or existing AI Agents from Aptean AI studio in any namespace.

The intigration requires three consul keys, as explained in the table. They are explained in more detail below.

Consul Key Required Purpose
upw-ui/aptean-agents no (managed via UI) list of registered AI agents — created and maintained through the Agent Management UI
upw-ui/app-studio-config yes Aptean IAM credentials + datasource IDs for AIS session management
config/upw-ui/features yes feature flags controlling which application features are enabled

upw-ui/app-studio-config

Purpose

This key provides:

The application reads this key at runtime via ApteanIamService. If the key is missing or malformed, all AI agent chat functionality will be unavailable.

Value Format

The value must be a JSON object with the following format.

Field Required Endpoint Details
client_id yes - OAuth2 client ID used to authenticate against Aptean IAM
client_secret yes - OAuth2 client secret
grant_type no - OAuth2 grant type. Defaults to client_credentials if omitted
token_data_source_id yes POST https://appcentral-int.aptean.com/iam/auth/realms/aptean/protocol/openid-connect/token proxies the Aptean IAM token endpoint (application/x-www-form-urlencoded)
sessions_datasource_id yes* GET https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/sessions fetches a single AIS session by flow_id
messages_datasource_id yes* GET https://appcentral-int.aptean.com/ais/api/v1/monitor/messages fetches messages by flow_id + session_id
delete_session_datasource_id yes* DELETE https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/session/{sessionId} deletes a session by sessionId (path param)
patch_session_datasource_id yes* PATCH https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/session/{sessionId} renames a session (sessionId path param, new_session_id query param)

*Required for full agent chat functionality (session management). The app will fall back gracefully but session-related features will not work.

Example:

{
  "client_id": "<oauth2-client-id>",
  "client_secret": "<oauth2-client-secret>",
  "grant_type": "client_credentials",
  "token_data_source_id": "cc9d627c-b0ec-364a-82da-81f95e85842b",
  "sessions_datasource_id": "f49de3c9-00ba-3457-80de-fd0df0b85740",
  "messages_datasource_id": "4c59e7d2-ad68-35b1-928e-d1387312bd78",
  "delete_session_datasource_id": "d5239ee1-3b9d-32dd-8b22-96f829561692",
  "patch_session_datasource_id": "5405342b-662e-3507-9037-e4491678eb7a" 
}

upw-ui/aptean-agents

Purpose

Stores the list of AI agents available in the chat interface. This key is managed automatically by the Agent Management UI — you do not need to create it manually. It is created/updated whenever an agent is added or removed through the UI.

Value Format

The value must be a JSON object with the following format.

Field Required Description
agentName yes display name shown in the agent selector
agentApiKey yes AIS API key (x-api-key header) sent with every chat request to this agent
agentDatasourceId yes ID of the platform datasource that proxies the AIS chat endpoint for this agent
flowId yes AIS Flow ID used to scope sessions and messages to this specific flow
description no short description displayed in the agent selector
exampleQuestions no up to 3 example questions surfaced in the UI to guide users
createdBy no username of the person who registered the agent

Example:

{
  "agents": [
    {
      "agentName": "My Agent",
      "agentApiKey": "<ais-api-key-for-this-agent>",
      "agentDatasourceId": "<platform-datasource-id>",
      "flowId": "<ais-flow-id>",
      "description": "Optional description shown to users",
      "exampleQuestions": [
        "What can you help me with?",
        "Show me the latest data"
      ],
      "createdBy": "user@example.com"
    }
  ]
}

upw-ui/aptean-agents

Purpose

Controls which application features are enabled in the namespace. The application reads this key at startup to toggle functionality on or off without requiring a redeployment.

Value Format

The value is a flat JSON object of feature flag names mapped to booleans. Like other Consul keys, it must be base64-encoded when written via the API.

Flag Default Description
platform-admin-app-context-feature true enables Platform Administration app context features
dynamic-dialog-in-app-features true enables dynamic dialogs within application features
user-overview-in-namespace-management false shows user overview inside namespace management
custom-function-ai-assistance true enables AI assistance for custom functions
chat-panel true enables the AI agent chat panel in the UI
user-view-state true persists and restores user view state
mcp-datasources true enables MCP (Model Context Protocol) datasource support

Example:

{
  "platform-admin-app-context-feature": true,
  "dynamic-dialog-in-app-features": true,
  "user-overview-in-namespace-management": false,
  "custom-function-ai-assistance": true,
  "chat-panel": true,
  "user-view-state": true,
  "mcp-datasources": true
}

Summary Checklist for a New Namespace