Build a File-Driven Integration

TimeUnder 10 minutes

What you'll buildA file integration that adds an onModify handler to track file changes and uses printInfo to log file modification events.

File integrations are ideal for batch uploads, scheduled file processing, and ETL workflows triggered by files appearing in a folder or FTP server.

Prerequisites

A working WSO2 Integrator environment.

WSO2 Cloud setup

Sign up and launch WSO2 Integrator in the browser-based cloud editor.

You'll also need a file at the listener path to watch. Create one if you don't have one:

macOS / Linux

echo "test" > /tmp/testfile.txt

Windows

mkdir C:\tmp 2>nul
echo test > C:\tmp\testfile.txt

Step 1: Create the integration

Note

In the cloud editor, you're already inside a project. Skip to Step 2.

1. Open WSO2 Integrator.
2. Select the Create New Integration card.
3. Set Integration Name to FileTracker.
4. Set Project Name to file-integration.
5. Select Create Integration.

Step 2: Add a file integration artifact

1. Select FileTracker from Project Overview Canvas.
2. In the design view, select + Add Artifact.
3. Select Local Files under File Integration.
4. Set Path to /tmp (macOS/Linux) or C:\tmp (Windows). Select Create.

Step 3: Add onModify event handler

1. In the service designer view, select + Add Handler.
2. Select onModify.

Step 4: Add file tracking logic

1. Select + in the flow diagram.
2. Search for printInfo and select printInfo.
3. Set Msg to File modified and select Save.

Step 5: Run and test

1. Select Run in the toolbar.

2. Run the modify command in your terminal to trigger the handler:

   macOS / Linux

   echo "modify" > /tmp/testfile.txt

   Windows

   echo modify > C:\tmp\testfile.txt

3. Confirm the run terminal shows the log line File modified.

Source code

View the generated Ballerina code

The steps above generate the following complete, runnable Ballerina program:

Windows

Change the listener path from "/tmp" to "C:\\tmp" (backslash escaped) before running the program.

import ballerina/file;
import ballerina/log;

listener file:Listener fileListener = new (path = "/tmp", recursive = false);

service file:Service on fileListener {
    remote function onModify(file:FileEvent event) returns error? {
        do {
            log:printInfo("File modified");
        } on fail error err {
            // handle error
            return error("unhandled error", err);
        }
    }

}

Learn more

• Local files — Full Local Files listener reference (events, recursive watching, file handlers)
• FTP/SFTP — Watch and process files on remote FTP or SFTP servers
• Streaming large files — Process large files without loading them fully into memory
• CSV fault tolerance — Handle errors and partial failures when processing CSV files