> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Task management setup
> Configure and deploy the Task Management plugin as a Docker microservice within the FlowX platform.
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](https://www.mongodb.com/) 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](https://redis.io/) 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](/5.9/docs/platform-deep-dive/user-roles-management/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](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
For more detailed information about configuring the 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](/5.1/setup-guides/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..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](./ingress-configuration).
## 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` |