Documents plugin setup

The plugin is available as a docker image.

Dependencies

Before setting up the plugin, ensure that you have the following dependencies installed and configured:

PostgreSQL Database: You will need a PostgreSQL database to store data related to document templates and documents.
MongoDB Database: MongoDB is required for the HTML templates feature of the plugin.
Kafka: Establish a connection to the Kafka instance used by the FlowX.AI engine.
Redis: Set up a Redis instance for caching purposes.
S3-Compatible File Storage Solution: Deploy an S3-compatible file storage solution to store document files.

Configuration

The plugin comes with pre-filled configuration properties, but you need to set up a few custom environment variables to tailor it to your specific setup. Here are the key configuration steps:

Redis server

The plugin can utilize the Redis component already deployed for the FLOWX.AI engine. Make sure it is configured properly.

Authorization configuration

The Documents plugin validates incoming tokens with the JWT public key mechanism:

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_ANONYMOUSIDENTITY_CLIENTID`	Anonymous service account client ID, used for anonymous runtime access	`flowx-anonymous-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`	Anonymous service account client secret

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.

Document processing configuration

Environment Variable	Description	Default Value
`FLOWX_DEFAULTCLIENTTYPE`	Default client type	`PF`
`FLOWX_HTML_TEMPLATES_ENABLED`	Enable HTML templates feature	`false`
`FLOWX_HTML_TEMPLATES_PDFFONTPATHS`	Paths to fonts for HTML templates	`/statics/fonts/Calibri.ttf, /statics/fonts/DejaVuSans.ttf`
`FLOWX_CONVERT_DPI`	DPI setting for PDF to image conversion	`150`

Set the FLOWX_HTML_TEMPLATES_PDFFONTPATHS config to select the font used for generating documents based on PDF templates.

If you want to use specific fonts in your PDF templates, override the FLOWX_HTML_TEMPLATES_PDFFONTPATHS config. By default, Calibri and DejaVuSans are available fonts.

FLOWX_CONVERT_DPI: Sets the DPI (dots per inch) for PDF to JPEG conversion. Higher values result in higher resolution images. (Default value: 150).

After making these configurations, the fonts will be available for use within PDF templates.

Database configuration

SQL database (PostgreSQL)

The Documents Plugin uses a PostgreSQL database for relational data storage.

Environment Variable	Description	Default Value
`SPRING_DATASOURCE_URL`	JDBC connection URL for PostgreSQL	`jdbc:postgresql://jx-documentdb:5432/document`
`SPRING_DATASOURCE_USERNAME`	Database username	`postgres`
`SPRING_DATASOURCE_PASSWORD`	Database password	-
`SPRING_DATASOURCE_DRIVERCLASSNAME`	JDBC driver class	`org.postgresql.Driver`

Primary MongoDB configuration

Environment Variable	Description	Default Value
`SPRING_DATA_MONGODB_URI`	MongoDB connection URI	`mongodb://flowx:password@jx-document-mongodb:27017/document`
`MONGODB_USERNAME`	MongoDB username	`flowx`
`MONGODB_PASSWORD`	MongoDB password	`password`
`SPRING_DATA_MONGODB_REPRESENTATION_UUID`	UUID representation format	`standard`
`SPRING_DATA_MONGODB_STORAGE`	MongoDB storage type	`mongodb`

Runtime MongoDB configuration

