Skip to main content
This guide provides a comprehensive reference for configuring the FlowX Admin microservice using environment variables and configuration files.

​
Infrastructure prerequisites

Before setting up the Admin microservice, ensure the following components are properly set up:
  • Database Instance: The Admin microservice connects to the same database as the FlowX.AI Engine.
  • MongoDB: For additional data management.
  • Redis: For caching and transient data storage.
  • Kafka: For audit logs, events, and messaging (if using FlowX.AI Audit functionality).

​
Core configuration

​
Server configuration

Environment VariableDescriptionDefault Value
SERVER_PORTPort on which the Admin service will run8080
SPRING_APPLICATION_NAMEName of the application used for service discoveryadmin
SPRING_JACKSON_SERIALIZATION_INDENTOUTPUTEnable indented JSON outputtrue

​
Database configuration

The Admin microservice connects to the same PostgreSQL or Oracle database as the FlowX.AI Engine for storing process definitions.
Environment VariableDescriptionDefault Value
SPRING_DATASOURCE_URLJDBC URL for database connectionjdbc:postgresql://localhost:5432/flowx
SPRING_DATASOURCE_USERNAMEDatabase usernamepostgres
SPRING_DATASOURCE_PASSWORDDatabase password[your-secure-password]
You will need to make sure that the user, password, connection link and database name are configured correctly, otherwise, you will receive errors at start time.
The database schema is managed by a Liquibase script provided with the Engine.

​
MongoDB configuration

The Admin microservice also connects to a MongoDB database instance for additional data management.
Environment VariableDescriptionDefault Value
DB_USERNAMEMongoDB usernamedata-model
DB_PASSWORDMongoDB password[your-secure-password]
DB_NAMEMongoDB database namedata-model
SPRING_DATA_MONGODB_URIMongoDB connection URImongodb://${DB_USERNAME}:${DB_PASSWORD}@localhost:27017/${DB_NAME}?retryWrites=true
SPRING_DATA_MONGODB_UUIDREPRESENTATIONUUID representation formatstandard
SPRING_DATA_MONGODB_STORAGEStorage type (Azure environments)mongodb or cosmosdb
MONGOCK_CHANGELOGSSCANPACKAGE_0_Mongock changelog scan packageai.flowx.admin.data.model.config.mongock
MONGOCK_TRANSACTIONENABLEDEnable transactions for Mongock operationsfalse
Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.

​
Redis and caching configuration

Admin Service uses Redis for caching and storing transient data. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
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.

​
Kafka configuration

The Admin microservice uses Kafka for sending audit logs, managing scheduled timer events, platform component versions, and start timer event updates.

​
General Kafka settings

Environment VariableDescriptionDefault Value
SPRING_KAFKA_BOOTSTRAPSERVERSKafka broker addresseslocalhost:9092
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocolPLAINTEXT
KAFKA_MESSAGE_MAX_BYTESMaximum message size in bytes52428800 (50MB)

​
Kafka producer configuration

Environment VariableDescriptionDefault Value
SPRING_KAFKA_PRODUCER_KEYSERIALIZERKey serializer classorg.apache.kafka.common.serialization.StringSerializer
SPRING_KAFKA_PRODUCER_VALUESERIALIZERValue serializer classorg.springframework.kafka.support.serializer.JsonSerializer
SPRING_KAFKA_PRODUCER_MAXREQUESTSIZEMaximum request size52428800 (50MB)

​
Kafka consumer configuration

Environment VariableDescriptionDefault Value
KAFKA_CONSUMER_GROUPID_GENERICPROCESSINGGeneric processing consumer groupgeneric-processing-group
KAFKA_CONSUMER_THREADS_GENERICPROCESSINGGeneric processing threads6
KAFKA_CONSUMER_GROUPID_PROCESSSYNCProcess sync consumer groupprocess-sync-group
KAFKA_CONSUMER_THREADS_PROCESSSYNCProcess sync consumer threads6
KAFKA_CONSUMER_GROUPID_BUSINESSRULESYNCBusiness rule sync consumer groupbusiness-rule-sync-group
KAFKA_CONSUMER_THREADS_BUSINESSRULESYNCBusiness rule sync consumer threads6
KAFKA_CONSUMER_GROUPID_REUSABLETEMPLATESYNCReusable template sync consumer groupreusable-template-sync-group
KAFKA_CONSUMER_THREADS_REUSABLETEMPLATESYNCReusable template sync consumer threads6
KAFKA_CONSUMER_GROUPID_UIFLOWSYNCUI flow sync consumer groupui-flow-sync-group
KAFKA_CONSUMER_THREADS_UIFLOWSYNCUI flow sync consumer threads6
KAFKA_CONSUMER_GROUPID_PROCESSCORRECTIONAFTERAPPOPERATIONProcess correction after app operation consumer groupprocess-correction-after-app-operation-group
KAFKA_CONSUMER_THREADS_PROCESSCORRECTIONAFTERAPPOPERATIONProcess correction after app operation consumer threads6
KAFKA_AUTHEXCEPTIONRETRYINTERVALAuth exception retry interval (seconds)10

