Skip to content

Update the ftp docs #504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KavinduZoysa wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update the ftp docs #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
07f263a
Update the ftp docs
KavinduZoysa May 22, 2026
958cde3
Change CSV Fault Tolerance
KavinduZoysa May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions en/docs/develop/integration-artifacts/file/csv-fault-tolerance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';

# CSV Fault Tolerance

Real-world CSV files rarely arrive perfectly clean. A single bad row (a stray comma, a wrong data type, a trailing blank) would normally fail the whole file. With **CSV fault tolerance** enabled, the listener treats malformed rows as a per-row issue instead of a per-file one. It skips rows that don't fit your schema and hands the rest to the handler as if nothing happened.
Real-world CSV files rarely arrive perfectly clean. A single bad row (a stray comma, a wrong data type, a trailing blank) would normally fail the whole file. With **Csv Fail Safe** enabled, the listener treats malformed rows as a per-row issue instead of a per-file one. It skips rows that don't fit your schema and hands the rest to the handler as if nothing happened.

@anupama-pathirage anupama-pathirage May 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be CSV Fail Safe?


## What the handler sees

Expand All @@ -23,10 +23,7 @@ Fault tolerance only skips rows that fail **typed binding**. If your handler is
On the **Add File Handler** form, click **+ Define Row Schema** and describe each column as a field on a Ballerina record. This flips the handler parameter to a typed array (for example `Order[]`), and rows that don't match trigger binding errors that fault tolerance can skip. See the [row-schema step in Streaming large files](streaming-large-files.md#enabling-streaming) for a walkthrough.
:::

Fault tolerance combines cleanly with:

- **Streaming** — works with [streamed CSV](streaming-large-files.md). A bad row no longer terminates the stream; processing continues through the rest of the file.
- **Move / Delete post-processing** — because the handler completes successfully, the file follows the **After Success** action as it would for a clean run.
Fault tolerance works with **Move / Delete post-processing**, because the handler completes successfully, the file follows the **After Success** action just as it would for a clean run.

## Configuration

Expand Down
49 changes: 24 additions & 25 deletions en/docs/develop/integration-artifacts/file/ftp-sftp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,32 +28,31 @@ Use this flow for plain (unencrypted) FTP. Default port: `21`. Supports anonymou

![Artifacts panel showing FTP / SFTP under File Integration](/img/develop/integration-artifacts/file/ftp-sftp/step-2.png)

3. In the **Create FTP Integration** form, keep **Protocol** set to **ftp**.

![Create FTP Integration form, FTP protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-ftp.png)

4. Fill in the **Listener Configuration**:
3. In the **Create FTP Integration** form, fill in the **Listener Configuration**:

| Field | Description |
|---|---|
| **Listener Name** | Identifier for this listener (e.g., `ftpListener`). |
| **Protocol** | Types of protocol. Select `ftp`. |
Comment thread
KavinduZoysa marked this conversation as resolved.
| **Host** | Hostname or IP address of the remote server (e.g., `ftp.example.com`). |
| **Port Number** | Port to connect on. Set to `21` for standard FTP. |

5. Choose an **authentication method**:
![Create FTP Integration form, FTP protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-ftp.png)

4. Choose an **authentication method**:

| Option | Fields revealed | Use when |
|---|---|---|
| **No Authentication** | — | The server accepts anonymous logins or a username alone without a password. |
| **Basic Authentication** | **Username**, **Password** | The server requires a username and password. |

6. Enter the **Monitoring Path** — the directory on the remote server to poll for new files (e.g., `/uploads`). Defaults to `/`.
5. Enter the **Monitoring Path** — the directory on the remote server to poll for new files (e.g., `/uploads`). Defaults to `/`.

7. Click **Create**. WSO2 Integrator opens the service in the **Service Designer** with the listener pill attached.
6. Click **Create**. WSO2 Integrator opens the service in the **Service Designer** with the listener pill attached.

![Service Designer showing the FTP service canvas](/img/develop/integration-artifacts/file/ftp-sftp/step-service-designer.png)

