> ## 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.
# Notifications plugin setup
> The Notifications plugin is available as a Docker image, and it has the following dependencies.
## Dependencies
Before setting up the plugin, ensure you have the following dependencies:
* A [MongoDB](https://www.mongodb.com/2) database for storing notification templates and records
* Access to the Kafka instance used by the FlowX.AI Engine
* A [Redis](https://redis.io/) instance for caching notification templates
* An S3-compatible file storage solution (for example [MinIO](http://min.io/)) if you need to attach documents to notifications
***
## Authorization configuration
The Notifications plugin validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:
| 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 | |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
**Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. 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.
***
## MongoDB configuration
The only thing that needs to be configured is the DB access info, the rest will be handled by the plugin.
| 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/notification-plugin` |
| `DB_USERNAME` | Username for runtime MongoDB connection | `notification-plugin` |
| `DB_PASSWORD` | Password for runtime MongoDB connection | `password` |
***
## Redis configuration
Notification 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
### 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 | `notification-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 | `1` |
### Consumer error handling
| Environment Variable | Description | Default Value |
| -------------------------------------------- | -------------------------------------------- | ------------- |
| `KAFKA_CONSUMER_ERRORHANDLING_ENABLED` | Enable consumer error handling | `false` |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRIES` | Number of retry attempts for failed messages | `0` |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` | Interval between retries (milliseconds) | `1000` |
### 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_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_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |
### Topic configurations
Each action in the service corresponds to a Kafka event on a specific topic. Configure the following topics:
#### OTP topics
| Environment Variable | Description | Default Value |
| ------------------------------ | ------------------------------------------ | --------------------------------------------------------------------- |
| `KAFKA_TOPIC_OTP_GENERATE_IN` | Topic for incoming OTP generation requests | `ai.flowx.plugin.notification.trigger.generate.otp.v1` |
| `KAFKA_TOPIC_OTP_GENERATE_OUT` | Topic for OTP generation results | `ai.flowx.engine.receive.plugin.notification.generate.otp.results.v1` |
| `KAFKA_TOPIC_OTP_VALIDATE_IN` | Topic for incoming OTP validation requests | `ai.flowx.plugin.notification.trigger.validate.otp.v1` |
| `KAFKA_TOPIC_OTP_VALIDATE_OUT` | Topic for OTP validation results | `ai.flowx.engine.receive.plugin.notification.validate.otp.results.v1` |
#### Notification topics
| Environment Variable | Description | Default Value |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` | Topic for incoming notification requests from the process engine (used by both Kafka-forwarded notifications and the [Send Notification action](../docs/building-blocks/actions/send-notification-action)) | `ai.flowx.plugin.notification.trigger.send.notification.v1` |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` | Topic for notification delivery confirmations | `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1` |
| `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` | Topic for forwarding notifications to external systems | `ai.flowx.plugin.notification.trigger.forward.notification.v1` |
#### Audit topic
| Environment Variable | Description | Default Value |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |
#### Resource usages topics
| Environment Variable | Description | Default Value |
| ------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------ |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Topic for resource usages refresh events | `ai.flowx.application-version.resources-usages.refresh.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_RESPONSE` | Topic for sub-resource validation responses | `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_OUT` | Topic for bulk resource usage operations | `ai.flowx.application-version.resources-usages.operations.bulk.v1` |
***
## File storage configuration
Based on use case you can use directly a file system or an S3 compatible cloud storage solution (for example [min.io](http://min.io/)).
The file storage solution can be configured using the following environment variables:
| Environment Variable | Description | Default Value |
| ---------------------------------------------- | ------------------------------------------------ | ----------------------------- |
| `APPLICATION_FILESTORAGE_TYPE` | Storage type to use (`s3` or `fileSystem`) | `s3` |
| `APPLICATION_FILESTORAGE_DISKDIRECTORY` | Directory for file storage when using filesystem | `MS_SVC_NOTIFICATION` |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | Enable S3-compatible storage | `true` |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | URL of MinIO or S3-compatible server | `http://minio-service:9000` |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable server-side encryption | `false` |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | Access key for S3 | `minio` |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | Secret key for S3 | `secret` |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | Prefix for bucket names | `qdevlocal-preview-paperflow` |
When using S3-compatible storage for notifications with attachments, the S3 user configured through `APPLICATION_FILESTORAGE_S3_ACCESSKEY` and `APPLICATION_FILESTORAGE_S3_SECRETKEY` must have read access to multiple buckets beyond its own:
Required bucket access:
* **Own bucket** - defined by `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
* [**Documents Plugin bucket**](./documents-plugin-setup#general-storage-configuration) - defined in the Documents Plugin configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
* [**CMS Core public bucket**](./cms-setup#configuring-file-storage) - defined in the CMS Core configuration via `APPLICATION_FILESTORAGE_S3_BUCKETNAME`
* [**Integration Designer bucket**](./integration-designer-setup#storage-configuration) - defined in the Integration Designer configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
Ensure your S3 user has appropriate read permissions to all releva dnt buckets to avoid attachment failures.
***
## SMTP setup
Configure SMTP settings for sending email notifications:
| Environment Variable | Description | Default Value |
| ---------------------------------- | ----------------------------------------------------------- | ---------------------------- |
| `SIMPLEJAVAMAIL_SMTP_HOST` | SMTP server hostname | `smtp.gmail.com` |
| `SIMPLEJAVAMAIL_SMTP_PORT` | SMTP server port | `587` |
| `SIMPLEJAVAMAIL_SMTP_USERNAME` | SMTP server username | `notification.test@flowx.ai` |
| `SIMPLEJAVAMAIL_SMTP_PASSWORD` | SMTP server password | `paswword` |
| `SIMPLEJAVAMAIL_TRANSPORTSTRATEGY` | Email transport strategy (e.g., `SMTP`, `EXTERNAL_FORWARD`) | `SMTP` |
| `SIMPLEJAVAMAIL_JAVAXMAIL_DEBUG` | Verbose JavaMail SMTP debug logging | `false` |
| `APPLICATION_MAIL_FROM_EMAIL` | Default sender email address | `notification.test@flowx.ai` |
| `APPLICATION_MAIL_FROM_NAME` | Default sender name | `Notification Test` |
### Advanced SMTP options
The notification plugin sends email through the [simple-java-mail](https://www.simplejavamail.org/) library, which auto-binds every `simplejavamail.*` property — set them as environment variables the same way as the values above. The options below come up most often when connecting to corporate SMTP relays:
| Environment Variable | Description | Default Value |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` | Verify that the hostname in the server's TLS certificate matches the configured SMTP host. Set to `false` for relays whose certificate doesn't match the configured hostname; the connection stays encrypted | `true` |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS` | Semicolon-delimited list of hosts whose TLS certificates are trusted without chain validation | – |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS` | Accept any TLS certificate without chain validation. Prefer `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS` | `false` |
| `SIMPLEJAVAMAIL_DEFAULTS_SESSIONTIMEOUTMILLIS` | Socket timeout (in milliseconds) for the SMTP session. Raise for slow relays | `60000` |
These defaults load into the library's global configuration, so they apply to **all** mailers the plugin creates — including the ones built dynamically for Email Sender systems configured in the Integration Designer, whose settings override only the connection fields (host, port, username, password, transport strategy). Changing `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` or `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS` therefore affects every configured email system.
For the full list of available properties (connection pooling, embedded image resolution, and more), see the [simple-java-mail configuration reference](https://www.simplejavamail.org/configuration.html).
***
## Email attachments configuration
Configure handling of email attachments:
| Environment Variable | Description | Default Value |
| -------------------------------------- | ------------------------------------------ | ------------- |
| `SPRING_HTTP_MULTIPART_MAXFILESIZE` | Maximum file size for attachments | `15MB` |
| `SPRING_HTTP_MULTIPART_MAXREQUESTSIZE` | Maximum request size for multipart uploads | `15MB` |
***
## OTP configuration
Configure One-Time Password generation and validation:
| Environment Variable | Description | Default Value |
| ------------------------------- | -------------------------------------- | ------------------- |
| `FLOWX_OTP_LENGTH` | Number of characters in generated OTPs | `4` |
| `FLOWX_OTP_EXPIRETIMEINSECONDS` | Expiry time for OTPs (seconds) | `6000` (10 minutes) |
***
## Logging configuration
Control logging levels for different components:
| Environment Variable | Description | Default Value |
| ---------------------------- | ----------------------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level | - |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver log level | `INFO` |
| `LOGGING_LEVEL_THYMELEAF` | Thymeleaf template engine log level | `INFO` |
| `LOGGING_LEVEL_FCM_CLIENT` | Firebase Cloud Messaging client log level | `OFF` |
| `LOGGING_LEVEL_REDIS` | Redis/Lettuce client log level | `OFF` |
***
## 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 | `-` |
***
## Usage notes
### Topic naming convention
Topics follow a standardized naming convention:
* Example: `ai.flowx.plugin.notification.trigger.generate.otp.v1`
* Structure: `{package}{environment}.{component}.{action}.{subject}.{version}`
### Consumer error handling
When `KAFKA_CONSUMER_ERRORHANDLING_ENABLED` is set to `true`:
* The application will retry processing failed messages according to `KAFKA_CONSUMER_ERRORHANDLING_RETRIES`
* Between retries, the application will wait for the duration specified by `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL`
For example, if `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` is set to 5000 (5 seconds) and `KAFKA_CONSUMER_ERROR_HANDLING_RETRIES` is set to 5, the consumer application will make up to 5 attempts, waiting 5 seconds between each attempt.
### Message size configuration
The `KAFKA_MESSAGE_MAX_BYTES` setting affects multiple Kafka properties:
* `spring.kafka.producer.properties.message.max.bytes`
* `spring.kafka.producer.properties.max.request.size`
* `spring.kafka.consumer.properties.max.partition.fetch.bytes`
### OAuth authentication
When using the 'kafka-auth' profile, the security protocol changes to 'SASL\_PLAINTEXT' and requires OAuth configuration via the `KAFKA_OAUTH_*` variables.
***
## Ingress and CORS
The Notification plugin 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 group | External path | Backend receives |
| ---------- | --------------- | ---------------- |
| admin | `/notification` | `/` |
The path is set through `services.notification-plugin.ingress.admin.path` (or `services.notification-plugin.gateway.admin.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 and integration domain that issues browser requests against Notification. | `-` |
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).
***
## Troubleshooting
### Common issues
**Symptoms:** Notification requests are accepted but emails or messages are never delivered.
**Solutions:**
1. Verify Kafka topics are correctly configured and the notification plugin is consuming from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`
2. Check SMTP configuration (`SIMPLEJAVAMAIL_SMTP_HOST`, port, credentials) and ensure the SMTP server is reachable from the pod
3. If using the Email Gateway for forwarding, verify `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` is configured and the Email Gateway is running
4. Check application logs for delivery errors by setting `LOGGING_LEVEL_APP` to `DEBUG`
**Symptoms:** OTP requests return errors or no OTP is generated.
**Solutions:**
1. Verify OTP configuration values (`FLOWX_OTP_LENGTH`, `FLOWX_OTP_EXPIRETIMEINSECONDS`) are set correctly
2. Check that Kafka topics `KAFKA_TOPIC_OTP_GENERATE_IN` and `KAFKA_TOPIC_OTP_GENERATE_OUT` are created and accessible
3. Ensure MongoDB is reachable and the notification plugin database has write permissions
4. Verify Kafka consumer group `SPRING_KAFKA_CONSUMER_GROUPID` is not conflicting with another instance
**Symptoms:** Notifications are sent but contain raw template syntax or missing values.
**Solutions:**
1. Verify substitution tags in the template match the keys provided in the notification request payload
2. Check that the Thymeleaf engine is functioning by reviewing logs at `LOGGING_LEVEL_THYMELEAF` set to `DEBUG`
3. Ensure the template exists in MongoDB and is in the correct format
4. Verify Redis cache is not serving stale templates — clear the cache or restart the plugin if templates were recently updated
**Symptoms:** Push notifications are not delivered to mobile devices.
**Solutions:**
1. Verify Firebase Cloud Messaging credentials are correctly configured
2. Check that the target device has a valid FCM registration token
3. Enable FCM client logging by setting `LOGGING_LEVEL_FCM_CLIENT` to `DEBUG` to inspect request/response details
4. Ensure network policies allow outbound HTTPS traffic to Firebase servers (`fcm.googleapis.com`)
***
## Related resources
Learn how to configure and send notifications from your processes
Configure the Email Gateway for inbound and outbound email processing
Complete Redis setup including Sentinel and Cluster modes