Integration Designer setup

Configuration

Core service configuration

Environment variable	Description	Default value
`LOGGING_LEVEL_APP`	Application logging level	`INFO`

Service communication

Environment variable	Description	Default value
`FLOWX_CMS_BASEURL`	Base URL for the CMS service	`http://cms-core:80`
`FLOWX_NOSQLDBRUNNER_BASEURL`	Base URL for the NoSQL DB Runner service	`http://nosql-db-runner:80`
`FLOWX_DOCUMENTPLUGIN_BASEURL`	Base URL for the Document Plugin service	`http://document-plugin:80`
`FLOWX_WEBHOOKGATEWAY_BASEURL`	Base URL for the Webhook Gateway service	`http://webhook-gateway:80`
`FLOWX_WEBCRAWLER_BASEURL`	Base URL for the web-crawler service (Web Page Extractor node)	`http://web-crawler:80`
`FLOWX_ADMIN_BASEURL`	Base URL for the Admin service	`http://admin:80`
`FLOWX_EMAILGATEWAY_BASEURL`	Base URL for the Email Gateway service	`http://email-gateway:80`
`FLOWX_NOTIFICATIONPLUGIN_BASEURL`	Base URL for the Notification Plugin service	`http://notification-plugin:80`
`FLOWX_DATAMODEL_BASEURL`	Base URL for the Data Model service	`http://admin:80`
`FLOWX_DOCPARSER_BASEURL`	Base URL for the Document Parser service	`http://doc-parser:80`
`FLOWX_SPEECHTOTEXT_BASEURL`	Base URL for the Speech-to-Text service	`http://speech-to-text:80`
`FLOWX_FILEGATEWAY_BASEURL`	Base URL for the File Gateway service, used by the File Storage data source	`http://file-gateway:80`

Environment variable	Description	Default value
`FLOWX_DATAPRIVACY_BASEURL`	Base URL for the Data Privacy service used by the Personal Information Guard on AI workflow nodes (input/output PII detection and redaction).	`http://data-privacy:80`
`FLOWX_DATAPRIVACY_TIMEOUTSECONDS`	Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker.	`60`

Storage configuration

S3 storage for files in Integration Designer.

Variable	Default Value	Description
`APPLICATION_FILESTORAGE_TYPE`	`s3`	🆕 Storage type
`APPLICATION_FILESTORAGE_PARTITIONSTRATEGY`	`NONE`	🆕 Partition strategy
`APPLICATION_FILESTORAGE_DELETIONSTRATEGY`	`delete`	🆕 Deletion strategy
`APPLICATION_FILESTORAGE_S3_ENABLED`	`true`	🆕 S3 enabled
`APPLICATION_FILESTORAGE_S3_SERVERURL`	`http://minio:9000`	S3 server URL
`APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED`	`false`	S3 encryption enabled
`APPLICATION_FILESTORAGE_S3_ACCESSKEY`	`minio`	S3 access key
`APPLICATION_FILESTORAGE_S3_SECRETKEY`	`minio123`	S3 secret key
`APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`	`workflows-bucket`	🆕 S3 bucket prefix

Redis

Integration Designer uses Redis for caching workflow execution data. Cache-specific configuration:

Variable	Description	Default Value
`SPRING_CACHE_TYPE`	Cache type	`redis`
`SPRING_CACHE_REDIS_KEYPREFIX`	Cache key prefix	`flowx:core:cache:integration-designer:`
`SPRING_CACHE_REDIS_TIMETOLIVE`	Cache time to live	`5000000`

Redis connection: Quick reference:

Environment Variable	Description	Example Value	Status
`SPRING_DATA_REDIS_HOST`	Redis server hostname	`localhost`	Recommended
`SPRING_DATA_REDIS_PORT`	Redis server port	`6379`	Recommended
`SPRING_DATA_REDIS_PASSWORD`	Redis authentication password	-	Recommended
`REDIS_TTL`	Cache TTL in milliseconds	`5000000`	Optional

Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.

For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

WebClient configuration

Integration Designer interacts with various APIs, some of which return large responses. To handle such cases efficiently, the FlowX WebClient buffer size must be configured to accommodate larger payloads, especially when working with legacy APIs that do not support pagination.

