Encrypting and decrypting files

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

Format	Extensions
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 Variable	Default Topic Name	Direction	Description
`KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_IN`	`ai.flowx.plugin.document.trigger.encrypt.file.v1`	Inbound	Topic for encryption requests
`KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_IN`	`ai.flowx.plugin.document.trigger.decrypt.file.v1`	Inbound	Topic for decryption requests
`KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_OUT`	`ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`	Outbound	Topic for encryption results
`KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_OUT`	`ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`	Outbound	Topic for decryption results

To find the configured topic names in your environment:

Navigate to FlowX Designer → Platform Status
Locate document-plugin-mngt in the components list
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

The plugin validates that all specified file(s) exist
Validates that files are of supported types
Downloads the file(s) from storage
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
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"
}

Parameter	Type	Required	Description
`fileIds`	Array of strings	Yes	List of file IDs to encrypt (files must exist in Documents plugin)
`password`	String	No	Password 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"
}

Parameter	Type	Description
`status`	String	Operation result: `success`, `partial_success`, `error`, or `no-op`
`message`	String	Additional information (populated in case of errors or partial success)
`fileId`	String	The file ID of the newly created encrypted file

Example: Encrypt a single file

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

Add a Receive Message Task node

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

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

The plugin validates that the specified file exists
Validates that the file is of a supported type
Downloads the file from storage
Attempts to open the file:
- First tries without a password
- If that fails, uses the provided password
If the file is a ZIP archive, extracts its contents
Filters extracted files by supported types
Uploads the resulting file(s) to storage
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"
}

Parameter	Type	Required	Description
`fileId`	String	Yes	The file ID of the encrypted file to decrypt
`password`	String	No	Password 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"]
}

Parameter	Type	Description
`status`	String	Operation result: `success`, `partial_success`, `error`, or `no-op`
`message`	String	Additional information (populated in case of errors or partial success)
`fileIds`	Array of strings	List 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

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

Add a Receive Message Task node

Configure the node to listen on the decryption results topic.

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

Scenario	Status	Description
All files processed	`success`	All files were encrypted/decrypted successfully
Some files failed	`partial_success`	Some files were processed but others failed (e.g., unsupported type in a batch)
File not found	`error`	The specified file ID does not exist in the Documents plugin
Unsupported file type	`error`	The file format is not supported for encryption/decryption
Invalid password	`error`	The provided password is incorrect (decryption only)
No files to process	`no-op`	Empty 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

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Encrypting and decrypting files

Overview

Supported file types

Prerequisites

Kafka topics

Topic configuration

Encrypting files

How encryption works

Request message structure

Response message structure

Example: Encrypt a single file

Decrypting files

How decryption works

Request message structure

Response message structure

Example: Decrypt a password-protected file

Error handling

Common error scenarios

Example error response

Security considerations

Password handling

File storage

Documents plugin overview

Documents plugin setup

Uploading files

Kafka Send action

​Overview

​Supported file types

​Prerequisites

​Kafka topics

​Topic configuration

​Encrypting files

​How encryption works

​Request message structure

​Response message structure

​Example: Encrypt a single file

​Decrypting files

​How decryption works

​Request message structure

​Response message structure

​Example: Decrypt a password-protected file

​Error handling

​Common error scenarios

​Example error response

​Security considerations

Password handling

File storage

​Related documentation

Documents plugin overview

Documents plugin setup

Uploading files

Kafka Send action

Overview

Supported file types

Prerequisites

Kafka topics

Topic configuration

Encrypting files

How encryption works

Request message structure

Response message structure

Example: Encrypt a single file

Decrypting files

How decryption works

Request message structure

Response message structure

Example: Decrypt a password-protected file

Error handling

Common error scenarios

Example error response

Security considerations

Related documentation