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

Set the following environment variables to connect to the identity management platform:

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Security type	`oauth2`
`SECURITY_OAUTH2_BASESERVERURL`	Base URL of the OAuth2 server
`SECURITY_OAUTH2_REALM`	OAuth2 realm name
`SECURITY_OAUTH2_CLIENT_CLIENT_ID`	Client ID for token introspection
`SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`	Client secret for token introspection

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`	polling	How the events gateway reads real-time events from Redis. `polling` checks for new events at the `EVENTS_REDIS_FREQUENCYMILLIS` interval; `blocking` holds a Redis connection open per read. Defaults to `polling` starting with 5.1.10 for Redis connection stability
`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

New in v5.5.0

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

Configuration Parameter	Default	Description
`EVENTS_SSE_CLEANUP_INTERVALMINS`	`5`	Interval in minutes between SSE connection cleanup cycles
`EVENTS_SSE_CLEANUP_MAXAGEMINS`	`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 configuration

The Events Gateway service uses a specialized ingress configuration for Server-Sent Events (SSE). For complete setup instructions, see the Ingress Configuration Guide. Service-specific values for Events Gateway:

Ingress name: events-gateway-admin
Service path: /api/events(/|$)(.*)(/|$)(.*)
Service name: events-gateway
Rewrite target: /api/events/$2
Fx-Workspace-Id: Not required (SSE exception)

Events Gateway does not require the Fx-Workspace-Id header because it handles real-time SSE connections with different security requirements. See the Events Gateway exception for details.

Complete Ingress Configuration

View the Events Gateway-specific ingress pattern in the centralized 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_MAXAGEMINS 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

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

Redis configuration

Quick reference

Events

SSE cleanup configuration

Configuring logging

Ingress configuration

Complete Ingress 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

​Redis configuration

​Quick reference

​Events

​SSE cleanup configuration

​Configuring logging

​Ingress configuration

Complete Ingress 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

Redis configuration

Quick reference

Events

SSE cleanup configuration

Configuring logging

Ingress configuration

Troubleshooting

Common issues

Related resources