File Storage

Overview

File Storage is a data source type that lets you connect FlowX workflows to external file storage your organization manages independently — an FTP/SFTP server, an S3 (or S3-compatible) bucket, or an Azure Blob Storage container. You configure a connection, define named file operations against it, and call those operations from workflows.

Here, external means the storage is managed by your organization rather than by FlowX — it can still run entirely inside your own network. Point the Host at an in-cluster or on-prem FTP/SFTP server, or set the S3 Endpoint URL to a self-hosted MinIO bucket. FlowX provides the connector (file-gateway); you provide the storage.

Connect to your storage

FTP, SFTP, S3 / S3-compatible, and Azure Blob Storage, each with its own connection and authorization settings

Define file operations

Save named List, Download, Upload, Delete, and Move operations scoped to a root path

Browse and test

Browse files in the configured storage and run any operation live before you use it

Reusable in workflows

Reference file operations from a Data Source node alongside other data sources

Prerequisites

An external file storage system reachable from your FlowX deployment: an FTP/SFTP server, an S3 or S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, and similar), or an Azure Blob Storage container.
Credentials for the storage system with the permissions your operations require (read for List/Download, write for Upload/Move, delete for Delete).
The file-gateway service deployed and able to reach both the storage system and the document-plugin service. See File Gateway setup.

Creating a File Storage data source

Open Data Sources

Navigate to Integration Designer → Data Sources in your project.

Add a new data source

Click the + button to open the Add Data Source dialog. In the Files category, select External File Storage.

Configure the connection on the Settings tab

New File Storage data sources open on the Settings tab, which has three sections:

Protocol — select the storage type: FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage.
Authorization — choose an authorization type and supply credentials (see Authorization).
General Settings — set the Root Path of the storage (all operations are scoped under this prefix) and the protocol-specific connection fields (see Connection settings).

Test the connection

Click Test connection in the Authorization section to verify the credentials and connectivity. A successful test reports Established connection.

Save

Click Save to create the data source. Until a valid connection is saved, the Files tab shows File storage is not configured and the Settings tab shows a Settings are not configured warning.

Connection settings

The connection fields depend on the protocol you select.

FTP

Field	Description	Default
Host	FTP server hostname or IP (required)	—
Port	FTP port (required)	`21`
Mode	Connection mode: Active or Passive	`Passive`
Encryption	None, FTPS (Explicit), or FTPS (Implicit)	`None`

SFTP

Field	Description	Default
Host	SFTP server hostname or IP (required)	—
Port	SFTP port (required)	`22`
Strict host-key checking	Accept new or Require fingerprint	`Accept new`
Known-hosts fingerprint	Optional. The expected host-key fingerprint when requiring verification	—

S3 / S3-compatible

Field	Description
Endpoint URL	Optional. Leave blank for AWS S3. Set this only for S3-compatible stores (MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, Localstack, and similar).
Region	Required, including for non-AWS stores such as MinIO.
Bucket	Required. Fixed for the lifetime of this data source.
Path-style access	Off by default (virtual-host style, the AWS default). Turn ON for path-style addressing, required by MinIO, Localstack, and most self-hosted stores. Rule of thumb: AWS S3 → off; MinIO / self-hosted → on.

Azure Blob Storage

Field	Description
Storage account name	Required. The Azure storage account.
Container name	Required. The blob container.
Endpoint	Optional. A custom endpoint, when not using the default Azure endpoint.

Authorization

The available authorization types depend on the protocol:

Protocol	Authorization types
FTP	No authorization, or Basic (username / password)
SFTP	Basic (username / password), or Private key (username + private key)
S3	Access key (access key ID + secret access key)
Azure Blob Storage	Access key (storage account name + account key), or Service account (tenant ID + client ID + client secret)

For Azure with Access key, the credential fields are labeled Storage Account Name and Account Key.

File operations

Each File Storage data source holds a list of named operations, managed on the Operations tab. Click to add an operation, choose its Operation type, and give it a Name and optional Description. Each operation opens a details page where you configure its parameters, and a test modal runs it live against the storage.

Operation	What it does
List	Lists file metadata inside the root path. Use File Path to target a subfolder and File pattern to filter results.
Download	Copies a file from external storage into Document Plugin internal storage for further processing.
Upload	Copies a file from Document Plugin internal storage to external storage.
Delete	Removes files from the external storage.
Move	Moves a file within the external storage. Move can also rename the file.

Operation parameters

Operation	Parameters
List	File Path (optional subfolder), File pattern (optional wildcard, e.g. `.csv`, `report-.xml`, `2026/.pdf`), Recursive* toggle
Download	Source File Path (required), Document folder (required), Document type (optional), File name override (optional)
Upload	Destination file path (required), Document plugin path (required)
Delete	File Path (required)
Move	Source File Path (required), Destination path (required)

Download and Upload exchange files with the Document Plugin internal storage rather than the workflow directly — Download brings an external file into FlowX, Upload sends a stored document out.

What do the Download parameters mean?

A Download operation reads one file from the external storage and saves a copy in Document Plugin internal storage.