Environment Variable	Description	Default Value
`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 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 URI. Optional — see `DB_USERNAME`.	`password`
`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION`	Enable automatic index creation	`false`
`SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID`	UUID representation format for runtime connection	`standard`

Redis configuration

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

Multipart upload configuration

Environment Variable	Description	Default Value
`SPRING_SERVLET_CONTEXTPATH`	Servlet context path	`/`
`SPRING_SERVLET_MULTIPART_MAXFILESIZE`	Maximum file size for uploads	`50MB`
`SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`	Maximum request size for multipart uploads	`50MB`

Basic Kafka configuration

Environment Variable	Description	Default Value
`KAFKA_BOOTSTRAP_SERVERS`	Address of Kafka server(s) (also accepts `SPRING_KAFKA_BOOTSTRAPSERVERS`)	`localhost:9092`
`KAFKA_SECURITY_PROTOCOL`	Security protocol for Kafka (also accepts `SPRING_KAFKA_SECURITY_PROTOCOL`)	`PLAINTEXT`
`SPRING_KAFKA_CONSUMER_GROUPID`	Consumer group ID for the service	`kafka-svc-document-consumer`
`KAFKA_MESSAGE_MAX_BYTES`	Maximum message size in bytes	`52428800` (50MB)
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	Retry interval for auth exceptions	`10` (seconds)

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`

Thread configuration

Environment Variable	Description	Default Value
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGENERATEHTMLIN`	Threads for HTML document generation	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTPERSISTIN`	Threads for document persistence	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTSPLITIN`	Threads for document splitting	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGETURLSIN`	Threads for document URL retrieval	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_OCRIN`	Threads for OCR processing	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDELETEIN`	Threads for file deletion	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEUPDATEIN`	Threads for file updates	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECONVERTIN`	Threads for file conversion	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEPERSISTIN`	Threads for file persistence	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECOMBINEIN`	Threads for file combining	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEENCRYPTIN`	Threads for file encryption	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDECRYPTIN`	Threads for file decryption	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN`	Threads for file archive	`5`
`KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEEXTRACTIN`	Threads for file extract	`5`

Document topics

Generate HTML documents

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`	Topic for incoming HTML generation requests	`ai.flowx.plugin.document.trigger.generate.html.v1`
`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`	Topic for HTML generation results	`ai.flowx.engine.receive.plugin.document.generate.html.results.v1`

Document persistence

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_PERSIST_IN`	Topic for incoming document persistence requests	`ai.flowx.plugin.document.trigger.persist.document.v1`
`KAFKA_TOPIC_DOCUMENT_PERSIST_OUT`	Topic for document persistence results	`ai.flowx.engine.receive.plugin.document.persist.document.results.v1`

Document splitting

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_SPLIT_IN`	Topic for incoming document splitting requests	`ai.flowx.plugin.document.trigger.split.document.v1`
`KAFKA_TOPIC_DOCUMENT_SPLIT_OUT`	Topic for document splitting results	`ai.flowx.engine.receive.plugin.document.split.document.results.v1`

Document URL retrieval

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_GET_URLS_IN`	Topic for incoming URL retrieval requests	`ai.flowx.plugin.document.retrieve.urls.v1`
`KAFKA_TOPIC_DOCUMENT_GET_URLS_OUT`	Topic for URL retrieval results	`ai.flowx.engine.receive.plugin.document.urls.results.v1`

OCR processing

Environment Variable	Description	Default Value
`KAFKA_TOPIC_OCR_IN`	Topic for incoming OCR requests	`ai.flowx.plugin.document.store.ocr.v1`
`KAFKA_TOPIC_OCR_OUT`	Topic for OCR processing results	`ai.flowx.engine.receive.plugin.document.ocr.results.v1`

File operation topics

File deletion

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_DELETE_IN`	Topic for incoming file deletion requests	`ai.flowx.plugin.document.trigger.delete.file.v1`
`KAFKA_TOPIC_FILE_DELETE_OUT`	Topic for file deletion results	`ai.flowx.engine.receive.plugin.document.delete.file.results.v1`

File update

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_UPDATE_IN`	Topic for incoming file update requests	`ai.flowx.plugin.document.trigger.update.file.v1`
`KAFKA_TOPIC_FILE_UPDATE_OUT`	Topic for file update results	`ai.flowx.engine.receive.plugin.document.update.file.results.v1`

File conversion

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_CONVERT_IN`	Topic for incoming file conversion requests	`ai.flowx.plugin.document.trigger.convert.file.v1`
`KAFKA_TOPIC_FILE_CONVERT_OUT`	Topic for file conversion results	`ai.flowx.engine.receive.plugin.document.convert.file.results.v1`

