Skip to main content
Available since FlowX.AI v5.5The document encryption/decryption feature is available starting with FlowX.AI version 5.5.

​
Overview

The Documents plugin provides file encryption and decryption capabilities through Kafka messaging. This feature allows you to:
  • Encrypt files - Password-protect one or multiple files stored in the Documents plugin
  • Decrypt files - Unlock password-protected files and extract contents from encrypted ZIP archives
Both operations are triggered via Kafka messages. Internal HTTP endpoints are also available for testing purposes.

​
Supported file types

FormatExtensions
PDF.pdf
Microsoft Word.doc, .docx
Microsoft Excel.xls, .xlsx
ZIP.zip
When encrypting multiple files, they are automatically bundled into a password-protected ZIP archive. During decryption, ZIP archives are extracted and only files matching supported types are returned.

​
Prerequisites

Before using the encryption/decryption features, ensure:
The Documents plugin is deployed and configured in your environment
Files are already uploaded to the Documents plugin (you’ll need file IDs)
Kafka topics are properly configured

​
Kafka topics

The encryption and decryption operations use dedicated Kafka topics for communication between the FlowX Engine and the Documents plugin.

​
Topic configuration

Environment VariableDefault Topic NameDirectionDescription
KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_INai.flowx.plugin.document.trigger.encrypt.file.v1InboundTopic for encryption requests
KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_INai.flowx.plugin.document.trigger.decrypt.file.v1InboundTopic for decryption requests
KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_OUTai.flowx.engine.receive.plugin.document.encrypt.file.results.v1OutboundTopic for encryption results
KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_OUTai.flowx.engine.receive.plugin.document.decrypt.file.results.v1OutboundTopic for decryption results
To find the configured topic names in your environment:
  1. Navigate to FlowX Designer → Platform Status
  2. Locate document-plugin-mngt in the components list
  3. Click the eye icon and expand KafkaTopicsHealthCheckIndicator → details → configuration → topic → document

​
Encrypting files

Use file encryption to password-protect documents stored in the Documents plugin.

​
How encryption works

  1. The plugin validates that all specified file(s) exist
  2. Validates that files are of supported types
  3. Downloads the file(s) from storage
  4. Creates a password-protected copy:
    • Single file: Creates an encrypted copy with a new file ID
    • Multiple files: Creates a ZIP archive containing all files, then password-protects the ZIP
  5. Returns the file ID of the encrypted document

​
Request message structure

Configure a Send Message Task node with a Kafka Send action to trigger file encryption. Topic: Use the encryption inbound topic (e.g., ai.flowx.plugin.document.trigger.encrypt.file.v1) Request body: 
{
  "fileIds": ["file-id-1", "file-id-2"],
  "password": "your-secure-password"
}
ParameterTypeRequiredDescription
fileIdsArray of stringsYesList of file IDs to encrypt (files must exist in Documents plugin)
passwordStringNoPassword for encryption. If null, creates an unprotected archive for multiple files

​
Response message structure

Configure a Receive Message Task node to receive the encryption result. Topic: Use the encryption outbound topic (e.g., ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1) Response body: 
{
  "status": "success",
  "message": null,
  "fileId": "encrypted-file-id-123"
}
ParameterTypeDescription
statusStringOperation result: success, partial_success, error, or no-op
messageStringAdditional information (populated in case of errors or partial success)
fileIdStringThe file ID of the newly created encrypted file

​
Example: Encrypt a single file

1

Add a Send Message Task node

Configure a Kafka Send action with the encryption topic and the following message body:
{
  "fileIds": ["${uploadedDocument.fileId}"],
  "password": "${encryptionPassword}"
}
2

Add a Receive Message Task node

Configure the node to listen on the encryption results topic to capture the encrypted file ID.
3

Store the encrypted file ID

Use the response fileId for subsequent operations (e.g., sending via email, downloading).

​
Decrypting files

Use file decryption to unlock password-protected documents and extract contents from encrypted archives.

​
How decryption works

  1. The plugin validates that the specified file exists
  2. Validates that the file is of a supported type
  3. Downloads the file from storage
  4. Attempts to open the file:
    • First tries without a password
    • If that fails, uses the provided password
  5. If the file is a ZIP archive, extracts its contents
  6. Filters extracted files by supported types
  7. Uploads the resulting file(s) to storage
  8. Returns the file ID(s) of the decrypted/extracted files

​
Request message structure

Configure a Send Message Task node with a Kafka Send action to trigger file decryption. Topic: Use the decryption inbound topic (e.g., ai.flowx.plugin.document.trigger.decrypt.file.v1) Request body: 
{
  "fileId": "encrypted-file-id-123",
  "password": "your-secure-password"
}
ParameterTypeRequiredDescription
fileIdStringYesThe file ID of the encrypted file to decrypt
passwordStringNoPassword for decryption. If the file is not password-protected, this can be null

​
Response message structure

Configure a Receive Message Task node to receive the decryption result. Topic: Use the decryption outbound topic (e.g., ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1) Response body: 
{
  "status": "success",
  "message": null,
  "fileIds": ["decrypted-file-id-1", "decrypted-file-id-2"]
}
ParameterTypeDescription
statusStringOperation result: success, partial_success, error, or no-op
messageStringAdditional information (populated in case of errors or partial success)
fileIdsArray of stringsList of file IDs for the decrypted/extracted files
When decrypting a ZIP archive, the response contains multiple file IDs—one for each extracted file that matches supported file types.

​
Example: Decrypt a password-protected file

1

Add a Send Message Task node

Configure a Kafka Send action with the decryption topic and the following message body:
{
  "fileId": "${encryptedDocument.fileId}",
  "password": "${userProvidedPassword}"
}
2

Add a Receive Message Task node

Configure the node to listen on the decryption results topic.
3

Process the decrypted files

The response fileIds array contains all successfully decrypted files. Use these IDs for further document processing.

​
Error handling

Both encryption and decryption operations return descriptive error messages when issues occur.

​
Common error scenarios

ScenarioStatusDescription
All files processedsuccessAll files were encrypted/decrypted successfully
Some files failedpartial_successSome files were processed but others failed (e.g., unsupported type in a batch)
File not founderrorThe specified file ID does not exist in the Documents plugin
Unsupported file typeerrorThe file format is not supported for encryption/decryption
Invalid passworderrorThe provided password is incorrect (decryption only)
No files to processno-opEmpty file list provided or all files filtered out

​
Example error response

{
  "status": "error",
  "message": "File with ID 'invalid-id-123' not found",
  "fileId": null
}
Always implement error handling in your process flow to gracefully manage encryption/decryption failures. Check the status field before proceeding with subsequent operations.

​
Security considerations

Password handling

In the current version, passwords are transmitted in clear text. Ensure your Kafka communication is secured with TLS encryption.

File storage

Encrypted files are stored as new documents with unique file IDs. Original files remain unchanged.

Documents plugin overview

Learn about all Documents plugin capabilities

Documents plugin setup

Configure the Documents plugin in your environment

Uploading files

Upload files to the Documents plugin before encryption

Kafka Send action

Configure Kafka Send actions in your process
Last modified on February 27, 2026