Notifications plugin setup

Dependencies

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

A MongoDB database for storing notification templates and records
Access to the Kafka instance used by the FlowX.AI Engine
A Redis instance for caching notification templates
An S3-compatible file storage solution (for example MinIO) 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`

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

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

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)	`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). 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 - defined in the Documents Plugin configuration via APPLICATION_FILESTORAGE_S3_BUCKETPREFIX
CMS Core public bucket - defined in the CMS Core configuration via APPLICATION_FILESTORAGE_S3_BUCKETNAME
Integration Designer bucket - 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

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.

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

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.

Troubleshooting

Common issues

Notifications not being sent

Symptoms: Notification requests are accepted but emails or messages are never delivered.Solutions:

Verify Kafka topics are correctly configured and the notification plugin is consuming from KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN
Check SMTP configuration (SIMPLEJAVAMAIL_SMTP_HOST, port, credentials) and ensure the SMTP server is reachable from the pod
If using the Email Gateway for forwarding, verify KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT is configured and the Email Gateway is running
Check application logs for delivery errors by setting LOGGING_LEVEL_APP to DEBUG

OTP generation fails

Symptoms: OTP requests return errors or no OTP is generated.Solutions:

Verify OTP configuration values (FLOWX_OTP_LENGTH, FLOWX_OTP_EXPIRETIMEINSECONDS) are set correctly
Check that Kafka topics KAFKA_TOPIC_OTP_GENERATE_IN and KAFKA_TOPIC_OTP_GENERATE_OUT are created and accessible
Ensure MongoDB is reachable and the notification plugin database has write permissions
Verify Kafka consumer group SPRING_KAFKA_CONSUMER_GROUPID is not conflicting with another instance

Notification templates not rendering

Symptoms: Notifications are sent but contain raw template syntax or missing values.Solutions:

Verify substitution tags in the template match the keys provided in the notification request payload
Check that the Thymeleaf engine is functioning by reviewing logs at LOGGING_LEVEL_THYMELEAF set to DEBUG
Ensure the template exists in MongoDB and is in the correct format
Verify Redis cache is not serving stale templates — clear the cache or restart the plugin if templates were recently updated

Firebase push notifications not working

Symptoms: Push notifications are not delivered to mobile devices.Solutions:

Verify Firebase Cloud Messaging credentials are correctly configured
Check that the target device has a valid FCM registration token
Enable FCM client logging by setting LOGGING_LEVEL_FCM_CLIENT to DEBUG to inspect request/response details
Ensure network policies allow outbound HTTPS traffic to Firebase servers (fcm.googleapis.com)

Sending Notifications

Learn how to configure and send notifications from your processes

Email Gateway Setup

Configure the Email Gateway for inbound and outbound email processing

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Microservices

AI Platform

Plugins

Observability

Access management

Notifications plugin setup

Dependencies

Authorization configuration

MongoDB configuration

Redis configuration

Kafka configuration

Core Kafka settings

Consumer error handling

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Topic configurations

OTP topics

Notification topics

Audit topic

Resource usages topics

File storage configuration

SMTP setup

Advanced SMTP options

Email attachments configuration

OTP configuration

Logging configuration

CAS lib configuration

Usage notes

Topic naming convention

Consumer error handling

Message size configuration

OAuth authentication

Ingress and CORS

Service route

CORS configuration

Troubleshooting

Common issues

Sending Notifications

Email Gateway Setup

Redis Configuration

​Dependencies

​Authorization configuration

​MongoDB configuration

​Redis configuration

​Kafka configuration

​Core Kafka settings

​Consumer error handling

​OAuth authentication (when using SASL_PLAINTEXT)

​Topic naming configuration

​Topic configurations

​OTP topics

​Notification topics

​Audit topic

​Resource usages topics

​File storage configuration

​SMTP setup

​Advanced SMTP options

​Email attachments configuration

​OTP configuration

​Logging configuration

​CAS lib configuration

​Usage notes

​Topic naming convention

​Consumer error handling

​Message size configuration

​OAuth authentication

​Ingress and CORS

​Service route

​CORS configuration

​Troubleshooting

​Common issues

​Related resources

Sending Notifications

Email Gateway Setup

Redis Configuration

Dependencies

Authorization configuration

MongoDB configuration

Redis configuration

Kafka configuration

Core Kafka settings

Consumer error handling

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Topic configurations

OTP topics

Notification topics

Audit topic

Resource usages topics

File storage configuration

SMTP setup

Advanced SMTP options

Email attachments configuration

OTP configuration

Logging configuration

CAS lib configuration

Usage notes

Topic naming convention

Consumer error handling

Message size configuration

OAuth authentication

Ingress and CORS

Service route

CORS configuration

Troubleshooting

Common issues

Related resources