> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File Storage

> Connect to external file storage (FTP, SFTP, S3, or Azure Blob) as a data source and move files in and out of FlowX from your workflows.

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

> [!NOTE]
>
> 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 self-hosted 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.

> [card] Connect to your storage
>
> FTP, SFTP, S3 / S3-compatible, and Azure Blob Storage, each with its own connection and authorization settings

> [card] Define file operations
>
> Save named List, Download, Upload, Delete, and Move operations scoped to a root path

> [card] Browse and test
>
> Browse files in the configured storage and run any operation live before you use it

> [card] 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](https://docs.flowx.ai/6.x/setup-guides/file-gateway-setup.md).

***

## Creating a File Storage data source

**1. Open Data Sources**

Navigate to **Integration Designer** → **Data Sources** in your project.

**2. Add a new data source**

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

**3. 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](#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](#connection-settings)).

**4. Test the connection**

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

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

***

## Certificates

A File Storage data source that connects over TLS has the same **Certificates** panel as a REST data source, in its **Settings**. **Trust** decides what the server's certificate is checked against (**System CAs**, **Custom CA**, or **None (insecure)**), and **Identity** is the client certificate FlowX presents when the server asks for one (mutual TLS). For every option and field, see [Certificates](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md#certificates).

The panel appears only when the connection uses TLS:

| Protocol | Certificates panel shown when |
| - | - |
| **FTP** | **Encryption** is **FTPS (Explicit)** or **FTPS (Implicit)** |
| **S3 / S3-compatible** | **Endpoint URL** is blank (AWS S3), starts with `https://`, or is a configuration parameter such as `${s3Endpoint}` |
| **Azure Blob Storage** | **Endpoint** is blank, starts with `https://`, or is a configuration parameter |
| **SFTP** | Never. SFTP runs over SSH, not TLS: authenticate with **Private key** under [Authorization](#authorization) |

> [!NOTE]
>
> For File Storage, **Path** points to the filesystem of the `file-gateway` service, not to your local machine. On SaaS deployments, use **Inline**.

An SFTP data source with **Private key** authorization that kept its SSH key in the earlier certificate settings has the key moved to the authorization automatically.

***

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

> [!NOTE]
>
> 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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md#receiving-files-endpoint-response-configuration). | 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](https://docs.flowx.ai/6.x/docs/building-blocks/actions/upload-file-action.md) to a user task | The Document Plugin reply. See [Receiving the reply](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md#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.

> [!NOTE]
>
> 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.

**1. Add a Data Source node**

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

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

**3. 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](https://docs.flowx.ai/6.x/setup-guides/file-gateway-setup.md).

***

## Troubleshooting

> [accordion] 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.

> [accordion] 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.

***

## Related resources

> [card] [File Gateway setup](https://docs.flowx.ai/6.x/setup-guides/file-gateway-setup.md)
>
> Deployment configuration for the file-gateway service

> [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Overview of all data source types and workflow building

> [card] [Oracle Database](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/oracle-database.md)
>
> Connect to externally managed Oracle databases

> [card] [Unmanaged MongoDB](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/unmanaged-mongodb.md)
>
> Connect to externally managed MongoDB instances


## Related topics

- [File Gateway setup](https://docs.flowx.ai/6.x/setup-guides/file-gateway-setup.md)
- [Encrypting and decrypting files](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files.md)
- [AI Platform setup](https://docs.flowx.ai/6.x/setup-guides/ai-platform-setup.md)
- [Deployment changes for v4.6.0](https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x.md)
- [Runtime manager setup](https://docs.flowx.ai/6.x/setup-guides/runtime-manager.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.