File persistence

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_PERSIST_IN`	Topic for incoming file persistence requests	`ai.flowx.plugin.document.trigger.persist.file.v1`
`KAFKA_TOPIC_FILE_PERSIST_OUT`	Topic for file persistence results	`ai.flowx.engine.receive.plugin.document.persist.file.results.v1`

File combination

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_COMBINE_IN`	Topic for incoming file combination requests	`ai.flowx.plugin.document.trigger.combine.file.v1`
`KAFKA_TOPIC_FILE_COMBINE_OUT`	Topic for file combination results	`ai.flowx.engine.receive.plugin.document.combine.file.results.v1`

File encryption

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_ENCRYPT_IN`	Topic for incoming file encryption requests	`ai.flowx.plugin.document.trigger.encrypt.file.v1`
`KAFKA_TOPIC_FILE_ENCRYPT_OUT`	Topic for file encryption results	`ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`

File decryption

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_DECRYPT_IN`	Topic for incoming file decryption requests	`ai.flowx.plugin.document.trigger.decrypt.file.v1`
`KAFKA_TOPIC_FILE_DECRYPT_OUT`	Topic for file decryption results	`ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`

File archive

Bundle a list of fileIds into a single (optionally password-protected) ZIP, persisted as a new Document/File. Uses the same trigger/reply pattern as encryption.

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_ARCHIVE_IN`	Topic for incoming file archive requests	`ai.flowx.plugin.document.trigger.archive.file.v1`
`KAFKA_TOPIC_FILE_ARCHIVE_OUT`	Topic for file archive results	`ai.flowx.engine.receive.plugin.document.archive.file.results.v1`

File extract

Unpack a ZIP fileId into N persisted Documents/Files. Supports plain and password-protected archives.

Environment Variable	Description	Default Value
`KAFKA_TOPIC_FILE_EXTRACT_IN`	Topic for incoming file extract requests	`ai.flowx.plugin.document.trigger.extract.file.v1`
`KAFKA_TOPIC_FILE_EXTRACT_OUT`	Topic for file extract results	`ai.flowx.engine.receive.plugin.document.extract.file.results.v1`

Bulk document persistence

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_IN`	Topic for incoming bulk document persistence	`ai.flowx.plugin.document.trigger.persist.document.bulk.v1`
`KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_OUT`	Topic for bulk document persistence results	`ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1`

UI flow session variable updates

After a UI Flow session document upload completes, the document-plugin sends the result to the process-engine so the session variables are updated automatically.

Environment Variable	Description	Default Value
`KAFKA_TOPIC_UIFLOW_UPDATE_OUT`	Topic for sending document upload results to process-engine for UI flow session variable updates	`ai.flowx.core.trigger.ui-flow.update.v1`

UI Flow multi-file upload

When a UI Flow uploads several files at once, the process-engine sends a single bulk command to document-plugin instead of one command per file. The document-plugin persists each file in the session and emits a single SSE frame (eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE, namespace=uploadBatchId) at the end of the batch via events-gateway, then forwards the per-file results to KAFKA_TOPIC_UIFLOW_UPDATE_OUT.

Environment Variable	Description	Default Value
`KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN`	Topic consumed by document-plugin to persist a single UI Flow upload session.	`ai.flowx.plugin.document.trigger.persist.document.session.v1`
`KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`	Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch.	`ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1`

Audit

Environment Variable	Description	Default Value
`KAFKA_TOPIC_AUDIT_OUT`	Topic for sending audit logs	`ai.flowx.core.trigger.save.audit.v1`

General storage configuration