Environment variable	Description	Default value
`FLOWX_WEBCLIENT_BUFFERSIZE`	Buffer size (in bytes) for FlowX WebClient	`52428800` (50MB)
`FLOWX_WEBCLIENT_BUFFERSIZEFORDOCUMENTPLUGIN`	Buffer size for Document Plugin calls	`20971520` (20MB)
`FLOWX_WEBCLIENT_COMPRESSIONENABLED`	Enable response compression	`true`

Workflow execution configuration

Environment variable	Description	Default value
`FLOWX_WORKFLOW_MAXEXECUTEDNODES`	Maximum number of nodes a workflow can execute	`1000`
`FLOWX_WORKFLOW_MAXSUBWORKFLOWDEPTH`	Maximum nesting depth for subworkflows	`100`
`FLOWX_SCRIPTENGINE_ALLOWUNSAFEEVAL`	Allow unsafe eval in workflow scripts	`false`

AI service configuration

Environment variable	Description	Default value
`FLOWX_AISERVICE_NODERUNNERTIMEOUTSECONDS`	Timeout (seconds) for how long an AI workflow node may run before it is cut off. Increase for Custom Agent nodes with many tool calls.	`600`

FLOWX_WORKFLOW_MAXEXECUTEDNODES is a safety guardrail — workflows that exceed this limit are terminated. Increase only if your workflows legitimately require more node executions.

Agent Builder configuration

Environment variable	Description	Default value
`FLOWX_AGENTBUILDER_HOST`	Hostname of the AI Platform Agent Builder service	`agent-builder`
`FLOWX_AGENTBUILDER_PORT`	gRPC port of the AI Platform Agent Builder service	`9100`

Starting with 5.9.2, AI Platform services are deployed under their plain names — the ai-platform- prefix is dropped from the default hostnames. If you overrode these variables with the old prefixed names, update them when upgrading. See the 5.9.2 deployment guidelines.

Process Engine configuration

Environment variable	Description	Default value
`FLOWX_PROCESSENGINE_BASEURL`	Base URL of the Process Engine service	`http://process-engine:80`

MCP client configuration

Timeouts for MCP (Model Context Protocol) server connections used by MCP Server data sources.

Environment variable	Description	Default value
`MCP_CLIENT_CONNECTTIMEOUT`	TCP connect timeout for MCP server connections	`5s`
`MCP_CLIENT_REQUESTTIMEOUT`	Request timeout for MCP server calls	`30s`
`MCP_CLIENT_PREFLIGHTCONNECTTIMEOUT`	Connect timeout for preflight (health) checks	`5s`
`MCP_CLIENT_PREFLIGHTREADTIMEOUT`	Read timeout for preflight checks	`5s`
`MCP_CLIENT_CLIENTNAME`	Client name sent in MCP handshake	`flowx-integration-designer`

Async AI callback configuration

Controls how timed-out AI node callbacks are reaped.

Environment variable	Description	Default value
`FLOWX_ASYNC_AI_CALLBACK_TTL`	Time-to-live for pending AI callbacks before they expire	`PT24H`
`FLOWX_ASYNC_AI_REAPER_FIXED_DELAY_MS`	Interval (ms) between reaper sweeps for expired callbacks	`5000`
`FLOWX_ASYNC_AI_REAPER_MAX_PER_TICK`	Maximum expired callbacks reaped per sweep	`200`

Script engine configuration

Integration Designer uses a native script engine for executing JavaScript and Python scripts in workflow nodes. The native engine runs scripts in separate Node.js and Python worker processes.

