Task management setup

The Task Management plugin is available as a Docker image and serves as a dedicated microservice within the FlowX platform ecosystem.

Dependencies

Before setting up the plugin, ensure you have the following dependencies:

A MongoDB database for task storage
A connection to the RuntimeDB for operational data
Access to the database used by the FlowX Engine
Connection to the Kafka instance used by the FlowX Engine
A Redis instance for caching and performance optimization

While many configuration properties come pre-configured, several environment variables must be explicitly set for proper functionality.

Authorization configuration & access roles

The Task Management plugin 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-task-management-plugin-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`

Starting with 5.9.0, the Task Management plugin no longer connects to the identity provider for user lookup. Task operations resolve users through FlowX runtime authorization instead. The previously required view-users, query-users, and query-groups realm-management roles on the service account, the OPENID_PROVIDER / OPENID_ENTRA_* settings, and the openid: Helm values block are obsolete and can be removed from your deployment.

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 more detailed information about configuring the service account:

Task Management Service Account

FlowX Engine datasource configuration

The service needs access to process instance data from the engine database. Configure these connection parameters:

Environment Variable	Description	Default Value
`SPRING_DATASOURCE_URL`	JDBC URL for the engine database	`jdbc:postgresql://onboardingdb:5432/onboarding`
`SPRING_DATASOURCE_USERNAME`	Database username	`postgres`
`SPRING_DATASOURCE_PASSWORD`	Database password	`password`

MongoDB configuration

Configure access to the primary MongoDB instance:

Environment Variable	Description	Default Value
`SPRING_DATA_MONGODB_URI`	MongoDB connection URI	`mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/task-management-plugin`
`DB_USERNAME`	MongoDB username	`task-management-plugin`
`DB_PASSWORD`	MongoDB password	`password`

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

Runtime MongoDB configuration

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

Enable the Runtime MongoDB connection:

Environment Variable	Description	Default Value
`SPRING_DATA_MONGODB_RUNTIME_ENABLED`	Enable runtime MongoDB connection	`true`
`SPRING_DATA_MONGODB_RUNTIME_URI`	URI for connecting to MongoDB Runtime	`mongodb://${RUNTIME_DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false`
`RUNTIME_DB_USERNAME`	Username for runtime database	`app-runtime`
`RUNTIME_DB_PASSWORD`	Password for runtime database	`password`

Redis configuration

Task Management Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables. 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.

Kafka configuration

Configure the Kafka integration using these environment variables:

Core Kafka settings

Environment Variable	Description	Default Value
`SPRING_KAFKA_BOOTSTRAPSERVERS`	Address of the Kafka server(s)	`localhost:9092`
`SPRING_KAFKA_SECURITY_PROTOCOL`	Security protocol for Kafka connections	`PLAINTEXT`
`SPRING_KAFKA_CONSUMER_GROUPID`	Consumer group identifier	`task-management-plugin-consumer`
`KAFKA_MESSAGE_MAX_BYTES`	Maximum message size (bytes)	`52428800` (50 MB)
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	Retry interval after authorization exceptions (seconds)	`10`
`KAFKA_CONSUMER_THREADS`	Number of consumer threads	`3`
`KAFKA_CONSUMER_EXCLUDEUSERSTHREADS`	Number of threads for processing user exclusion events	`3`

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

Environment Variable	Description	Default Value
`KAFKA_TOPIC_NAMING_SEPARATOR`	Primary separator for topic names	`.`
`KAFKA_TOPIC_NAMING_SEPARATOR2`	Secondary separator for topic names	`-`
`KAFKA_TOPIC_NAMING_PACKAGE`	Package prefix for topic names	`ai.flowx.`
`KAFKA_TOPIC_NAMING_ENVIRONMENT`	Environment segment for topic names
`KAFKA_TOPIC_NAMING_VERSION`	Version suffix for topic names	`.v1`

Kafka topics

Process management topics

Environment Variable	Description	Default Value
`KAFKA_TOPIC_PROCESS_START_OUT`	Topic for running hooks	`ai.flowx.core.trigger.start.process.v1`
`KAFKA_TOPIC_PROCESS_OPERATIONS_OUT`	Topic for task operations (assign, unassign, etc.)	`ai.flowx.core.trigger.operation.v1`
`KAFKA_TOPIC_PROCESS_OPERATIONS_BULKOUT`	Topic for bulk operations on tasks	`ai.flowx.core.trigger.operations.bulk.v1`

Scheduling topics

Environment Variable	Description	Default Value
`KAFKA_TOPIC_PROCESS_SCHEDULE_IN`	Topic for receiving scheduler messages for hooks	`ai.flowx.plugin.tasks.trigger.run.hook.v1`
`KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET`	Topic for setting schedules	`ai.flowx.core.trigger.set.schedule.v1`
`KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP`	Topic for stopping schedules	`ai.flowx.core.trigger.stop.schedule.v1`

