File I/O

The file I/O functions read data from multiple file formats (CSV, Excel, PDF, XML, Word, and more), write data to files, and manage files and folders on a file system. All functions in this class are static and execute without an instance configuration.

Where functions execute

The file system these functions access depends on their execution environment:

1. Platform: When executed directly on the platform, functions access the file system of the platform installation itself, the same content visible in the File Explorer. The root path is /shared, meaning a file in the uploads folder uses the path /shared/uploads/test.csv.

2. Local OS: To work with files on your premises, compile, download, and install an Agent containing this class. Functions executed via the Agent access the file system where the Agent runs, using standard local paths like C:\Users\YourUserName\Documents\test.csv.

Pitfall on Windows

When referencing Windows paths, wrap the YAML input in quotes. Without quotes, C:\Users parses as an object containing a C key and a \Users value. Define paths as 'C:\Users'.

Reading files

read

Reads a file and automatically parses its content based on the file extension. This function serves as a convenience wrapper that calls the matching specific function (such as readCsv or readXlsx). Supported extensions include csv, xlsx, docx, pptx, html, htm, md, txt, xsl, pdf, and xml.

Parameters

Input	Description	Type
filename	The full path to the file.	string
options	Options specific to the detected file type. See the respective read function.	object

Example

# filename
/path/to/my-data.xlsx

Output

Returns the parsed content of the file (for example, executing this on an .xlsx path internally calls readXlsx and returns the parsed JSON content). Throws an error for unsupported file types.

exists

Checks whether a file exists at the specified path.

Parameters

Input	Description	Type
filename	The path of the file to check.	string

Output

Returns true if the file exists, or false if it does not.

Working with buffers

readFileToBuffer

Reads any file and returns its entire content as a base64 encoded string.

Parameters

Input	Description	Type
filePath	The path of the file to read.	string

Output

Returns the file content as a base64 encoded string.

writeBufferToFile

Writes a base64 encoded string to a new file.

Parameters

Input	Description	Type
filePath	The full path where the file is saved, including the filename and extension.	string
buffer	The content of the file as a base64 encoded string.	string

Output

Returns true on a successful write.

writeBuffersToDirectory

Writes one or more buffer-file objects to a directory. The function creates the directory (including parent folders) if it does not exist.

Parameters

Input	Description	Type
dirname	The path to the directory where the files are written.	string
bufferData	A single object or an array of objects, each containing at least the name and base64 properties. See the file object structure.	object or array

Output

Returns true when all files are successfully written. Throws an error listing every file that failed.

This function integrates directly with the photo or upload widget when configured to use Buffer as the storage type.

Local file sharing

Using these functions from an Agent establishes a file share between your App and your local OS. For example, you can store pictures taken with the photo widget directly on your own file server.

Managing files and folders

moveFile

Moves or renames a file.

Parameters

Input	Description	Type
oldPath	The original path of the file.	string
newPath	The new path for the file.	string

Output

Returns nothing on success. Throws an error on failure.

copyFile

Copies a file from a source path to a destination path.

Parameters

Input	Description	Type
src	The path of the file to copy.	string
dest	The path where the copy is created.	string

Output

Returns nothing on success. Throws an error on failure.

deleteFile

Deletes a file.

Irreversible action

This permanently deletes the file from the file system. You cannot undo this action.

Parameters

Input	Description	Type
filename	The path of the file to delete.	string

Output

Returns nothing on success. Throws an error if the file does not exist.

createFolder

Creates a new folder at the specified path, including any missing parent folders.

Parameters

Input	Description	Type
path	The path where the new folder is created.	string

Output

Returns nothing on success. Throws an error on failure.

deleteFolder

Deletes a folder and all of its contents recursively. The function does not throw an error if the folder is missing.

Irreversible action

This permanently deletes the folder and all containing files and subfolders. You cannot undo this action.

Parameters

Input	Description	Type
dir	The path of the folder to delete.	string

Output

Returns nothing.

browse

Recursively scans a folder and returns a structure representing its files and subfolders.

Parameters

Input	Description	Type
filename	The path of the folder to browse.	string

Output

Returns a nested JSON object detailing the folder's contents, containing the properties name, path, size, modDate, isDir, and a children array for directories:

