FlowX Events Gateway setup

This guide will walk you through the process of setting up the events-gateway service.

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

Kafka topics related to process instances

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

Kafka topics related to process commands

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

Kafka topics related to user 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_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 could be set in order to 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:

1. 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
2. Verify keep-alive configuration on your load balancer and ingress controller
3. Review the EVENTS_SSE_CLEANUP_MAXAGEMINS setting — ensure it is not set too low for your use case
4. 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:

1. Verify Kafka consumer configuration — check that the consumer group IDs match expected values
2. Confirm that the KAFKA_TOPIC_EVENTSGATEWAY_PATTERN matches the topics being published to by the process engine
3. Check Kafka consumer lag using your monitoring tools to identify backpressure issues
4. 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:

1. Check the Redis connection — verify SPRING_DATA_REDIS_HOST and SPRING_DATA_REDIS_PORT are correct and the Redis instance is responsive
2. Review EVENTS_REDIS_FREQUENCYMILLIS — lower values reduce latency but increase Redis load
3. Check Kafka partition configuration — ensure sufficient partitions for your consumer thread count
4. 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:

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

---

Related resources

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