User management topics

Environment Variable	Description	Default Value
`KAFKA_TOPIC_EXCLUDEUSERS_SCHEDULE_IN`	Topic for user exclusion events	`ai.flowx.plugin.tasks.trigger.exclude.users.v1`

Task operations topics

Environment Variable	Description	Default Value
`KAFKA_TOPIC_TASK_IN`	Topic for incoming task creation messages	`ai.flowx.plugin.tasks.trigger.save.task.v1`

Events and integration topics

Environment Variable	Description	Default Value
`KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`	Topic for Events Gateway messages	`ai.flowx.eventsgateway.receive.taskmanager.commands.message.v1`
`KAFKA_TOPIC_RESOURCESUSAGES_REFRESH`	Topic for resource usage refresh events	`ai.flowx.application-version.resources-usages.refresh.v1`

The Engine listens for messages on topics with specific naming patterns. Ensure you use the correct outgoing topic names when configuring the Task Management plugin to maintain proper communication with the engine.

CAS lib configuration

Environment Variable	Description	Default Value
`FLOWX_SPICEDB_HOST`	SpiceDB server hostname	`spicedb`
`FLOWX_SPICEDB_PORT`	SpiceDB server port	`50051`
`FLOWX_SPICEDB_TOKEN`	SpiceDB authentication token	`spicedb-token`

Logging configuration

Control logging verbosity with these environment variables:

Environment Variable	Description	Default Value
`LOGGING_LEVEL_ROOT`	Root Spring Boot microservice logs	-
`LOGGING_LEVEL_APP`	Application-level logs	`DEBUG`
`LOGGING_LEVEL_MONGO_DRIVER`	MongoDB driver logs	`INFO`
`LOGGING_LEVEL_REDIS`	Redis/Lettuce client log level	`OFF`

Ingress and CORS

The Task Management plugin is exposed on both the admin and public hosts. 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 routes

Host group	External path	Backend receives
admin	`/task`	`/`
public	`/task`	`/`

Paths are set through services.task-management-plugin.ingress.admin.path / services.task-management-plugin.ingress.public.path (or the corresponding gateway.<key>.paths) in the chart values.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOW_ORIGIN`	Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Task Management.	`-`

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.

Filtering feature

Environment Variable	Description
`FLOWX_ALLOW_USERNAME_SEARCH_PARTIAL`	Enables filtering possible assignees by partial names

Scheduled jobs

Configure scheduled maintenance jobs:

Environment Variable	Description	Default Value
`SCHEDULER_USERSCACHESCLEANUP_CRONEXPRESSION`	Cron expression for user cache cleanup	`0 0 0 * *?` (daily at midnight)

Resource usage monitoring

The plugin includes a resource usage monitoring feature that can be configured:

Environment Variable	Description	Default Value
`FLOWX_LIB_RESOURCESUSAGES_ENABLED`	Enable resource usage tracking	`true`
`FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED`	Enable refresh listener	`true`
`FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT`	Number of threads for resource collection	`5`
`FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE`	Maximum batch size for collection	`1000`
`FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGES_REFRESH`	Consumer group for resource usage refresh events	`taskMgmtResourcesUsagesRefreshGroup`
`FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGES_REFRESH`	Number of threads for processing resource usage events	`3`

Database migration

The Task Management plugin uses Mongock for MongoDB migrations:

Environment Variable	Description	Default Value
`MONGOCK_CHANGELOGSSCANPACKAGE`	Package to scan for database change logs	`ai.flowx.task.management.config.mongock`

​Dependencies

​Authorization configuration & access roles

Task Management Service Account

​FlowX Engine datasource configuration

​MongoDB configuration

​Runtime MongoDB configuration

​Redis configuration

​Kafka configuration

​Core Kafka settings

​OAuth authentication (when using SASL_PLAINTEXT)

​Topic naming configuration

​Kafka topics

​Process management topics

​Scheduling topics

​User management topics

​Task operations topics

​Events and integration topics

​CAS lib configuration

​Logging configuration

​Ingress and CORS

​Service routes

​CORS configuration

​Filtering feature

​Scheduled jobs

​Resource usage monitoring

​Database migration

Dependencies

Authorization configuration & access roles

FlowX Engine datasource configuration

MongoDB configuration

Runtime MongoDB configuration

Redis configuration

Kafka configuration

Core Kafka settings

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Kafka topics

Process management topics

Scheduling topics

User management topics

Task operations topics

Events and integration topics

CAS lib configuration

Logging configuration

Ingress and CORS

Service routes

CORS configuration

Filtering feature

Scheduled jobs

Resource usage monitoring

Database migration