Local Files

Local file services monitor a directory on the local file system and trigger event handlers when files are created, modified, or deleted. Use them for on-premises batch processing, development workflows, and integrations that consume files dropped into a watched directory.

Creating a local file service

Visual Designer

1. Click + Add Artifact in the canvas or click + next to Entry Points in the sidebar.

2. In the Artifacts panel, select Local Files under File Integration.

   

3. In the creation form, fill in the following fields:

   

   Field	Description	Default
   Path	Directory path to monitor for file events (e.g., /data/incoming).	Required
   Recursive	When set to True, monitors all subdirectories under the specified path.	False

   Expand Advanced Configurations to set the listener name.

   Field	Description	Default
   Listener Name	Identifier for the listener created with this service.	fileListener

4. Click Create.

5. WSO2 Integrator opens the service in the Service Designer. The canvas shows the attached listener pill and the Event Handlers section.

   

6. Click + Add Handler to define how file events are processed.

Ballerina Code

import ballerina/file;
import ballerina/log;

configurable string path = "/data/incoming";
configurable boolean recursive = false;

listener file:Listener fileListener = check new ({
    path: path,
    recursive: recursive
});

service on fileListener {

    remote function onCreate(file:FileEvent event) returns error? {
        log:printInfo("File created", path = event.name);
    }

    remote function onModify(file:FileEvent event) returns error? {
        log:printInfo("File modified", path = event.name);
    }

    remote function onDelete(file:FileEvent event) returns error? {
        log:printInfo("File deleted", path = event.name);
    }
}

Service and listener configuration

Visual Designer

In the Service Designer, click the Configure icon in the header to open the Local Files Configuration panel.

Select Local Files in the left panel to view service-level settings, or select fileListener under Attached Listeners to configure the listener.

Configuration for fileListener

Field	Description	Default
Name	Identifier for the listener.	fileListener
Path	Directory path which the listener monitors.	Required
Recursive	When enabled, recursively monitors all subdirectories in the given directory path.	False

Click + Attach Listener to attach an additional listener to the same service.

Click Save Changes to apply updates.

Ballerina Code

The listener configuration is set when constructing file:Listener:

listener file:Listener fileListener = check new ({
    path: "/data/incoming",
    recursive: false
});

file:ListenerConfig fields:

Field	Type	Default	Description
path	string	Required	Directory path to monitor
recursive	boolean	false	Monitor all subdirectories under the path

File handlers

A file handler is a remote function that WSO2 Integrator calls each time a matching file system event occurs in the monitored directory.

Adding a file handler

Visual Designer

In the Service Designer, click + Add Handler. A Select Handler to Add panel opens on the right listing the available event types. Click the event type to add it directly. No further configuration is required.

Handler	Triggered when
onCreate	A new file is created in the monitored directory
onDelete	A file is deleted from the monitored directory
onModify	An existing file in the monitored directory is modified

Ballerina Code

Add the handler as a remote function inside the service. Each handler receives a file:FileEvent parameter containing details about the event.

onCreate handler:

service on fileListener {

    remote function onCreate(file:FileEvent event) returns error? {
        string filePath = event.name;
        log:printInfo("New file detected", path = filePath);
        check processFile(filePath);
    }
}

onModify handler:

service on fileListener {

    remote function onModify(file:FileEvent event) returns error? {
        log:printInfo("File modified", path = event.name);
    }
}

onDelete handler:

service on fileListener {

    remote function onDelete(file:FileEvent event) returns error? {
        log:printInfo("File deleted", path = event.name);
    }
}

FileEvent

Each handler receives a file:FileEvent parameter with details about the file system event.

Field	Type	Description
name	string	Path of the file or directory that changed (absolute when the listener was configured with an absolute path)
operation	string	One of "create", "modify", "delete" (lowercase)

Reading file content

Use the ballerina/io module to read the content of the file that triggered a handler. The path of the file is available as event.name on the file:FileEvent parameter.

Visual Designer

In the Service Designer, open the handler and build the flow with two nodes: a Call Function node that reads the file content and a Log node that prints it.

1. Click + on the handler canvas to add a node, pick Call Function, and select fileReadString under io functions.

2. Set event.name as an Expression in the Path field, content as the Result, and string as the Result Type. Save the node.

3. Click + after the Call Function node, pick Log → Log Info, switch the Msg field to Expression mode, and enter content. Save the node.

Ballerina Code

import ballerina/file;
import ballerina/io;
import ballerina/log;

service on fileListener {

    remote function onCreate(file:FileEvent event) returns error? {
        string content = check io:fileReadString(event.name);
        log:printInfo("File received", path = event.name, size = content.length());
    }
}

io read functions:

Function	Description
io:fileReadString(path)	Read the file as a single UTF-8 string
io:fileReadBytes(path)	Read the file as a byte array
io:fileReadLines(path)	Read the file as a string[], one entry per line
io:fileReadJson(path)	Read and parse the file as a json value
io:fileReadXml(path)	Read and parse the file as an xml value
io:fileReadCsv(path)	Read and parse CSV content as string[][] or a record array

Writing output files

Use the ballerina/io module to write results to the local file system from within a handler.

Visual Designer

Use a Call Function node to invoke an io write function, then add a Log node to confirm the write:

1. Click + on the handler canvas to add a node, pick Call Function, and select fileWriteString under io functions.

2. Set the Path to /data/outgoing/report.txt and the Content to "Processing complete.". Save the node.

3. Click + after the Call Function node, pick Log → Log Info, and enter a confirmation message such as "Output written". Save the node.

Ballerina Code

import ballerina/file;
import ballerina/io;
import ballerina/log;

service on fileListener {

    remote function onCreate(file:FileEvent event) returns error? {
        check io:fileWriteString("/data/outgoing/report.txt", "Processing complete.");
        log:printInfo("Output written", trigger = event.name);
    }
}

io write functions:

Function	Description
io:fileWriteString(path, content)	Write a string to a file, overwriting any existing content
io:fileWriteString(path, content, option)	Write a string with io:APPEND or io:OVERWRITE option
io:fileWriteCsv(path, content)	Serialize a record[] or string[][] and write it as CSV
io:fileWriteBytes(path, content)	Write a byte array to a file
io:fileWriteLines(path, content)	Write a string[] as lines to a file

What's next

• FTP / SFTP — monitor a remote file server instead of a local directory
• Connections — reuse connection credentials across services
• Data Mapper — transform incoming file payloads between formats