Environment variable	Description	Default value
`APPLICATION_SCRIPTENGINE_PROVIDER`	Script engine provider (`native` or `graalvm`)	`native`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE`	Number of Node.js worker processes	`16`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE`	Path to the Node.js binary used for the JS worker pool	`/usr/bin/node`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS`	Execution timeout per script (ms)	`5000`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER`	Max executions before a worker is recycled	`10000`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES`	Max input payload size (bytes)	`1048576` (1 MB)
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE`	Number of Python worker processes	`8`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE`	Path to the Python 3 binary used for the Python worker pool	`/usr/bin/python3`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`	Execution timeout per script (ms)	`10000`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER`	Max executions before a worker is recycled	`10000`
`APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES`	Max input payload size (bytes)	`1048576` (1 MB)

The native script engine is the default starting with 5.9.0. It replaces the previous GraalVM-based engine and runs scripts in isolated Node.js / Python subprocess pools. If you need to revert to GraalVM, set APPLICATION_SCRIPTENGINE_PROVIDER=graalvm.

Knowledge Base RAG configuration

Environment variable	Description	Default value
`FLOWX_KBRAG_HOST`	Hostname of the AI Platform Knowledge Base RAG service	`knowledgebase-rag`
`FLOWX_KBRAG_PORT`	gRPC port of the AI Platform Knowledge Base RAG service	`9100`

Oracle SQL schema discovery

Environment variable	Description	Default value
`FLOWX_SQL_DISCOVERY_CACHE_TTL`	Time-to-live for cached schema discovery responses (duration format, e.g. `24h`, `1h`)	`24h`

Retry configuration

Environment variable	Description	Default value
`FLOWX_RETRY_THREADS`	Worker threads for retry processing	`20`
`FLOWX_RETRY_PICKINGPAUSEMILLIS`	Pause between retry picking batches (ms)	`500`
`FLOWX_RETRY_COOLDOWNAFTERSECONDS`	Cooldown period after retry processing (sec)	`120`
`FLOWX_RETRY_SCHEDULER_UNBLOCKRETRIES_CRONEXPRESSION`	Cron expression for unblocking retries	`"/2 * * * ?"`

Database configuration

Advancing database

The Advancing Controller is a support service that optimizes advancing operations by ensuring efficient, balanced workload distribution—especially during scale-up and scale-down events. To enable Integration Designer to interact with the Advancing database, configure the following environment variables:

It can connect to the same database as the FlowX.AI Engine.

Environment variable	Description	Default value
`ADVANCING_DATASOURCE_URL`	Database JDBC URL	`jdbc:postgresql://localhost:5432/advancing`
`ADVANCING_DATASOURCE_USERNAME`	Database username	`postgres`
`ADVANCING_DATASOURCE_PASSWORD`	Database password	-
`ADVANCING_DATASOURCE_DRIVERCLASSNAME`	JDBC driver class	`org.postgresql.Driver`

Configuring the Advancing controller

Environment variable	Description	Default value
`ADVANCING_PROCESSINGTHREADS`	Number of worker threads for advancing operations	`20`
`ADVANCING_PICKINGPAUSEMILLIS`	Pause duration between picking batches (ms)	`50`
`ADVANCING_COOLDOWNAFTERSECONDS`	Cooldown period after processing (seconds)	`120`
`ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION`	Cron expression for the heartbeat	`"/2 * * * ?"`

Environment variable	Description	Default value
`ADVANCING_PICKINGTHREADS`	Number of worker threads for reading from database (picking operations)	`1`
`ADVANCING_PROCESSINGTHREADS`	Number of threads for parallel processing of advancing events	`20`
`ADVANCING_PROCESSINGBUFFERSIZE`	Maximum buffer size for processing queue. Controls how many events can be queued	`20`
`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`	Block picking operations when no worker threads are available	`true`
`ADVANCING_PICKINGPAUSEMILLIS`	Pause duration between picking batches (ms)	`50`
`ADVANCING_COOLDOWNAFTERSECONDS`	Cooldown period after processing a batch (seconds)	`120`
`ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION`	Cron expression for the heartbeat	`"/2 * * * ?"`

How the new advancing controller works:

Picking threads (ADVANCING_PICKINGTHREADS): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
Processing buffer (ADVANCING_PROCESSINGBUFFERSIZE): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there’s available space (even just 1 position), that amount of events will be read.
Processing threads (ADVANCING_PROCESSINGTHREADS): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.

The Advancing Controller supports multiple database systems including PostgreSQL and Oracle. Ensure you configure the appropriate JDBC URL and driver class for your chosen database system.

Workflow partitioning configuration

Workflow partitioning allows you to manage workflow instance data more efficiently by organizing data into time-based partitions. This is particularly useful for large-scale deployments where workflow instances accumulate over time.