​
Topic naming configuration

Environment VariableDescriptionDefault Value
DOTReference to the primary separator${kafka.topic.naming.separator}
DASHReference to the secondary separator${kafka.topic.naming.separator2}
KAFKA_TOPIC_NAMING_PACKAGEBase package nameai${dot}flowx${dot}
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment name
KAFKA_TOPIC_NAMING_VERSIONTopic version${dot}v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator-
KAFKA_TOPIC_NAMING_PREFIXCombined prefix${kafka.topic.naming.package}${kafka.topic.naming.environment}
KAFKA_TOPIC_NAMING_SUFFIXCombined suffix${kafka.topic.naming.version}

​
Kafka topics configuration

​
Application topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_APPLICATION_SYNCRESPONSESync response topic${kafka.topic.naming.prefix}application-version.sync.out${kafka.topic.naming.suffix}ai.flowx.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESSSYNCProcess sync topic${kafka.topic.naming.prefix}application-version.sync.process.in${kafka.topic.naming.suffix}ai.flowx.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULESYNCBusiness rule sync topic${kafka.topic.naming.prefix}application-version.sync.business-rule.in${kafka.topic.naming.suffix}ai.flowx.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATESYNCReusable template sync topic${kafka.topic.naming.prefix}application-version.sync.reusable-template.in${kafka.topic.naming.suffix}ai.flowx.application-version.sync.reusable-template.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCEUPDATEPROPAGATIONResource update propagation topic${kafka.topic.naming.prefix}application-version.resource.update.propagation${kafka.topic.naming.suffix}ai.flowx.application-version.resource.update.propagation.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESSCorrection after app operation → process request${kafka.topic.naming.prefix}application-version.correction-after-app-operation.process.request${kafka.topic.naming.suffix}ai.flowx.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULECorrection after app operation → business rule${kafka.topic.naming.prefix}application-version.correction-after-app-operation.business-rule.request${kafka.topic.naming.suffix}ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATECorrection after app operation → reusable template${kafka.topic.naming.prefix}application-version.correction-after-app-operation.reusable-template.request${kafka.topic.naming.suffix}ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_UIFLOWCorrection after app operation → UI flow${kafka.topic.naming.prefix}application-version.correction-after-app-operation.ui-flow.request${kafka.topic.naming.suffix}ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUTCorrection after app operation response topic${kafka.topic.naming.prefix}application-version.correction-after-app-operation.response${kafka.topic.naming.suffix}ai.flowx.application-version.correction-after-app-operation.response.v1
KAFKA_TOPIC_APPLICATION_UIFLOWSYNCUI flow sync topic${kafka.topic.naming.prefix}application-version.sync.ui-flow.in${kafka.topic.naming.suffix}ai.flowx.application-version.sync.ui-flow.in.v1

​
Audit topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_AUDIT_OUTAudit output topic${kafka.topic.naming.prefix}core${dot}trigger${dot}save${dot}audit${kafka.topic.naming.suffix}ai.flowx.core.trigger.save.audit.v1

​
Platform Topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_INComponents versions caching topic${kafka.topic.naming.prefix}core${dot}trigger${dot}platform${dot}versions${dot}caching${kafka.topic.naming.suffix}ai.flowx.core.trigger.platform.versions.caching.v1

​
Events gateway topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGECommands message output topic${kafka.topic.naming.prefix}eventsgateway${dot}process${dot}commands${dot}message${kafka.topic.naming.suffix}ai.flowx.eventsgateway.process.commands.message.v1

​
Build topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_BUILD_RUNTIMEDATABuild runtime data topic${kafka.topic.naming.prefix}build${dot}runtime-data${kafka.topic.naming.suffix}ai.flowx.build.runtime-data.v1
KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_OUT_UPDATESStart timer events updates topic${kafka.topic.naming.prefix}build${dot}start${dash}timer${dash}events${dot}updates${dot}in${kafka.topic.naming.suffix}ai.flowx.build.start-timer-events.updates.in.v1