Environment Variable	Description	Default Value
`APPLICATION_DEFAULTLOCALE`	Default locale for the application	`en`
`APPLICATION_SUPPORTEDLOCALES`	Comma-separated list of supported locales	`en, ro`
`APPLICATION_FILESTORAGE_TYPE`	Storage type to use (`s3` or `fileSystem`)	`s3`
`APPLICATION_FILESTORAGE_DISKDIRECTORY`	Directory for file storage when using filesystem	`MS_SVC_DOCUMENT`
`APPLICATION_FILESTORAGE_PARTITIONSTRATEGY`	Strategy for file organization (`NONE` or `PROCESS_DATE`)	`NONE`
`APPLICATION_FILESTORAGE_DELETIONSTRATEGY`	Strategy for deleting files (`delete`, `disabled`, or `deleteBypassingGovernanceRetention`)	`delete`
`APPLICATION_FILESTORAGE_TESTFILESBUCKET`	Custom bucket name for test files (overrides default `-test-documents` suffix)	`-test-documents`

APPLICATION_FILESTORAGE_DELETIONSTRATEGY:

disabled: This will disable entirely the deletion of temporary files from the temporary bucket, and the responsibility to delete and clean up the bucket will move in the ownership of the admins of the implementing project.
deleteBypassingGovernanceRetention: This will still delete the temporary files and further more will add in the delete request the header: x-amz-bypass-governance-retention:true , to enable deletion of governed files, in case the s3 configured user for document-plugin, will have the s3:BypassGovernanceRetention permission.

APPLICATION_FILESTORAGE_TESTFILESBUCKET: This variable allows you to override the default -test-documents bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed. This is particularly useful when the client environment has restrictions on bucket naming conventions or doesn’t have permissions to create new buckets.

Runtime buckets configuration

Environment Variable	Description	Default Value
`APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_ENABLED`	Enable dedicated runtime buckets for file storage	`false`
`APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_BUCKETNAME`	Name of the runtime bucket	`runtime-bucket`
`APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_PARTITIONBYDATE`	Enable date-based partitioning for runtime bucket files	`true`
`APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_STATICFILETYPE`	File-type subfolder used for non-partitioned (static) runtime files	`static`

Zip extraction configuration

Environment Variable	Description	Default Value
`ZIP_EXTRACTION_ALLOWEDEXTENSIONS`	Comma-separated list of allowed file extensions in ZIP uploads	`pdf,xls,xlsx,doc,docx,txt,jpg,jpeg,png,gif`

S3-Compatible storage configuration

Environment Variable	Description	Default Value
`APPLICATION_FILESTORAGE_S3_ENABLED`	Enable S3-compatible storage	`true`
`APPLICATION_FILESTORAGE_S3_SERVERURL`	URL of S3-compatible server	`http://minio-service:9000`
`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`
`APPLICATION_FILESTORAGE_S3_TEMPBUCKET`	Name of temporary bucket for initial file uploads	`temp-bucket`
`APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED`	Enable server-side encryption	`false`

Make sure to follow the recommended bucket naming rules when choosing the bucket prefix name.

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

Environment Variable	Description	Default Value
`LOGGING_LEVEL_APP`	Log level for application logs	`INFO`
`LOGGING_LEVEL_MONGO_DRIVER`	Log level for MongoDB driver	`INFO`
`LOGGING_LEVEL_LIQUIBASE`	Log level for Liquibase database migrations	`INFO`
`LOGGING_LEVEL_REDIS`	Log level for Redis/Lettuce client	`OFF`
`LOGGING_LEVEL_ROOT`	Root logging level for the application	-

Ingress and CORS

The Document 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	`/document`	`/`
public	`/document`	`/`

Paths are set through services.document-plugin.ingress.admin.path / services.document-plugin.ingress.public.path (or the corresponding gateway.<key>.paths) in the chart values. The chart also applies nginx.ingress.kubernetes.io/proxy-body-size: 50m by default on both routes to allow larger document uploads — adjust the annotation if you need a different limit.

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, runtime renderer, and integration domain that uploads or fetches documents from the browser.	`-`

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

File upload fails

Symptoms: File uploads return errors or time out.Solutions:

