FlowX Advancing Controller setup

This guide provides step-by-step instructions to help you configure and deploy the Advancing Controller effectively.

Infrastructure prerequisites

Before setting up the Advancing Controller, ensure the following components are properly set up:

• FlowX.AI Engine Deployment: The Advancing Controller depends on the FlowX Engine and must be deployed in the same environment. Refer to the FlowX Engine setup guide for more information on setting up the Engine.
• Database Instance: The Advancing Controller uses a PostgreSQL or Oracle Database instance as its database.

---

Dependencies

Ensure the following dependencies are met:

• Database: Properly configured database instance.
• Datasource: Configuration details for connecting to the database.
• FlowX.AI Engine: Must be set up and running. Refer to the FlowX Engine setup guide.

Database compatibility

The Advancing Controller supports both PostgreSQL and Oracle databases. However, the FlowX.AI Engine and the Advancing Controller must be configured to use the same type of database at any given time. The FlowX.AI Engine employs two databases: one shared with the FlowX.AI Admin microservice for process metadata and instances, and the other dedicated to advancement.

Mixing PostgreSQL and Oracle Database is not supported; both databases must be of the same type.

---

Database configuration

PostgreSQL

A basic PostgreSQL configuration for Advancing.

If the parallel advancing configuration already exists, you must reset the ‘advancing’ database by executing the SQL command DROP DATABASE advancing;. Once the database has been dropped, the Liquibase script will automatically re-enable it.

---

Configuration

The Advancing Controller uses a PostgreSQL or an Oracle database as a dependency.

• Ensure that the user, password, connection link, and database name are correctly configured. If these details are not configured correctly, errors will occur at startup.
• The datasource is configured automatically via a Liquibase script inside the engine. All updates will include migration scripts.

Configuring datasource

If you need to change the datasource configuration detail, you can use the following environment variables:

Variable	Description	Default Value
SPRING_DATASOURCE_URL	JDBC URL for database connection	jdbc:postgresql://postgresql:5432/advancing
SPRING_DATASOURCE_DRIVERCLASSNAME	JDBC driver class name	org.postgresql.Driver
SPRING_DATASOURCE_USERNAME	Database username	postgres
SPRING_DATASOURCE_PASSWORD	Database password	[your-secure-password]
SPRING_JPA_DATABASE	Database type (accepted values: oracle or postgresql)	postgresql
SPRING_JPA_SHOWSQL	Toggle SQL query logging	false
SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULT_SCHEMA	Default database schema (❗️only for Oracle DBs)	public
SPRING_LIQUIBASE_CHANGELOG	Path to Liquibase changelog for database migrations	classpath:config/liquibase/master.xml

It’s important to keep in mind that the Advancing Controller is tightly integrated with the FlowX.AI Engine. Therefore, it is crucial to ensure that both the Engine and the Advancing Controller are configured correctly and are in sync.

---

Health monitoring

Variable	Description	Default Value
MANAGEMENT_HEALTH_DB_ENABLED	Enable database health checks	true

---

Troubleshooting

Common issues

Process instances stuck and not advancing

Symptoms: Process instances remain in a pending state and do not advance to the next node.

Solutions:

1. Check Kafka connectivity and verify that the Advancing Controller can reach the Kafka brokers
2. Review the Advancing Controller logs for errors or warnings related to message consumption
3. Monitor consumer group lag to determine if messages are accumulating without being processed
4. Verify that the FlowX Engine is running and responsive

Advancing Controller fails to start

Symptoms: The service crashes or exits during startup with connection errors.

Solutions:

1. Verify the PostgreSQL (or Oracle) connection string and credentials are correct
2. Check that the Kafka broker configuration is valid and the brokers are reachable
3. Ensure the PostgreSQL (or Oracle) database is accessible and the advancing database exists
4. Review the Liquibase migration logs for schema issues

Timeout errors during token advancement

Symptoms: Logs show timeout exceptions when advancing tokens between nodes.

Solutions:

1. Review process complexity — deeply nested subprocesses or large parallel gateways may require longer timeouts
2. Monitor Kafka response times to identify broker-side latency
3. Verify that downstream services responding via Kafka are healthy and not overloaded

High CPU usage

Symptoms: The Advancing Controller pod shows consistently high CPU utilization.

Solutions:

1. Check thread pool settings and reduce concurrency if the system is over-provisioned
2. Monitor the number of concurrent process instances being advanced
3. Review Kafka consumer configuration — a high number of partitions with aggressive polling can increase CPU load
4. Consider scaling horizontally by adding additional replicas

---

Related resources

Advancing Controller

Learn how the Advancing Controller manages process instance progression

FlowX Engine Setup

Configure the FlowX Engine that the Advancing Controller depends on

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes