> ## 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` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

> [!WARNING]
>
> **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](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/authentication-iam.md) 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://paperflow:password@jx-notification-mdb:27017/notification` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | Runtime MongoDB connection URI | `mongodb://${DB_USERNAME:paperflow}:${DB_PASSWORD:password}@jx-app-runtime-mdb:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME` | Runtime MongoDB username, referenced as a placeholder by the default runtime URI. Optional — if you override the full URI, set the credentials there instead. | `paperflow` |
| `DB_PASSWORD` | Runtime MongoDB password, referenced as a placeholder by the default runtime URI. Optional — see `DB_USERNAME`. | `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 |

> [!NOTE]
>
> 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.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](https://docs.flowx.ai/5.1/setup-guides/redis-configuration.md) 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` |

> [!NOTE]
>
> 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](https://docs.flowx.ai/6.x/docs/building-blocks/actions/send-notification-action.md)) | `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` |

> [!NOTE]
>
> 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**](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md#general-storage-configuration) - defined in the Documents Plugin configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
> * [**CMS Core public bucket**](https://docs.flowx.ai/6.x/setup-guides/cms-setup.md#configuring-file-storage) - defined in the CMS Core configuration via `APPLICATION_FILESTORAGE_S3_BUCKETNAME`
> * [**Integration Designer bucket**](https://docs.flowx.ai/6.x/setup-guides/integration-designer-setup.md#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

> [!NOTE]
>
> The Notifications plugin sends email over **SMTP only**. It does not support Microsoft 365 / Microsoft Graph authentication (Azure AD client secret or certificate). To send through Microsoft 365, configure a **Microsoft Outlook** data source in the Integration Designer — that path runs through the email-gateway and uses the MS Graph API. See [Microsoft Outlook](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/microsoft-outlook-data-source.md).

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_FROMEMAIL` | Default sender email address | `notification.test@flowx.ai` |
| `APPLICATION_MAIL_FROMNAME` | Default sender name | `Notification` |

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

> [!WARNING]
>
> 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` (100 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_ALLOWORIGIN` | 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](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md).

***

## Troubleshooting

### Common issues

> [accordion] Notifications not being sent
>
> **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`

> [accordion] OTP generation fails
>
> **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

> [accordion] Notification templates not rendering
>
> **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

> [accordion] Firebase push notifications not working
>
> **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

> [card] [Sending Notifications](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification.md)
>
> Learn how to configure and send notifications from your processes

> [card] [Email Gateway Setup](https://docs.flowx.ai/6.x/setup-guides/email-gateway-setup.md)
>
> Configure the Email Gateway for inbound and outbound email processing

> [card] [Redis Configuration](https://docs.flowx.ai/6.x/setup-guides/redis-configuration.md)
>
> Complete Redis setup including Sentinel and Cluster modes


## Related topics

- [Plugins setup](https://docs.flowx.ai/6.x/setup-guides/plugins-setup-guide/plugins-setup-guide-overview.md)
- [OCR plugin setup](https://docs.flowx.ai/6.x/setup-guides/plugins-setup-guide/ocr-plugin-setup.md)
- [Documents plugin setup](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md)
- [Notification Templates](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview.md)
- [Data-Sync job setup](https://docs.flowx.ai/6.x/setup-guides/data-sync.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.