Verify the S3/MinIO connection by checking APPLICATION_FILESTORAGE_S3_SERVERURL, APPLICATION_FILESTORAGE_S3_ACCESSKEY, and APPLICATION_FILESTORAGE_S3_SECRETKEY
Ensure the target bucket exists and the configured user has read/write permissions
Check that SPRING_SERVLET_MULTIPART_MAXFILESIZE is large enough for the files being uploaded
Verify network connectivity between the pod and the S3-compatible storage service

Document generation not working

Symptoms: HTML-to-PDF document generation fails or produces empty documents.Solutions:

Verify FLOWX_HTML_TEMPLATES_ENABLED is set to true
Check that the font paths in FLOWX_HTML_TEMPLATES_PDFFONTPATHS are valid and the font files exist at those paths
Ensure the Kafka topics for HTML generation (KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN / OUT) are created and accessible
Verify MongoDB connectivity, as HTML templates are stored in MongoDB

Files not being deleted from temporary storage

Symptoms: The temporary S3 bucket grows continuously and files are not cleaned up.Solutions:

Check that APPLICATION_FILESTORAGE_DELETIONSTRATEGY is set to delete (not disabled)
If using governance-locked buckets, set the strategy to deleteBypassingGovernanceRetention and ensure the S3 user has the s3:BypassGovernanceRetention permission
Verify the temporary bucket name configured in APPLICATION_FILESTORAGE_S3_TEMPBUCKET matches the actual bucket
Check application logs for deletion errors or permission issues

PDF conversion fails

Symptoms: File conversion requests fail or return errors.Solutions:

Check that the source file format is in the supported list configured via ZIP_EXTRACTION_ALLOWEDEXTENSIONS
Verify FLOWX_CONVERT_DPI is set to a valid value (default 150)
Ensure the file is not corrupted and uses valid encoding
Check that the Kafka topics for file conversion (KAFKA_TOPIC_FILE_CONVERT_IN / OUT) are properly configured

Uploading Documents

Upload documents to processes using the Documents plugin

Generating Documents

Generate documents from HTML templates

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

​Dependencies

​Configuration

​Redis server

​Authorization configuration

​Document processing configuration

​Database configuration

​SQL database (PostgreSQL)

​Primary MongoDB configuration

​Runtime MongoDB configuration

​Redis configuration

​Multipart upload configuration

​Basic Kafka configuration

​OAuth authentication (when using SASL_PLAINTEXT)

​Topic naming configuration

​Thread configuration

​Document topics

​Generate HTML documents

​Document persistence

​Document splitting

​Document URL retrieval

​OCR processing

​File operation topics

​File deletion

​File update

​File conversion

​File persistence

​File combination

​File encryption

​File decryption

​File archive

​File extract

​Bulk document persistence

​UI flow session variable updates

​UI Flow multi-file upload

​Audit

​General storage configuration

​Runtime buckets configuration

​Zip extraction configuration

​S3-Compatible storage configuration

​CAS lib configuration

​Logging configuration

​Ingress and CORS

​Service routes

​CORS configuration

​Troubleshooting

​Common issues

​Related resources

Uploading Documents

Generating Documents

Redis Configuration

Dependencies

Configuration

Redis server

Authorization configuration

Document processing configuration

Database configuration

SQL database (PostgreSQL)

Primary MongoDB configuration

Runtime MongoDB configuration

Redis configuration

Multipart upload configuration

Basic Kafka configuration

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Thread configuration

Document topics

Generate HTML documents

Document persistence

Document splitting

Document URL retrieval

OCR processing

File operation topics

File deletion

File update

File conversion

File persistence

File combination

File encryption

File decryption

File archive

File extract

Bulk document persistence

UI flow session variable updates

UI Flow multi-file upload

Audit

General storage configuration

Runtime buckets configuration

Zip extraction configuration

S3-Compatible storage configuration

CAS lib configuration

Logging configuration

Ingress and CORS

Service routes

CORS configuration

Troubleshooting

Common issues

Related resources