{
  "id": "12345",
  "path": "/path/to/project",
  "name": "project",
  "modDate": "2025-08-22T12:02:00.000Z",
  "size": 4096,
  "isDir": true,
  "childrenCount": 2,
  "children": [
    {
      "id": "12346",
      "path": "/path/to/project/report.docx",
      "name": "report.docx",
      "modDate": "2025-08-21T10:30:00.000Z",
      "size": 15360,
      "isDir": false,
      "isFile": true,
      "isSymlink": false
    },
    {
      "id": "12347",
      "path": "/path/to/project/images",
      "name": "images",
      "modDate": "2025-08-22T11:00:00.000Z",
      "size": 4096,
      "isDir": true,
      "childrenCount": 1,
      "children": []
    }
  ]
}

CSV files

readCsv

Reads CSV data and converts it into an array of JSON objects. The function automatically detects whether the input is a file path, a raw CSV string, or a base64 encoded string.

Parameters

Input	Key	Description	Type
fileInfo		The path to the .csv file, a raw CSV string, or a base64 encoded string of the file content.	string
options	delimiter	The column delimiter. Provide a string (such as ;), auto for automatic detection, or an array of candidates (such as [',', ';', '|']). Default ,.	string or array
	checkType	If true, automatically converts numbers and booleans from strings to their native types. Default false.	boolean
	noheader	Indicates that the CSV data has no header row. Default false.	boolean
	headers	An array of strings used as column headers, such as when the CSV has no header row.	array
	output	The output format: json, csv (array of arrays), or line (each line as a string). Default json.	string
	trim	Trims whitespace from headers and values. Default true.	boolean
	ignoreEmpty	If true, ignores empty lines. Default false.	boolean
	quote	The character used for quoting columns. Default ".	string
	includeColumns	A regular expression specifying which columns to include.	string
	ignoreColumns	A regular expression specifying which columns to ignore.	string

All other csvtojson options pass through directly.

Examples

Example 1: Reading a semicolon-delimited CSV with type conversion

# fileInfo
/path/to/data.csv
# options
delimiter: ;
checkType: true

Example 2: Reading a CSV string with no header row

# fileInfo
'1,ProductA,19.99\n2,ProductB,25.50'
# options
noheader: true
headers: ['id', 'name', 'price']
checkType: true

Output

Returns an array of JSON objects (or the format specified by output). Throws an error if the input is neither a valid path, base64 string, nor a valid CSV string.

writeCsv

Converts an array of JSON objects into a CSV string and writes it to a file.

Parameters

Input	Key	Description	Type
json		An array of JSON objects.	array
filename		The path where the .csv file is saved.	string
options	keys	An array of strings specifying which properties to include as columns, in order.	array
	delimiter	The field separator. Default ,.	string
	prependHeader	If false, the connector omits the header row. Default true.	boolean
	eol	The end-of-line character. Default \n.	string
	sortHeader	If true, sorts the headers alphabetically. Default false.	boolean
	emptyFieldValue	The value used for empty, null, or undefined fields. Default ''.	string
	excelBOM	If true, adds a BOM character for correct UTF-8 display in Excel.	boolean

Example

# json
[
  { "id": 1, "name": "Product A", "price": 19.99, "stock": 100 },
  { "id": 2, "name": "Product B", "price": 25.50, "stock": 250 }
]
# filename
/path/to/output.csv
# options
keys: ['id', 'name', 'price']
prependHeader: false

Output

Returns true on a successful write.

Excel files

readXlsx

Reads an Excel file and converts its content into JSON. If the file contains only one sheet (or only one is queried), the result is an array of row objects. For files with multiple sheets, the result is an object containing one key per sheet name.

Parameters

Input	Key	Description	Type
fileInput		The path to the .xlsx file or a base64 encoded string of the file content.	string
options	headerRows	The number of rows from the top treated as a header and excluded from the data.	integer
	sheets	An array of sheet names to include. Default includes all existing sheets.	array
	columnToKey	An object whose keys identify xlsx columns and whose values define the corresponding property name in the result.	object
	range	A cell range to read (such as 'A2:C10').	string

Configuration tips

• Use columnToKey: { '*': '{{columnHeader}}' } to automatically extract names from the header row.

