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:

• IAM credentials used to obtain a bearer token from Aptean IAM (via OAuth2 client_credentials flow).
• Datasource IDs that point to platform datasources used for AIS session and message operations. All datasources will be providen automatically.

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

• Obtain Aptean IAM credentials (client_id, client_secret) for the namespace.
• Identify or create the platform datasource IDs for each AIS endpoint (token, session, sessions list, messages, delete, patch).
• Create Consul key upw-ui/app-studio-config with the base64-encoded JSON payload.
• Verify the key is readable: open the app, open browser DevTools, confirm no Missing Consul key upw-ui/app-studio-config errors appear in the console.
• Create Consul key config/upw-ui/features with the desired feature flags JSON.
• Register at least one agent via the Agent Management UI.