FlowX Events Gateway setup

Infrastructure prerequisites

Before proceeding with the setup, ensure that the following components have been set up:

Redis
Kafka

Configuration

Configuring Kafka

Set the following Kafka-related configurations using environment variables:

Configuration Parameter	Default Value	Description
`KAFKA_BOOTSTRAP_SERVERS`	`localhost:9092`	Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)
`KAFKA_SECURITY_PROTOCOL`	`PLAINTEXT`	Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`)
`KAFKA_MESSAGE_MAX_BYTES`	`52428800`	Maximum message size in bytes (50 MB)
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	`10`	Retry interval for auth exceptions (seconds)

OAuth authentication (when using SASL_PLAINTEXT)

Environment Variable	Description	Default Value
`KAFKA_OAUTH_CLIENT_ID`	OAuth client ID	`kafka`
`KAFKA_OAUTH_CLIENT_SECRET`	OAuth client secret	`kafka-secret`
`KAFKA_OAUTH_TOKEN_ENDPOINT_URI`	OAuth token endpoint	`kafka.auth.localhost`

When using the kafka-auth profile, the security protocol will automatically be set to SASL_PLAINTEXT and the SASL mechanism will be set to OAUTHBEARER.

Topic naming configuration

Configuration Parameter	Default Value	Description
`KAFKA_TOPIC_NAMING_PACKAGE`	`ai.flowx.`	Package prefix for topic names
`KAFKA_TOPIC_NAMING_ENVIRONMENT`		Environment segment for topic names
`KAFKA_TOPIC_NAMING_VERSION`	`.v1`	Version suffix for topic names
`KAFKA_TOPIC_NAMING_SEPARATOR`	`.`	Primary separator for topic names
`KAFKA_TOPIC_NAMING_SEPARATOR2`	`-`	Secondary separator for topic names

Group IDs

The configuration parameters “KAFKA_CONSUMER_GROUPID_*” are used to set the consumer group name for Kafka consumers that consume messages from topics. Consumer groups in Kafka allow for parallel message processing by distributing the workload among multiple consumer instances. By configuring the consumer group ID, you can specify the logical grouping of consumers that work together to process messages from the same topic, enabling scalable and fault-tolerant message consumption in your Kafka application.

Configuration Parameter	Default value	Description
`KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_MESSAGE`	`engine-commands-message`	Consumer group ID for processing engine commands messages
`KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_DISCONNECT`	`engine-commands-disconnect`	Consumer group ID for processing engine commands disconnect messages
`KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_CONNECT`	`engine-commands-connect`	Consumer group ID for processing engine commands connect messages
`KAFKA_CONSUMER_GROUPID_TASKCOMMANDS_MESSAGE`	`task-commands-message`	Consumer group ID for processing task commands messages
`KAFKA_CONSUMER_GROUPID_PROCESSCOMMANDS_MESSAGE`	`process-commands-message`	Consumer group ID for processing process commands messages
`KAFKA_CONSUMER_GROUPID_GENERICCOMMANDS`	`generic-commands-message`	Consumer group ID for processing generic commands messages
`KAFKA_CONSUMER_GROUPID_USERBROADCASTCOMMANDS`	`user-broadcast-commands-message`	Consumer group ID for processing user broadcast commands messages

Threads

The configuration parameters “KAFKA_CONSUMER_THREADS_*” are utilized to specify the number of threads assigned to Kafka consumers for processing messages from topics. These parameters allow you to fine-tune the concurrency and parallelism of your Kafka consumer application, enabling efficient and scalable message consumption from Kafka topics.

Configuration Parameter	Default value	Description
`KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_MESSAGE`	`10`	Number of threads for processing engine commands messages
`KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_DISCONNECT`	`5`	Number of threads for processing engine commands disconnect messages
`KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_CONNECT`	`5`	Number of threads for processing engine commands connect messages
`KAFKA_CONSUMER_THREADS_TASKCOMMANDS`	`10`	Number of threads for task commands messages
`KAFKA_CONSUMER_THREADS_PROCESSCOMMANDS`	`10`	Number of threads for processing process commands messages
`KAFKA_CONSUMER_THREADS_GENERICCOMMANDS`	`10`	Number of threads for processing generic commands messages
`KAFKA_CONSUMER_THREADS_USERBROADCASTCOMMANDS`	`10`	Number of threads for processing user broadcast commands messages

Events Gateway pattern

Configuration Parameter	Default value	Description
`KAFKA_TOPIC_EVENTSGATEWAY_PATTERN`	`ai.flowx.eventsgateway.receive.*`	Pattern for Events Gateway communication

Configuration Parameter	Default value	Description
`KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_MESSAGE`	`ai.flowx.eventsgateway.engine.commands.message.v1`	Topic for engine commands messages
`KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_DISCONNECT`	`ai.flowx.eventsgateway.engine.commands.disconnect.v1`	Topic for engine commands disconnect messages
`KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_CONNECT`	`ai.flowx.eventsgateway.engine.commands.connect.v1`	Topic for engine commands connect messages

Configuration Parameter	Default value	Description
`KAFKA_TOPIC_EVENTSGATEWAY_PROCESS_IN_MESSAGE`	`ai.flowx.eventsgateway.process.commands.message.v1`	Topic for process commands messages

Configuration Parameter	Default value	Description
`KAFKA_TOPIC_EVENTSGATEWAY_USERMESSAGES_IN_MESSAGE`	`ai.flowx.core.designer.notification.user.v1`	Topic for user notification messages

Configuring authorization & access roles

Events Gateway validates incoming tokens with the JWT public key mechanism:

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Token validation mechanism (JWT public key validation)	`jwt-public-key`
`SECURITY_OAUTH2_BASESERVERURL`	Base URL of the Keycloak server
`SECURITY_OAUTH2_SAREALM`	Service-accounts realm ID	`00000002-0002-4002-8002-000000000002`
`FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`	URL of the organization-manager service, used by the security library	`http://organization-manager:80`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`	Anonymous service account client ID, used for anonymous runtime access	`flowx-anonymous-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`	Anonymous service account client secret