Environment variable	Description	Default value	Options
`FLOWX_DATA_PARTITIONING_ENABLED`	Turn on or off workflow instance partitioning	`false`	`true`, `false`
`FLOWX_DATA_PARTITIONING_INTERVAL`	Time interval for creating partitions	`MONTH`	`DAY`, `WEEK`, `MONTH`
`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`	Turn on or off automatic archiving of old partitions	`false`	`true`, `false`
`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`	Number of intervals to retain before archiving	`3`	Any positive integer
`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`	Cron expression for the archiving schedule	`0 0 1 * * ?`	Any valid cron expression
`FLOWX_DATA_PARTITIONING_ARCHIVING_BATCHSIZE`	Batch size for moving documents into archive collections	`5000`	Integer values
`FLOWX_DATA_PARTITIONING_ARCHIVING_MAXDURATIONMINUTES`	Maximum time a single partition archive may run before it times out	`240`	Integer values
`FLOWX_DATA_PARTITIONING_ARCHIVING_SLEEPBETWEENBATCHESMS`	Pause between archive batches, in milliseconds	`200`	Integer values
`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`	Terminate stuck workflow instances so archiving isn’t blocked	`false`	`true`, `false`
`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_CRONEXPRESSION`	Cron for the stuck-instance termination sweep. Runs before the archiving cron.	`0 0 3 * * ?`	Any valid cron expression
`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_BATCHSIZE`	Batch size for the stuck-instance termination sweep	`100`	Integer values
`FLOWX_DATA_PARTITIONING_ARCHIVING_POSTARCHIVE_ACTION`	Post-archive action. `KEEP` retains archived data; `DROP` permanently deletes it.	`KEEP`	`KEEP`, `DROP`
`FLOWX_DATA_PARTITIONING_ARCHIVING_POSTARCHIVE_RETENTIONDAYS`	Days after archiving before `DROP` deletes data. Used only when the action is `DROP`.	`90`	Integer values
`FLOWX_DATA_PARTITIONING_ARCHIVING_POSTARCHIVE_CRONEXPRESSION`	Cron for the post-archive drop sweep. Offset from the archive cron.	`0 0 4 * * ?`	Any valid cron expression
`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`	One-shot backfill of `partition_id` on legacy documents. Turn off once it drains.	`false`	`true`, `false`
`FLOWX_DATA_PARTITIONING_BACKFILL_BATCHSIZE`	Batch size for the `partition_id` backfill	`5000`	Integer values
`FLOWX_DATA_PARTITIONING_BACKFILL_SLEEPBETWEENBATCHESMS`	Pause between backfill batches, in milliseconds	`100`	Integer values
`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`	One-shot backfill of `organization_id` on legacy documents. Optional on self-hosted; can remain `false`.	`false`	`true`, `false`

DROP permanently deletes archived data. When FLOWX_DATA_PARTITIONING_ARCHIVING_POSTARCHIVE_ACTION is set to DROP, archived data older than POSTARCHIVE_RETENTIONDAYS is deleted with no soft-delete and no way to recover it. Keep the default KEEP in production unless you have an explicit data-retention or compliance sign-off, and set the same value on Integration Designer and the process-engine.

Set FLOWX_DATA_PARTITIONING_INTERVAL to the same value on Integration Designer and the process-engine. A mismatch desynchronizes archive alignment between the two services.

How workflow partitioning works:

Partitioning: When turned on, workflow instances are stored in time-based partitions according to the specified interval.
Partition interval: Determines how frequently new partitions are created (DAY, WEEK, or MONTH).
Archiving: When turned on, automatically archives partitions older than the specified retention intervals. For example, with MONTH interval and 3 retention intervals, partitions older than 3 months will be archived.
Archiving schedule: The cron expression controls when the archiving process runs. The default 0 0 1 * * ? runs daily at 1:00 AM.

Partitions that still contain unfinished workflow instances are not archived. The archiving job processes a partition only when every workflow instance in it has reached a finished state: FINISHED, FAILED, or CANCELLED. A single workflow instance still in STARTED blocks the entire partition; the partition is retried on the next archiving run. If archiving stalls, turn on the stuck-instance termination sweep (FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED) to force blocking workflow instances into a final state so archiving can advance.

Turn on partitioning and archiving only after careful planning and testing. Once turned on, ensure that your database has sufficient storage for partition management operations. It’s recommended to start with archiving turned off and turn it on only after verifying that partitioning works correctly for your use case.

MongoDB

Integration Designer requires two MongoDB databases for managing integration-specific data and runtime data:

Integration Designer Database (integration-designer): Stores data specific to Integration Designer, such as integration configurations, metadata, and other operational data.
Shared Runtime Database (app-runtime): Shared across multiple services, this database manages runtime data essential for integration and data flow execution.

