> ## 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

Configure the following variables to connect to your identity management platform:

| Environment Variable                                                | Description                              | Default Value                                                                                    |
| ------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `SECURITY_TYPE`                                                     | Security type                            | `oauth2`                                                                                         |
| `SECURITY_OAUTH2_BASESERVERURL`                                     | Base URL of your OpenID Connect provider |                                                                                                  |
| `SECURITY_OAUTH2_REALM`                                             | OAuth2 realm name                        |                                                                                                  |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`                                  | Client ID for token introspection        |                                                                                                  |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`                              | Client secret for token introspection    |                                                                                                  |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`                   | Service account client ID                | `flowx-task-management-plugin-sa`                                                                |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`               | Service account client secret            |                                                                                                  |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Provider token URI                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token` |

<Info>
  A dedicated service account must be configured in your OpenID provider. The task management service account requires `view-users`, `query-users`, and `query-groups` client roles from realm-management to support task auto-assignment.
</Info>

### OpenID connect settings

<Info>
  The Task Management plugin supports Microsoft Entra ID as an OpenID provider.
</Info>

| Environment Variable       | Description                         | Default Value                                     |
| -------------------------- | ----------------------------------- | ------------------------------------------------- |
| `OPENID_PROVIDER`          | Type of OpenID provider             | `keycloak` (possible values: `keycloak`, `entra`) |
| `OPENID_ENTRA_TENANTID`    | Tenant ID for Microsoft Entra ID    | -                                                 |
| `OPENID_ENTRA_PRINCIPALID` | Principal ID for Microsoft Entra ID | -                                                 |
| `OPENID_ENTRA_GRAPHSCOPE`  | Graph scope for Microsoft Entra ID  | `https://graph.microsoft.com/.default`            |

For more detailed information about configuring the service account:

<Card title="Task Management Service Account" href="../setup-guides/access-management/configuring-an-iam-solution#task-management-service-account" icon="file" />

### 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`                                                                                                                                                              |

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

### Runtime MongoDB configuration

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

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. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |

### 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        |

<Info>
  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.
</Info>

<Info>
  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.
</Info>

## 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` |

<Info>
  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`.
</Info>

### 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`       |

<Info>
  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.
</Info>

## 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 configuration

The Task Management plugin 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](./ingress-configuration).

**Service-specific values for Task Management Plugin:**

* **Ingress name:** `task-management-plugin-admin`
* **Service path:** `/task(/|$)(.*)(/|$)(.*)`
* **Service name:** `task-management-plugin`
* **Rewrite target:** `/$2`
* **Fx-Workspace-Id:** Required

<Card title="Complete Ingress Configuration" href="./ingress-configuration" icon="network-wired">
  View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.
</Card>

## 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` |


## Related topics

- [Task management](/5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview.md)
- [Task Management localization](/5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization.md)
- [Configuring access roles for processes](/5.1/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes.md)
- [Configuring an IAM solution (Keycloak)](/5.1/setup-guides/access-management/configuring-an-iam-solution.md)
- [User task node](/5.1/docs/building-blocks/node/user-task-node.md)