Upgrading from 5.1.x? Remove the legacy opaque-token env vars: SECURITY_OAUTH2_REALM, SECURITY_OAUTH2_CLIENT_CLIENTID, and SECURITY_OAUTH2_CLIENT_CLIENTSECRET. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the authentication and IAM migration guide for the full list.

Service communication

Environment Variable	Description	Default Value
`FLOWX_URLS_RUNTIMEMANAGER`	Base URL of the Runtime Manager service	`http://runtime-manager/`

Redis configuration

FlowX Events Gateway uses Redis for real-time message distribution. The process engine sends messages to the events-gateway, which is responsible for sending them to Redis. Events Gateway supports all Redis deployment modes (Standalone, Sentinel, and Cluster). For detailed Redis configuration including all deployment modes and parameters, see the Redis Configuration guide.

Quick reference

Common Redis configuration parameters:

Configuration Parameter	Description	Example Value
`SPRING_DATA_REDIS_HOST`	Redis server hostname (Standalone mode)	`localhost`
`SPRING_DATA_REDIS_PORT`	Redis server port (Standalone mode)	`6379`
`SPRING_DATA_REDIS_PASSWORD`	Redis authentication password	`yourpassword`
`SPRING_DATA_REDIS_SENTINEL_MASTER`	Sentinel master name (Sentinel mode)	`mymaster`
`SPRING_DATA_REDIS_SENTINEL_NODES`	Sentinel nodes (Sentinel mode)	`host1:26379,host2:26379`
`SPRING_DATA_REDIS_CLUSTER_NODES`	Cluster nodes (Cluster mode)	`host1:6379,host2:6379`

For complete Redis configuration details including Sentinel mode, Cluster mode, SSL/TLS setup, and troubleshooting, refer to the Redis Configuration guide.

Events

This configuration helps manage how event data is stored and accessed in Redis.

Configuration Parameter	Default	Description
`EVENTS_REDIS_MODE`	blocking	How the events gateway reads real-time events from Redis. `blocking` holds a Redis connection open per read; `polling` checks for new events at the `EVENTS_REDIS_FREQUENCYMILLIS` interval instead
`EVENTS_REDIS_FREQUENCYMILLIS`	300	Time interval (in milliseconds) between Redis queries by the events gateway to check for new messages
`EVENTS_REDIS_TTLHOURS`	4	Sets the time-to-live for events in Redis to 4 hours

SSE cleanup configuration

Configure how Server-Sent Events (SSE) connections are cleaned up:

Configuration Parameter	Default	Description
`EVENTS_SSE_CLEANUP_INTERVALMINUTES`	`5`	Interval in minutes between SSE connection cleanup cycles
`EVENTS_SSE_CLEANUP_MAXAGEMINUTES`	`10`	Maximum age in minutes before an inactive SSE connection is removed

Configuring logging

The following environment variables control log levels:

Configuration Parameter	Description
`LOGGING_LEVEL_ROOT`	Logging level for the root Spring Boot microservice logs
`LOGGING_LEVEL_APP`	Logging level for the application-level logs

Ingress and CORS

The Events Gateway is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because Server-Sent Events use the same path on the backend as on the client.