Parameter	Description
Source File Path	Path of the file in the external storage, relative to the data source root path. The root path is added in front of it.
Document folder	Name of the Document Plugin folder the copy is saved in.
Document type	Optional document type assigned to the saved copy in Document Plugin.
File name override	Optional file name for the saved copy. When empty, the copy keeps the source file name.

The operation output includes a documentPluginMetadata object with these keys:

Key	Description
`filePath`	Storage path of the saved copy. Map it to the Document plugin path of an Upload operation, or to any step that reads the file from Document Plugin.
`downloadPath`	Download path of the saved copy in Document Plugin.
`fileEntryUuid`	ID of the Document Plugin file entry.
`fileName`	Name of the source file in the external storage.
`byteCount`	Size of the source file in bytes.

How do I get a file into Document Plugin storage before an Upload?

An Upload operation can only send a file that is already in Document Plugin internal storage. Its Document plugin path parameter takes the file’s storage path, the filePath value returned when the file was saved. Each of these saves a file to Document Plugin storage and returns a filePath:

Source of the file	How to save it	Where to read `filePath`
An external API response, including Base64 content in JSON	Turn on Save Files on the REST endpoint and set File Destination to Document Plugin. See Receiving files.	The workflow node output
Another external file storage	Run a File Storage Download operation	The `filePath` key inside `documentPluginMetadata` in the operation output
A file a user uploads in a process	Add an Upload File action to a user task	The Document Plugin reply. See Receiving the reply.

Map that filePath to Document plugin path, and set Destination file path to the path in the external storage, relative to the data source root path.

Pass the storage path, not a preview or download URL. If a business rule replaced filePath with a preview URL, keep the original storage path in a separate key for the Upload.

Browsing files

The Files tab is a file browser for the configured storage. Once a valid connection is saved, you can navigate the storage, copy file paths, and preview files. The browser is available only after the connection is configured on the Settings tab.

Using in workflows

File operations are called from a Data Source node in workflows.

Add a Data Source node

On the workflow canvas, add a Data Source node and select your File Storage data source.

Select the operation

Pick one of the operations defined on that data source. The picker lists only the operations saved on the selected data source.

Map parameters

Map workflow inputs to the operation’s parameters, and map the operation result (file list, document reference, or status) to a workflow variable.

Deployment

File Storage operations run in the file-gateway service.

file-gateway is MongoDB-backed and connects to the document-plugin service to exchange files; Download and Upload operations move files between external storage and document-plugin internal storage.
It does not require Redis.
It authenticates using the flowx-file-gateway-sa service account.
The default maximum file size for operations is 1 GiB.

For deployment configuration, see File Gateway setup.

Troubleshooting

Error: There was an error while calling file-gateway service

This message means the file-gateway service returned an error response that Integration Designer doesn’t pass through. The actual status and response body are in the integration-designer logs, on a line that starts with File gateway execute operation failed with status. Check that line first.For a Download operation, a common cause is Document Plugin rejecting the copy of the file, so also check that the document-plugin service is running and that file-gateway can reach it.Problems with the external storage itself don’t produce this message. A missing file, a file over the 1 GiB size limit, credentials the storage rejects, or an unreachable storage server make the operation fail with the storage’s own error message instead.

Error: Cannot invoke FileStorageConfig.getProtocol() because cfg is null

The File Storage data source has no saved connection settings, so the operation has no storage to connect to. Open the data source, fill in the Settings tab, click Test connection, and save. Until a valid connection is saved, the Settings tab shows a Settings are not configured warning.

File Gateway setup

Deployment configuration for the file-gateway service

Integration Designer

Overview of all data source types and workflow building

Oracle Database

Connect to externally managed Oracle databases

Unmanaged MongoDB

Connect to externally managed MongoDB instances

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Overview

Connect to your storage

Define file operations

Browse and test

Reusable in workflows

Prerequisites

Creating a File Storage data source

Connection settings

FTP

SFTP

S3 / S3-compatible

Azure Blob Storage

Authorization

File operations

Operation parameters

What do the Download parameters mean?

How do I get a file into Document Plugin storage before an Upload?

Browsing files

Using in workflows

Deployment

Troubleshooting

File Gateway setup

Integration Designer

Oracle Database

Unmanaged MongoDB

​Overview

Connect to your storage

Define file operations

Browse and test

Reusable in workflows

​Prerequisites

​Creating a File Storage data source

​Connection settings

​FTP

​SFTP

​S3 / S3-compatible

​Azure Blob Storage

​Authorization

​File operations

​Operation parameters

​What do the Download parameters mean?

​How do I get a file into Document Plugin storage before an Upload?

​Browsing files

​Using in workflows

​Deployment

​Troubleshooting

​Related resources

File Gateway setup

Integration Designer

Oracle Database

Unmanaged MongoDB

Overview

Prerequisites

Creating a File Storage data source

Connection settings

FTP

SFTP

S3 / S3-compatible

Azure Blob Storage

Authorization

File operations

Operation parameters

What do the Download parameters mean?

How do I get a file into Document Plugin storage before an Upload?

Browsing files

Using in workflows

Deployment

Troubleshooting

Related resources