8. Click [**+ Add File Handler**](#adding-a-file-handler) to define how incoming files are processed.
7. Click [**+ Add File Handler**](#adding-a-file-handler) to define how incoming files are processed.

</TabItem>
<TabItem value="code" label="Ballerina Code">
Expand Down Expand Up @@ -120,26 +119,26 @@ part of the configuration.
<TabItem value="ui" label="Visual Designer" default>

1. Click **+ Add Artifact** → **FTP / SFTP** under **File Integration**.
2. In the **Create FTP Integration** form, select **Protocol** → **ftps**.

![Create FTP Integration form, FTPS protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-ftps.png)

3. Fill in the **Listener Configuration**:
2. In the **Create FTP Integration** form, fill in the **Listener Configuration**:

| Field | Description |
|---|---|
| **Listener Name** | Identifier for this listener (e.g., `ftpsListener`). |
| **Protocol** | Types of protocol. Select `ftps`. |
| **Host** | Hostname or IP address of the remote server (e.g., `ftps.example.com`). |
| **Port Number** | Port to connect on. Set to `21` for explicit FTPS or `990` for implicit FTPS. |

4. Choose an **authentication method**:
![Create FTP Integration form, FTPS protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-ftps.png)

3. Choose an **authentication method**:

| Option | Fields revealed | Use when |
|---|---|---|
| **No Authentication** | — | The server accepts anonymous TLS connections. |
| **Basic Authentication** | **Username**, **Password** | The server requires credentials over the encrypted channel. Typical for FTPS. |

5. Expand **Advanced Configurations**. The **Secure Socket** field is
4. Expand **Advanced Configurations**. The **Secure Socket** field is
required for FTPS. Click **Record** and supply the SSL/TLS
configuration — at minimum a truststore or certificate path so the
client can verify the server:
Expand All @@ -153,9 +152,9 @@ part of the configuration.
See [SSL/TLS configuration](https://central.ballerina.io/ballerina/ftp/latest#SecureSocket) for the full
field set, including mutual TLS and protocol-version pinning.

6. Enter the **Monitoring Path** and click **Create**.
5. Enter the **Monitoring Path** and click **Create**.

7. Click [**+ Add File Handler**](#adding-a-file-handler) in the Service Designer to define how incoming files are processed.
6. Click [**+ Add File Handler**](#adding-a-file-handler) in the Service Designer to define how incoming files are processed.

</TabItem>
<TabItem value="code" label="Ballerina Code">
Expand Down Expand Up @@ -210,21 +209,21 @@ Use this flow for SFTP (FTP over SSH). Default port: `22`. The form collects the
<TabItem value="ui" label="Visual Designer" default>

1. Click **+ Add Artifact** → **FTP / SFTP** under **File Integration**.
2. In the **Create FTP Integration** form, select **Protocol** → **sftp**.

![Create FTP Integration form, SFTP protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-sftp.png)

3. Fill in the **Listener Configuration**:
2. In the **Create FTP Integration** form, fill in the **Listener Configuration**:

| Field | Description |
|---|---|
| **Listener Name** | Identifier for this listener (e.g., `sftpListener`). |
| **Protocol** | Types of protocol. Select `sftp`. |
| **Host** | Hostname or IP address of the remote server (e.g., `sftp.example.com`). |
| **Port Number** | Port to connect on. Set to `22` for SFTP. |

4. Choose **Certificate-Based Authentication** under **authentication method**. This reveals the **Private Key** and **Username** fields.
![Create FTP Integration form, SFTP protocol](/img/develop/integration-artifacts/file/ftp-sftp/step-creation-form-sftp.png)

3. Choose **Certificate-Based Authentication** under **authentication method**. This reveals the **Private Key** and **Username** fields.

5. Enter the **Private Key** record. Click **Record** on the field and supply:
4. Enter the **Private Key** record. Click **Record** on the field and supply:

```ballerina
{path: "/path/to/private_key"}
Expand All @@ -237,9 +236,9 @@ Use this flow for SFTP (FTP over SSH). Default port: `22`. The form collects the
{path: "/path/to/private_key", password: "my-passphrase"}
```

6. Enter the **Username** that matches the configured private key and the **Monitoring Path**.
5. Enter the **Username** that matches the configured private key and the **Monitoring Path**.

7. Click **Create**. Then click [**+ Add File Handler**](#adding-a-file-handler) in the Service Designer.
6. Click **Create**. Then click [**+ Add File Handler**](#adding-a-file-handler) in the Service Designer.

</TabItem>
<TabItem value="code" label="Ballerina Code">
Expand Down
Loading