Service routes

Host group	External path	Backend receives	Notes
admin	`/api/events`	`/api/events/...`	Path preserved
public	`/api/events`	`/api/events/...`	Path preserved

Paths are set through services.events-gateway.ingress.admin.path / services.events-gateway.ingress.public.path (or the corresponding gateway.<key>.paths) in the chart values. No rewrite is applied because Events Gateway expects the same path on the backend.

Server-Sent Events are long-lived HTTP connections. If you front Events Gateway with a custom ingress controller or reverse proxy, set generous read timeouts (300s+) and disable response buffering on the SSE path.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOWORIGIN`	Comma-separated list of origins allowed to open SSE connections from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that subscribes to events.	`-`

Allowed methods, allowed headers, and credential handling are baked into the service’s application.yaml with safe defaults for SSE traffic. Override these only if you have a non-standard requirement. For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the ingress configuration guide.

Troubleshooting

Common issues

SSE connections dropping unexpectedly

Symptoms: Clients lose real-time updates intermittently, SSE connections close after a timeout period.Solutions:

Check your ingress timeout settings — SSE connections require longer timeouts than standard HTTP requests. Set proxy-read-timeout and proxy-send-timeout to at least 3600 seconds
Verify keep-alive configuration on your load balancer and ingress controller
Review the EVENTS_SSE_CLEANUP_MAXAGEMINUTES setting — ensure it is not set too low for your use case
Check for network proxies or firewalls that may terminate long-lived connections

Events not reaching the UI

Symptoms: Process updates do not appear in the Designer or end-user interface, despite successful process execution.Solutions:

Verify Kafka consumer configuration — check that the consumer group IDs match expected values
Confirm that the KAFKA_TOPIC_EVENTSGATEWAY_PATTERN matches the topics being published to by the process engine
Check Kafka consumer lag using your monitoring tools to identify backpressure issues
Ensure the events-gateway service has network access to Kafka brokers

High latency on events

Symptoms: Noticeable delay between process execution and UI updates.Solutions:

Check the Redis connection — verify SPRING_DATA_REDIS_HOST and SPRING_DATA_REDIS_PORT are correct and the Redis instance is responsive
Review EVENTS_REDIS_FREQUENCYMILLIS — lower values reduce latency but increase Redis load
Check Kafka partition configuration — ensure sufficient partitions for your consumer thread count
Monitor Kafka consumer thread counts (KAFKA_CONSUMER_THREADS_*) and increase if threads are saturated

WebSocket connection failures

Symptoms: Browser console shows WebSocket or SSE connection errors, CORS-related error messages.Solutions:

Verify CORS settings in your ingress configuration allow the Designer and application domains
Ensure the ingress controller supports WebSocket upgrades and SSE connections
Check that the ingress path pattern /api/events(/|$)(.*)(/|$)(.*) is correctly configured
Confirm that the events-gateway service is reachable from the ingress controller

Ingress Configuration

Configure routing, CORS, and SSE-specific ingress settings

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

FlowX Engine Setup

Configure the process engine that publishes events to the gateway

Microservices

AI Platform

Plugins

Observability

Access management

FlowX Events Gateway setup

Infrastructure prerequisites

Configuration

Configuring Kafka

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Group IDs

Threads

Events Gateway pattern

Configuring authorization & access roles

Service communication

Redis configuration

Quick reference

Events

SSE cleanup configuration

Configuring logging

Ingress and CORS

Service routes

CORS configuration

Troubleshooting

Common issues

Ingress Configuration

Redis Configuration

FlowX Engine Setup

​Infrastructure prerequisites

​Configuration

​Configuring Kafka

​OAuth authentication (when using SASL_PLAINTEXT)

​Topic naming configuration

​Group IDs

​Threads

​Events Gateway pattern

​Kafka topics related to process instances

​Kafka topics related to process commands

​Kafka topics related to user messages

​Configuring authorization & access roles

​Service communication

​Redis configuration

​Quick reference

​Events

​SSE cleanup configuration

​Configuring logging

​Ingress and CORS

​Service routes

​CORS configuration

​Troubleshooting

​Common issues

​Related resources

Ingress Configuration

Redis Configuration

FlowX Engine Setup

Infrastructure prerequisites

Configuration

Configuring Kafka

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Group IDs

Threads

Events Gateway pattern

Kafka topics related to process instances

Kafka topics related to process commands

Kafka topics related to user messages

Configuring authorization & access roles

Service communication

Redis configuration

Quick reference

Events

SSE cleanup configuration

Configuring logging

Ingress and CORS

Service routes

CORS configuration

Troubleshooting

Common issues

Related resources