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.

Local setup

Install and launch WSO2 Integrator on your machine.

WSO2 Cloud Account

For AI assisted development and WSO2 Cloud deployments.

Also required, 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

If you're using the cloud editor, a project is already open, so you can skip this step and go directly to Step 2: Add a file integration artifact.

1. Open WSO2 Integrator.

2. Click Create in the Create a Project card.

   

3. Set Project Name to file-integration.

4. Set Integration Name to FileTracker.

5. Click Create.

   

Step 2: Add a file integration artifact

1. Select your integration from the project overview canvas.

2. In the design view, click Add Artifact Manually.

   

3. Select Local Files under File Integration.

   

4. Set Path to the folder you want to watch:

   macOS / Linux

   /tmp

   Windows

   C:\tmp

5. Click Create.

   

Step 3: Add onModify event handler

1. In the service designer view, click + Add Handler.

2. Select onModify.

   

3. In the Configure onModify Handler panel, clear both On Success and On Error under File Handling Options, then click Save. Both options arrive ticked and set to Move, which moves each processed file out of the watched directory. Clearing them keeps testfile.txt in /tmp, where the later steps expect it. For details, see Post-processing: moving or deleting files.

Step 4: Add file tracking logic

1. Click + in the flow diagram.

2. Search for printInfo and select printInfo.

   

3. Set Msg to File modified.

4. Click Save.

   

Step 5: Run and test

1. Click 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);
       }
   }


}

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