​
Resource topics

Environment VariableDescriptionPatternDefault Value
KAFKA_TOPIC_RESOURCESUSAGES_REFRESHResources usages refresh topic${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}refresh${kafka.topic.naming.suffix}ai.flowx.application-version.resources-usages.refresh.v1

​
OAuth authentication for Kafka

When using the kafka-auth profile, the following variables configure OAuth for Kafka:
Environment VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.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.

​
CAS lib configuration

Environment VariableDescriptionDefault Value
FLOWX_SPICEDB_HOSTSpiceDB server hostnamespicedb
FLOWX_SPICEDB_PORTSpiceDB server port50051
FLOWX_SPICEDB_TOKENSpiceDB authentication tokenspicedb-token

​
Logging configuration

The FlowX Admin microservice provides granular control over logging levels for different components:
Environment VariableDescriptionDefault Value
LOGGING_LEVEL_ROOTLog level for root Spring Boot microserviceINFO
LOGGING_LEVEL_APPLog level for application-specific codeDEBUG

​
Changing log levels at runtime

You can adjust log levels dynamically without restarting the service using Spring Boot Actuator endpoints. This is particularly useful for troubleshooting and debugging in production environments. Example: Change log level for a specific package 
curl 'http://localhost:8081/actuator/loggers/ai.flowx.admin' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
Common logger packages:
  • ai.flowx.admin - Application-specific logs
  • org.springframework - Spring Framework logs
  • org.mongodb.driver - MongoDB driver logs
  • org.apache.kafka - Kafka client logs
Available log levels: TRACE, DEBUG, INFO, WARN, ERROR, OFF
Using DEBUG or TRACE log levels in production may impact performance and generate large log volumes. Revert to INFO or WARN after troubleshooting is complete.

​
Localization settings

Environment VariableDescriptionDefault Value
APPLICATION_DEFAULTLOCALEDefault locale for the applicationen
APPLICATION_SUPPORTEDLOCALESList of supported localesen, ro

​
Health monitoring

Environment VariableDescriptionDefault Value
MANAGEMENT_HEALTH_DB_ENABLEDEnable database health checkstrue
MANAGEMENT_HEALTH_KAFKA_ENABLEDEnable Kafka health checkstrue
MANAGEMENT_SERVER_ADDRESSManagement server bind address0.0.0.0
MANAGEMENT_SERVER_PORTManagement server port8081
MANAGEMENT_SERVER_BASEPATHBase path for management endpoints/manage
MANAGEMENT_SECURITY_ENABLEDEnable security for management endpointsfalse
MANAGEMENT_ENDPOINTS_WEB_BASEPATHBase path for actuator endpoints/actuator
MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDEEndpoints to exposehealth,info,metrics,metric,prometheus
MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLEDEnable Kubernetes probestrue
MANAGEMENT_ENDPOINT_HEALTH_SHOWDETAILSShow health check detailsalways
MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLEDEnable Prometheus metrics exportfalse

​
Platform health configuration

Environment VariableDescriptionDefault Value
FLOWX_PLATFORMHEALTH_NAMESPACEKubernetes namespace for health checksflowx
FLOWX_PLATFORMHEALTH_MANAGEMENTBASEPATHBase path for management endpoints${management.server.base-path}
FLOWX_PLATFORMHEALTH_ACTUATORBASEPATHBase path for actuator endpoints${management.endpoints.web.base-path}
FLOWX_PLATFORMHEALTH_ANNOTATIONNAMEKubernetes annotation name for health checksflowx.ai/health
FLOWX_PLATFORMHEALTH_ANNOTATIONVALUEKubernetes annotation value for health checkstrue
FLOWX_PLATFORMHEALTH_DISCOVERYINTERVALInterval at which the platform re-discovers deployed services automaticallyPT5M
FLOWX_PLATFORMHEALTH_DISCOVERYINITIALDELAYDelay before the first automatic service discovery run after startupPT30S

​
Multi-edit and undo/redo configuration

Environment VariableDescriptionDefault Value
FLOWX_MULTIEDIT_TTLTime-to-live for multi-edit sessions in seconds45
FLOWX_UNDOREDO_TTLTime-to-live for undo/redo actions in seconds86400
FLOWX_UNDOREDO_CLEANUP_CRONEXPRESSIONCron expression for undo/redo cleanup0 0 2 ?
FLOWX_UNDOREDO_CLEANUP_DAYSDays to keep deleted undo/redo items2

​
Resources usage configuration

