NoSQL DB Runner

Behavior change in FlowX.AI 5.9.1. Insert operations no longer accept a custom _id field._id is reserved and assigned internally by MongoDB. Supplying your own _id on insert was never supported and could cause errors on later reads, so Insert and Insert Many now reject any payload that contains an _id field with 400 Bad Request and the message _id is a reserved keyword. Remove _id from insert payloads; if you need to keep a custom identifier, store it under a different key (for example, externalId). Update and query operations are not affected.

Configuration

The service comes with most of the needed configuration properties filled in, but there are several environment variables that need to be set up for your specific deployment.

Database configuration

The NoSQL DB Runner connects to MongoDB for data persistence. Configure the following variables:

Environment Variable	Description	Default Value
`DB_USERNAME`	MongoDB username for the service	`nosql-db-runner`
`DB_PASSWORD`	MongoDB password (should be stored as secret)	`secret(mongodb-generic)`
`SPRING_DATA_MONGODB_URI`	Complete MongoDB connection string	`mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/nosql-db-runner`

The MongoDB URI supports replica set configuration for high availability. The connection string includes multiple MongoDB instances and an arbiter for proper replica set functionality.

Configuring authorization & access roles

The NoSQL DB Runner 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-nosql-db-runner-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.

FlowX operations document limit

This setting allows you to configure the maximum number of documents that can be retrieved from MongoDB in a single request.

Environment Variable	Description	Default Value
`FLOWX_RUNOPERATIONS_DOCUMENTLIMIT`	Maximum number of documents to be processed in a single operation	`1000`

External MongoDB connection caching

Environment Variable	Description	Default Value
`FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES`	Maximum number of cached external MongoDB connections	`100`
`FLOWX_MONGO_CONNECTIONS_CACHE_TTL`	Time-to-live for cached connections (duration format, e.g. `1d`, `12h`)	`1d`

If you connect to many distinct external MongoDB instances, increase FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES to avoid frequent reconnections. Lower the TTL if your MongoDB credentials rotate frequently.

Relational database connection pooling

These defaults apply to all relational database data sources (Oracle and PostgreSQL).

Environment Variable	Description	Default Value
`FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES`	Maximum cached JDBC connection pools	`100`
`FLOWX_JDBC_CONNECTIONS_CACHE_TTL`	Time-to-live for cached connection pools (duration format, e.g. `1d`, `12h`)	`1d`
`FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE`	Maximum HikariCP pool size per data source	`5`
`FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS`	JDBC connection timeout	`10`
`FLOWX_SQL_DEFAULTS_ROW_LIMIT`	Default row cap on `SELECT` responses	`1000`
`FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS`	Query execution timeout	`30`

Increase FLOWX_SQL_DEFAULTS_ROW_LIMIT if your workflows need to read more than 1000 rows in a single query. Adjust FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS for long-running analytical queries.

Configuring logging

Control log levels for different components of the service:

Environment Variable	Description	Default Value
`LOGGING_CONFIG_FILE`	Path to the logging configuration file	`logback-spring.xml`
`LOGGING_LEVEL_ROOT`	Root logger level for the Spring Boot service	`INFO`
`LOGGING_LEVEL_APP`	Application-specific log level	`INFO`

Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.

Configuring application management

Configure management endpoints and monitoring capabilities:

Environment Variable	Description	Default Value
`MANAGEMENT_SERVER_PORT`	Port for management endpoints	`8081`
`MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE`	Health checks for liveness probes	`ping,buildInfo`
`MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE`	Health checks for readiness probes	`ping,buildInfo,mongo`
`MANAGEMENT_HEALTH_KUBERNETES_ENABLED`	Enable Kubernetes health checks	`false`

Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:

Environment Variable	Description	Default Value
`MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED`	Enable Prometheus metrics export	`false`

The older form MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED also works (both resolve to the same setting). The property path above is the preferred form.

Troubleshooting

Common issues

MongoDB connection failures

Symptoms: Service fails to start with database connection errors.Solutions:

Verify MongoDB connection string format and credentials
Ensure MongoDB replica set is properly configured and accessible
Check network connectivity between service and MongoDB instances
Verify MongoDB user permissions and database access rights

Kafka connectivity issues

Symptoms: Service cannot consume or produce Kafka messages.Solutions:

Verify SPRING_KAFKA_BOOTSTRAP_SERVERS points to the correct broker(s)
Check Kafka security protocol and authentication configuration
Ensure network policies allow traffic to the Kafka cluster
Verify topic names and consumer group assignments are correct

OAuth authentication errors

Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:

Verify OAuth client ID and client secret are correct
Check OAuth server URL and realm configuration
Ensure OAuth provider is accessible from the service
Validate token endpoint URI configuration

Insert fails with '_id is a reserved keyword'

Symptoms: An Insert or Insert Many operation returns 400 Bad Request with the message _id is a reserved keyword.Cause: _id is reserved and assigned by MongoDB. Supplying it on insert was never supported and could break later reads, so starting with FlowX.AI 5.9.1 it is rejected.Solution: Remove the _id field from the insert payload. If you need to keep a specific identifier, store it under a different key (for example, externalId).

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup

Microservices

AI Platform

Plugins

Observability

Access management

NoSQL DB Runner

Configuration

Database configuration

Configuring authorization & access roles

FlowX operations document limit

External MongoDB connection caching

Relational database connection pooling

Configuring logging

Configuring application management

Prometheus metrics configuration

Troubleshooting

Common issues

Redis Configuration

Kafka Authentication

IAM Configuration

​Configuration

​Database configuration

​Configuring authorization & access roles

​FlowX operations document limit

​External MongoDB connection caching

​Relational database connection pooling

​Configuring logging

​Configuring application management

​Prometheus metrics configuration

​Troubleshooting

​Common issues

​Related resources

Redis Configuration

Kafka Authentication

IAM Configuration

Configuration

Database configuration

Configuring authorization & access roles

FlowX operations document limit

External MongoDB connection caching

Relational database connection pooling

Configuring logging

Configuring application management

Prometheus metrics configuration

Troubleshooting

Common issues

Related resources