Environment variable	Description	Default value
`SPRING_DATA_MONGODB_URI`	Integration Designer MongoDB URI	`mongodb://mongodb-0.mongodb-headless:27017/integration-designer`
`SPRING_DATA_MONGODB_USERNAME`	MongoDB username	`integration-designer`
`SPRING_DATA_MONGODB_PASSWORD`	MongoDB password
`SPRING_DATA_MONGODB_STORAGE`	Storage type (Azure environments only)	`mongodb` (or `cosmosdb`)
`SPRING_DATA_MONGODB_RUNTIME_URI`	Runtime MongoDB URI	`mongodb://mongodb-0.mongodb-headless:27017/app-runtime`
`SPRING_DATA_MONGODB_RUNTIME_USERNAME`	Runtime MongoDB username	`app-runtime`
`SPRING_DATA_MONGODB_RUNTIME_PASSWORD`	Runtime MongoDB password

Integration Designer requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.

Configuration parameters

There are two types of Config Params that can be read from the environment: variables and secrets. There is one provider for variables and secrets extracted from the environment variables, and two providers for the ones extracted from Kubernetes. By default, the variables and secrets are extracted from environment variables (env provider).

Configuration parameters from environment variables (default)

The env provider used for variables and secrets extracts them from environment variables. For security reasons, the env provider uses an allow list regex which defaults to FLOWX_CONFIGPARAM_.*. This means only environment variables that match this naming pattern can be read at runtime into configuration params (either as variables or secrets). Feel free to edit it to match the environment variables that you use in your deployment.

Environment variable	Description	Default value
`FLOWX_CONFIGPARAMS_VARS_PROVIDER`	Provider type for variables	`env`
`FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX`	Regular expression to match allowed env variables for variables	`FLOWX_CONFIGPARAM_.*`
`FLOWX_CONFIGPARAMS_SECRETS_PROVIDER`	Provider type for secrets	`env`
`FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX`	Regular expression to match allowed env variables for secrets	`FLOWX_CONFIGPARAM_.*`

Configuration parameters from Kubernetes Secrets and ConfigMaps

Use the following configuration to read Config Params from Kubernetes Secrets and ConfigMaps:

Environment variable	Description	Values
`FLOWX_CONFIGPARAMS_VARS_PROVIDER`	Provider type for variables	`k8s-configmaps`
`FLOWX_CONFIGPARAMS_SECRETS_PROVIDER`	Provider type for secrets	`k8s-secrets`

These providers can be configured as follows:

Environment variable	Description	Values
`FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_0`	Name of the ConfigMap to use for variables	`flowx-configparams`
`FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_0`	Name of the Secret to use for secrets	`flowx-configparams`

You can configure multiple secrets and ConfigMaps by incrementing the index number (e.g., FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_1, FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_1). In dev environments, the typical ConfigMap/Secret name is flowx-rt. Values are overridden based on the order in which the maps are defined.The default provider is env, but there is a built-in allowlist with the regex pattern FLOWX_CONFIGPARAM_.*. This means only configuration parameters that match this naming pattern can be read at runtime, whether they are environment variables or secret variables.

Kafka configuration

Kafka connection and security variables