Environment VariableDescriptionDefault Value
FLOWX_LIB_RESOURCESUSAGES_ENABLEDEnable resources usage trackingtrue
FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLEDEnable listener for resource usage refreshestrue
FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNTThread count for resource usage collector5
FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZEMaximum batch size for resource usage collection1000
FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGESREFRESHConsumer group ID for resource usage refreshadmin-resources-usages-refresh-group
FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGESREFRESHNumber of consumer threads for resource usage refresh3
FLOWX_LIB_RESOURCESUSAGES_KAFKA_TOPIC_RESOURCE_USAGES_REFRESHKafka topic for resource usage refresh${kafka.topic.resources-usages.refresh}
FLOWX_LIB_RESOURCESUSAGES_KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval in seconds after auth exceptions3

​
Authentication and Authorization Configuration

The FlowX Admin microservice supports authentication and authorization through OpenID Connect (with Keycloak as the default provider) and allows detailed role-based access control.

​
Security type

Environment VariableDescriptionDefault Value
SECURITY_TYPEToken validation mechanism (JWT public key validation)jwt-public-key
SECURITY_OAUTH2CLIENTEnable OAuth2 clientenabled
SECURITY_OAUTH2_BASESERVERURLBase URL of the Keycloak server
SECURITY_OAUTH2_SAREALMService-accounts realm ID00000002-0002-4002-8002-000000000002
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLURL of the organization-manager service, used by the security libraryhttp://organization-manager:80

​
Service account configuration

The Admin service authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:
Environment VariableDescriptionDefault Value
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTIDService account client IDflowx-admin-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETService account client secret (Keycloak-issued)
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTIDAnonymous service account client ID, used for anonymous runtime accessflowx-anonymous-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRETAnonymous service account client secret
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURIProvider 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. The OPENID_PROVIDER / OPENID_KEYCLOAK_* / OPENID_ENTRA_* identity-provider block was also removed from the Admin service in 5.9.0. See the authentication and IAM migration guide for the full list.
When deploying with the FlowX Helm chart, SECURITY_OAUTH2_BASESERVERURL is supplied through the chart value flowx.keycloak.baseServerUrl and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.

​
Designer authentication client

Environment VariableDescriptionDefault Value
FLOWX_AUTHENTICATE_CLIENTIDClient ID for authentication serviceflowx-platform-authenticate
The role-based access control is configured in the application YAML and grants specific permissions for platform management, user management, process management, integrations management, and configuration management.

​
Ingress and CORS

The Admin 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 groupExternal pathBackend receives
admin//
The path is set through services.admin.ingress.admin.path (or services.admin.gateway.admin.paths) in the chart values. Override only if you serve FlowX Admin under a different prefix.

​
CORS configuration

Environment VariableDescriptionDefault Value
APPLICATION_CORS_ALLOW_ORIGINComma-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 Admin.-
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.
In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.
Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.

​
Troubleshooting

​
Common issues

Symptoms: Service crashes on startup or fails health checks.Solutions:
  1. Verify PostgreSQL connection parameters (SPRING_DATASOURCE_URL, credentials) are correct and the database is reachable
  2. Check that MongoDB is running and the connection URI is valid
  3. Ensure Kafka brokers are accessible at the configured SPRING_KAFKA_BOOTSTRAPSERVERS address
  4. Review startup logs for specific error messages indicating which dependency is unavailable
Symptoms: Import/export operations fail with permission or authentication errors.Solutions:
  1. Verify the Keycloak service account has the required roles for import/export operations
  2. Check that SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID and SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET are configured correctly
  3. Ensure the service account has canImport access rights in the target workspace
  4. Confirm the target application version is in a WIP state
Symptoms: Creating a build returns errors or times out.Solutions:
  1. Check connectivity between Admin and the application-manager service
  2. Verify that the Kafka topics for build operations (KAFKA_TOPIC_BUILD_RUNTIMEDATA) are created and accessible
  3. Ensure version compatibility between Admin and application-manager services
  4. Review Kafka consumer group lag for build-related topics
Symptoms: Designer interface fails to render or returns blank pages.Solutions:
  1. Verify the Designer service is running and healthy
  2. Check ingress configuration — ensure the Admin ingress (admin-admin) is correctly routing traffic
  3. Review CORS settings in the Ingress Configuration Guide
  4. Confirm that the Fx-Workspace-Id header is being passed correctly through the ingress

Configuring an IAM Solution

Identity and access management setup for Keycloak and Microsoft Entra ID

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Ingress Configuration

Centralized ingress guide with CORS configuration and best practices
Last modified on June 4, 2026