Build a File-Driven Integration

Time: Under 10 minutes | What you'll build: A 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

• WSO2 Integrator installed

• 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

Visual Designer

Step 1: Create the project

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.

Ballerina Code

The following complete, runnable Ballerina program produces the same integration shown in the visual designer steps.

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);
        }
    }

}

Save this as main.bal, then run bal run from the project directory. With the test file already in place (see Prerequisites), run the modify command in a separate terminal to trigger the handler:

macOS / Linux

echo "modify" > /tmp/testfile.txt

Windows

echo modify > C:\tmp\testfile.txt

Confirm the run terminal shows the log line File modified.

What's next

• 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