Environment variable	Description	Default value
`KAFKA_BOOTSTRAP_SERVERS`	Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)	`localhost:9092`
`KAFKA_SECURITY_PROTOCOL`	Security protocol (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`)	`PLAINTEXT` or `SASL_PLAINTEXT`
`FLOWX_WORKFLOW_CREATETOPICS`	Auto-create topics	`false` (default)

Message size configuration

Environment variable	Description	Default value
`KAFKA_MESSAGE_MAX_BYTES`	Maximum message size	`52428800` (50MB)

This setting affects:

Producer message max bytes
Producer max request size

Consumer configuration

Environment variable	Description	Default value
`KAFKA_CONSUMER_GROUPID_STARTWORKFLOWS`	Start workflows consumer group	`start-workflows-group`
`KAFKA_CONSUMER_GROUPID_RESELEMUSAGEVALIDATION`	Resource usage validation consumer group	`integration-designer-res-elem-usage-validation-group`
`KAFKA_CONSUMER_GROUPID_SYSTEMSYNC`	System sync consumer group	`system-sync-group`
`KAFKA_CONSUMER_GROUPID_WORKFLOWSYNC`	Workflow sync consumer group	`workflow-sync-group`
`KAFKA_CONSUMER_GROUPID_CORRECTIONAFTERAPPOPERATION`	Correction after app operation consumer group	`correction-after-app-operation-group`
`KAFKA_CONSUMER_GROUPID_STOREENTRYINDEXERRESPONSE`	KB store entry indexer response consumer group	`store-entry-indexer-response-group`
`KAFKA_CONSUMER_THREADS_STARTWORKFLOWS`	Start workflows consumer threads	`3`
`KAFKA_CONSUMER_THREADS_RESELEMUSAGEVALIDATION`	Resource usage validation consumer threads	`3`
`KAFKA_CONSUMER_THREADS_SYSTEMSYNC`	System sync consumer threads	`3`
`KAFKA_CONSUMER_THREADS_WORKFLOWSYNC`	Workflow sync consumer threads	`3`
`KAFKA_CONSUMER_THREADS_CORRECTIONAFTERAPPOPERATION`	Correction after app operation consumer threads	`3`
`KAFKA_CONSUMER_THREADS_STOREENTRYINDEXERRESPONSE`	KB store entry indexer response consumer threads	`3`
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	Retry interval after authorization errors	`10` (seconds)

Topic naming convention and pattern creation

The Integration Designer uses a structured topic naming convention that follows a standardized pattern, ensuring consistency across environments and making topics easily identifiable.

Topic naming components

Environment variable	Description	Default value
`KAFKA_TOPIC_NAMING_PACKAGE`	Base package for topics	`ai.flowx.`
`KAFKA_TOPIC_NAMING_ENVIRONMENT`	Environment identifier
`KAFKA_TOPIC_NAMING_VERSION`	Topic version	`.v1`
`KAFKA_TOPIC_NAMING_SEPARATOR`	Topic name separator	`.`
`KAFKA_TOPIC_NAMING_SEPARATOR2`	Alternative separator	`-`
`KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN`	Engine receive pattern	`engine.receive.`
`KAFKA_TOPIC_NAMING_INTEGRATIONRECEIVEPATTERN`	Integration receive pattern	`integration.receive.`

Topics are constructed using the following pattern:

{prefix} + service + {separator/dot} + action + {separator/dot} + detail + {suffix}

For example, a typical topic might look like:

ai.flowx.eventsgateway.receive.workflowinstances.v1

Where:

ai.flowx. is the prefix (package + environment)
eventsgateway is the service
receive is the action
workflowinstances is the detail
.v1 is the suffix (version)

Kafka topic configuration

Core topics

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_AUDIT_OUT`	Topic for sending audit logs	`ai.flowx.core.trigger.save.audit.v1`

Events gateway topics

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`	Topic for workflow instances communication	`ai.flowx.eventsgateway.receive.workflowinstances.v1`

UI flow session variable updates

When a workflow triggered by a UI Flow finishes, the integration-designer sends the result to the process-engine so the session variables are updated automatically.

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_UIFLOW_UPDATE_OUT`	Topic for sending workflow results to process-engine for UI flow session variable updates	`ai.flowx.core.trigger.ui-flow.update.v1`

Knowledge Base store entry lifecycle topics

These topics handle communication between Integration Designer and the AI Platform for Knowledge Base store entry indexing operations.

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_IN`	Topic for receiving KB store entry index responses from AI Platform (consumed)	`ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1`
`KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_OUT`	Topic for sending KB store entry index requests to AI Platform (produced)	`ai.flowx.ai-platform.knowledgebase.store-entry.index-request.v1`

AI Platform job topics

Integration Designer dispatches document parsing, speech-to-text, and evaluation jobs to the AI Platform over Kafka. Each job family has a request topic (produced), a response topic (consumed), and a dead-letter topic (consumed).

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_AI_DOCPARSER_JOB_REQUEST_OUT`	Document Parser job requests (produced)	`ai.flowx.ai-platform.doc-parser.job.request.v1`
`KAFKA_TOPIC_AI_DOCPARSER_JOB_RESPONSE_IN`	Document Parser job responses (consumed)	`ai.flowx.ai-platform.doc-parser.job.response.v1`
`KAFKA_TOPIC_AI_DOCPARSER_JOB_DLQ_IN`	Document Parser job dead-letter queue (consumed)	`ai.flowx.ai-platform.doc-parser.job.dlq.v1`
`KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_REQUEST_OUT`	Speech-to-Text job requests (produced)	`ai.flowx.ai-platform.speech-to-text.job.request.v1`
`KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_RESPONSE_IN`	Speech-to-Text job responses (consumed)	`ai.flowx.ai-platform.speech-to-text.job.response.v1`
`KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_DLQ_IN`	Speech-to-Text job dead-letter queue (consumed)	`ai.flowx.ai-platform.speech-to-text.job.dlq.v1`
`KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`	Evaluations judge job requests (produced)	`ai.flowx.ai-platform.evals-judge.job.request.v1`
`KAFKA_TOPIC_AI_EVALSJUDGE_JOB_RESPONSE_IN`	Evaluations judge job responses (consumed)	`ai.flowx.ai-platform.evals-judge.job.response.v1`
`KAFKA_TOPIC_AI_EVALSJUDGE_JOB_DLQ_IN`	Evaluations judge job dead-letter queue (consumed)	`ai.flowx.ai-platform.evals-judge.job.dlq.v1`
`KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT`	Evaluation improvement-suggestions job requests (produced) — available from FlowX.AI 5.9.1	`ai.flowx.evals.suggestions.job.request.v1`
`KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN`	Evaluation improvement-suggestions job responses (consumed) — available from FlowX.AI 5.9.1	`ai.flowx.evals.suggestions.job.response.v1`

Engine and Integration communication topics

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_ENGINEPATTERN`	Pattern for Engine communication	`ai.flowx.engine.receive.`
`KAFKA_TOPIC_INTEGRATIONPATTERN`	Pattern for Integration communication	`ai.flowx.integration.receive.*`

Application topics

Outbound topics:

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_APPLICATION_OUT_SYNCRESPONSE`	Sync response messages	`ai.flowx.application-version.sync.out.v1`
`KAFKA_TOPIC_APPLICATION_OUT_CORRECTIONAFTERAPPOPERATIONRESPONSE`	Correction after app operation response	`ai.flowx.application-version.correction-after-app-operation.response.v1`
`KAFKA_TOPIC_BUILD_RUNTIMEDATA`	Build runtime data	`ai.flowx.build.runtime-data.v1`
`KAFKA_TOPIC_LICENSE_OUT_USAGE`	License usage tracking	`ai.flowx.license.usage.v1`

The sync.out.v1 and correction-after-app-operation.response.v1 topics exist since 5.1.x (produced by admin). Starting with 5.5.0, integration-designer also produces to these shared response topics for system and workflow sync/correction operations.

Inbound topics:

Environment variable	Description	Default Pattern
`KAFKA_TOPIC_APPLICATION_IN_RESELEMUSAGEVALIDATION`	Resource usage validation requests	`ai.flowx.application-version.resources-usages.sub-res-validation.request-integration.v1`
`KAFKA_TOPIC_APPLICATION_IN_SYSTEMSYNCREQUEST`	System sync requests	`ai.flowx.application-version.sync.system.in.v1`
`KAFKA_TOPIC_APPLICATION_IN_WORKFLOWSYNCREQUEST`	Workflow sync requests	`ai.flowx.application-version.sync.workflow.in.v1`
`KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_SYSTEM`	System correction after app operation	`ai.flowx.application-version.correction-after-app-operation.system.request.v1`
`KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_WORKFLOW`	Workflow correction after app operation	`ai.flowx.application-version.correction-after-app-operation.workflow.request.v1`
`KAFKA_TOPIC_RESOURCESUSAGES_REFRESH`	Resource usage refresh commands	`ai.flowx.application-version.resources-usages.refresh.v1`

OAuth authentication variables (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.

Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, ensure proper coordination between services:

Topic name matching: Output topics from one service must match the expected input topics of another service.
Pattern consistency: The pattern values must be consistent across services:
- Process Engine listens to topics matching: ai.flowx.engine.receive.*
- Integration Designer listens to topics matching: ai.flowx.integration.receive.*
Communication flow:
- Other services write to topics matching the Engine’s pattern → Process Engine listens
- Process Engine writes to topics matching the Integration Designer’s pattern → Integration Designer listens

The exact pattern value isn’t critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.

Kafka topics best practices

Large message handling for workflow instances topic

The workflow instances topic requires special configuration to handle large messages. By default, Kafka has message size limitations that may prevent Integration Designer from processing large workflow payloads. Recommended max.message.bytes value: 10485760 (10 MB)

Method: update using AKHQ (recommended)

Access AKHQ
- Open the AKHQ web interface
- Log in if authentication is required
Navigate to Topic
- Go to the “Topics” section
- Find the topic: ai.flowx.eventsgateway.receive.workflowinstances.v1
Edit Configuration
- Click on the topic name
- Go to the “Configuration” tab
- Locate or add max.message.bytes
- Set the value to 10485760
- Save changes

CAS lib configuration

CAS lib is used to communicate with the authorization-service through SpiceDB.

Environment variable	Description	Default value
`FLOWX_SPICEDB_HOST`	Spicedb host	`spicedb`
`FLOWX_SPICEDB_PORT`	Spicedb port	`50051`
`FLOWX_SPICEDB_TOKEN`	Spicedb db token	`REPLACEME`

Configuring authentication and access roles

Integration Designer validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:

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_MAINIDENTITY_CLIENTID`	Service account client ID	`flowx-integration-designer-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	Service account client secret (Keycloak-issued)
`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
`SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`	Provider token URI, resolved against the service-accounts realm	`${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token`

Upgrading from 5.1.x? Remove the legacy opaque-token env vars: SECURITY_OAUTH2_REALM, SECURITY_OAUTH2_CLIENT_CLIENTID, SECURITY_OAUTH2_CLIENT_CLIENTSECRET, and SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*. 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.

For detailed instructions on configuring user roles and access rights, refer to:

Access Management

For configuring a service account, refer to:

Integration Designer service account

Configuring logging

To control the log levels for Integration Designer, set the following environment variables:

Environment variable	Description	Default value
`LOGGING_LEVEL_ROOT`	Root Spring Boot logs level	`INFO`
`LOGGING_LEVEL_APP`	Application-level logs level	`INFO`

Configuring admin ingress

The Integration Designer service uses the standard FlowX.AI ingress pattern. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the Ingress Configuration Guide. Service-specific values for Integration Designer:

Ingress name: integration-designer-admin
Service path: /integration(/|$)(.*)
Service name: integration-designer
Rewrite target: /$2
Fx-Workspace-Id: Required

Complete Ingress Configuration

View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.

Monitoring and maintenance

To monitor the performance and health of the Integration Designer, use tools like Prometheus or Grafana. Configure Prometheus metrics with:

Environment variable	Description	Default value
`MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED`	Enable Prometheus metrics export	`false`

RBAC configuration

Integration Designer requires specific RBAC (Role-Based Access Control) permissions to access Kubernetes ConfigMaps and Secrets, which store necessary configurations and credentials. Set up these permissions by enabling RBAC and defining the required rules:

rbac:
  create: true
  rules:
    - apiGroups:
        - ""
      resources:
        - secrets
        - configmaps
        - pods
      verbs:
        - get
        - list
        - watch

This configuration grants read access (get, list, watch) to ConfigMaps, Secrets, and Pods, which is essential for retrieving application settings and credentials required by Integration Designer.

Ingress and CORS

The Integration Designer service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

Service route

Host group	External path	Backend receives
admin	`/integration`	`/`

The path is set through services.integration-designer.ingress.admin.path (or services.integration-designer.gateway.admin.paths) in the chart values.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOWORIGIN`	Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Integration Designer.	`-`

Allowed methods, allowed headers (including Authorization, Content-Type, Fx-Workspace-Id), and credential handling are baked into the service’s application.yaml with safe defaults. 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

Integration Designer fails to start

Symptoms: Service crashes on startup or fails health checks.Solutions:

Verify MongoDB connection URIs for both the integration-designer and app-runtime databases
Check that Kafka broker addresses are reachable and the security protocol is correct
Ensure the Keycloak service account is properly configured and the client secret is valid
Review logs at LOGGING_LEVEL_APP=DEBUG for detailed startup error messages

REST connector calls failing

Symptoms: Workflow executions fail at REST connector nodes with timeout or connection errors.Solutions:

Verify network connectivity between the Integration Designer pod and the target system
Check SSL/TLS certificates if the target system uses HTTPS
Review timeout settings and increase FLOWX_WEBCLIENT_BUFFERSIZE if responses are large
Ensure firewall rules and network policies allow outbound traffic to the target host and port

Workflow execution errors

Symptoms: Workflows start but fail during execution with Kafka or data mapping errors.Solutions:

Verify that all required Kafka topics exist and are correctly named across services
Check that input/output parameter mappings match the expected data model
Ensure the KAFKA_TOPIC_ENGINEPATTERN and KAFKA_TOPIC_INTEGRATIONPATTERN values are consistent with the Process Engine configuration
Review the events gateway topic (KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE) for message delivery issues

Data sources not connecting

Symptoms: Data sources configured in Integration Designer show connection errors or timeouts.Solutions:

Verify that the credentials for the target data source are correct and not expired
Check network access between the Integration Designer pod and the data source endpoint
Ensure firewall rules allow traffic on the required ports
For S3-compatible storage issues, verify APPLICATION_FILESTORAGE_S3_SERVERURL and access key configuration