• Use columnToKey: { A: '{{A1}}', B: '{{B1}}' } to use names defined anywhere in the sheet.

• Configure options per sheet by passing objects inside the sheets array:

sheets:
  - name: sheet1
    range: 'A2:B2'
  - name: sheet2
    range: 'A3:B4'

Examples

Example 1: Reading a specific range with named columns

# fileInput
/path/to/report.xlsx
# options
range: 'B2:D10'
columnToKey: {
  B: product,
  C: quantity,
  D: price
}

Output:

[
  { "product": "Widget", "quantity": 10, "price": 19.99 }
]

Example 2: Reading a table with a single header row and mapped columns

# fileInput
/path/to/assets.xlsx
# options
headerRows: 1
columnToKey: {
  B: barcode,
  C: name,
  D: acquired,
  H: keeper,
  K: inventoryNo,
  M: serialNo,
  N: costCtr
}

Output:

[
  { "barcode": 187552, "name": "HP Laptop", "acquired": "2025-06-01T00:00:00.000Z" }
]

Example 3: Combining Excel reading with a file upload

Uploads an .xlsx file, saves it as a base64 buffer, and feeds it to the readXlsx function.

readXlsxCells

Reads the values of one or more specific cells from an Excel sheet.

Parameters

Input	Description	Type
fileInput	The path to the .xlsx file or a base64 encoded string of the file content.	string
cellAddresses	A single cell address (such as 'B5') or an array of addresses (such as ['A1', 'C5']).	string or array
sheetIdentifier	The name (such as 'Sales') or zero-based index (0) of the sheet. Default targets the first sheet.	string or integer

Example

# fileInput
/path/to/report.xlsx
# cellAddresses
['B2', 'D5']
# sheetIdentifier
'Summary'

Output

Returns the cell value, or an array of values when you provide multiple addresses (such as ['Total Revenue', 15000]). Empty or non-existent cells return no value. Throws an error if the file or sheet is not found.

writeXlsx

Writes an array of JSON objects to a new Excel file.

Parameters

Input	Key	Description	Type
data		The array of JSON objects to write. This array must not be empty.	array
filePath		The path where the new .xlsx file is saved.	string
options	sheetName	The name for the worksheet. Default Sheet1.	string
	headers	An array of strings used as the header row. Default uses the keys of the first data object.	array

Example

# data
[
  { "product": "Widget", "quantity": 10, "price": 19.99 },
  { "product": "Gadget", "quantity": 5, "price": 49.95 }
]
# filePath
/path/to/new_report.xlsx
# options
sheetName: 'Inventory'

Output

Returns nothing on success. Throws an error on empty data, an invalid path, or a failed write.

Other document formats

readPdf

Reads a PDF file and extracts its text content and metadata.

Parameters

Input	Description	Type
filename	The path to the .pdf file.	string

Output

Returns an object containing text (the full text content), numpages, numrender, and info (metadata):

{
  "numpages": 2,
  "numrender": 2,
  "info": {
    "PDFFormatVersion": "1.7",
    "Title": "My Annual Report",
    "Author": "John Doe",
    "Creator": "Microsoft® Word for Office 365",
    "CreationDate": "D:20250822120200Z"
  },
  "metadata": null,
  "text": "\n\nPage 1 Content\n\nThis is the first paragraph of the annual report...\n\n",
  "version": "1.10.100"
}

readXml

Reads an XML file and converts it into a JSON object.

Parameters

Input	Key	Description	Type
filename		The path to the .xml file.	string
options	attrkey	The key used for XML attributes. Default _attr.	string
	explicitArray	If false, single-element arrays convert to a single object. Default true.	boolean
	mergeAttrs	If true, merges attributes into their parent object instead of a separate attrkey object.	boolean
	explicitRoot	If false, the root XML element is excluded from the result.	boolean

All other xml2js parser options pass through directly.

Output

Returns a JSON representation of the XML content.

readDocx, readPptx, readHtml, readTxt, readMd

These functions read their respective file types and extract the plain text content.

Parameters

Input	Key	Description	Type
filename		The path to the file.	string
options	preserveLineBreaks	Maintains line breaks from the original document. Default true.	boolean

All other textract options pass through directly.

Output

Returns the plain text content of the file as a string.