Spreadsheet File

Read from and write to spreadsheet files (CSV, XLS, XLSX, ODS, HTML, RTF)

Overview

The Spreadsheet File tool converts between spreadsheet binary files and JSON data. It has two operations: (1) fromFile reads a binary spreadsheet and outputs one JSON item per row (1-to-many); (2) toFile aggregates all input JSON items into a single spreadsheet binary file (many-to-1). Supports CSV, XLS, XLSX, ODS, HTML, and RTF formats. Uses the xlsx (SheetJS) library for spreadsheet formats and csv-parse for CSV files. No external API calls or credentials required.

Category: Core Nodes
Tool Name: spreadsheet_file
Version: 1

Appearance: Icon: lucide-Sheet | Color: #2244FF

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Operations

Operation	Value	Description
Read From File	fromFile	Reads data from a spreadsheet file
Write to File	toFile	Writes the workflow data to a spreadsheet file

Parameters

Read From File (fromFile)

Parameter	Type	Required	Default	Description
Input Binary Field (binaryPropertyName)	string	Yes	data	Name of the binary field containing the spreadsheet file to read. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.
File Format (fileFormat)	options	No	autodetect	The format of the binary data to read from.
				Options: autodetect, csv (comma-separated values), html (HTML table), ods (OpenDocument Spreadsheet), rtf (Rich Text Format), xls (Excel), xlsx (Excel)
Options (options)	collection	No	{}	Parsing settings. Several apply to CSV only.
— Delimiter	string	No	,	Set the field delimiter, usually a comma. (shown when File Format is csv)
— Encoding	options	No	utf-8	Character encoding used to read the CSV text. (shown when File Format is csv)
				Options: ascii, latin1, ucs-2, ucs2, utf-8, utf16le, utf8
— Exclude Byte Order Mark (BOM)	boolean	No	false	Whether to detect and exclude the byte-order-mark from CSV input if present. (shown when File Format is csv)
— Preserve Quotes	boolean	No	false	Whether to handle unclosed quotes in CSV fields as part of the field content instead of throwing a parsing error. (shown when File Format is csv)
— Header Row	boolean	No	true	Whether the first row of the file contains the header names.
— Include Empty Cells	boolean	No	false	Whether to include empty cells when reading from file. They will be filled with an empty string.
— Max Number of Rows to Load	number	No	-1	Stop handling records after the requested number of rows are read. Use -1 to load all rows. (shown when File Format is csv)
— Range	string	No	—	The range to read from the table. If set to a number it will be the starting row. If set to string it will be used as A1-style notation range.
— RAW Data	boolean	No	false	Whether to return RAW data, instead of parsing it.
— Read As String	boolean	No	false	In some cases and file formats, it is necessary to read as string to ensure special characters are interpreted correctly.
— Sheet Name	string	No	Sheet	Name of the sheet to read from in the spreadsheet. If not set, the first one will be chosen.
— Starting Line	number	No	0	Start handling records from the requested line number. Starts at 0. (shown when File Format is csv)
— Skip Records With Errors	fixedCollection	No	{ value: { enabled: false, maxSkippedRecords: -1 } }	Keep parsing past malformed CSV rows instead of failing the whole file. (shown when File Format is csv)
— — Enabled	boolean	No	false	Whether to skip records with errors when reading from file.
— — Max Skipped Records	number	No	-1	The maximum number of records that can be skipped. Set to -1 to remove limit.

Write to File (toFile)

Parameter	Type	Required	Default	Description
File Format (fileFormat)	options	No	xlsx	The format of the file to save the data as.
				Options: csv (comma-separated values), html (HTML table), ods (OpenDocument Spreadsheet), rtf (Rich Text Format), xls (Excel), xlsx (Excel)
Put Output File in Field (binaryPropertyName)	string	Yes	data	The name of the output binary field to put the file in. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.
Options (options)	collection	No	{}	Output settings.
— Compression	boolean	No	false	Whether compression will be applied or not. (shown when File Format is xlsx or ods)
— File Name	string	No	—	File name to set in binary data. Defaults to “spreadsheet.<fileFormat>”.
— Header Row	boolean	No	true	Whether the first row of the file contains the header names.
— Sheet Name	string	No	Sheet	Name of the sheet to create in the spreadsheet. (shown when File Format is ods, xls or xlsx)

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently (used for fromFile operation).

Output Data

Both operations change item cardinality — in opposite directions.

Read From File — one output item per row. Each input item carrying a spreadsheet produces as many output items as the file has rows. Output items carry JSON only; binary data is not forwarded, so the source file does not travel past this node.

With Header Row on (the default), each output item is the row keyed by its column headers:

{
  "orderId": "A-1043",
  "customer": "Acme Ltd",
  "total": 249.5
}

With Header Row off, the row is emitted as an array under a single field:

{
  "row": ["A-1043", "Acme Ltd", 249.5]
}

A file that yields no rows produces no output item for that input, and that is not an error. Empty cells are omitted from the row object unless Include Empty Cells is on, so test for a field’s presence rather than assuming every row has the same keys.

Write to File — exactly one output item for the whole node run. Every input item becomes a row and the node emits a single item whose JSON is empty ({}) and whose binary holds the finished spreadsheet, stored under the name given by Put Output File in Field. Its file name is the Options → File Name value, or spreadsheet.<format> when that is empty, and the MIME type matches the chosen format. Because the JSON is empty, carry anything you still need past this node on a separate branch.

Usage Examples

• Parse an uploaded CSV file into individual row items
• Convert JSON data into an XLSX Excel file for download
• Read an ODS spreadsheet and extract rows as JSON
• Export workflow data to a CSV file with custom delimiter

Example Configuration

Read a CSV:

{
  "type": "spreadsheet_file",
  "parameters": {
    "operation": "fromFile",
    "binaryPropertyName": "data",
    "fileFormat": "csv",
    "maxConcurrency": 5,
    "options": {
      "delimiter": ",",
      "encoding": "utf-8",
      "headerRow": true,
      "includeEmptyCells": false,
      "readAsString": false
    }
  }
}

Read a named sheet and a cell range from an Excel workbook:

{
  "type": "spreadsheet_file",
  "parameters": {
    "operation": "fromFile",
    "binaryPropertyName": "file",
    "fileFormat": "xlsx",
    "maxConcurrency": 10,
    "options": {
      "headerRow": true,
      "sheetName": "Data",
      "range": "A1:Z100",
      "includeEmptyCells": true
    }
  }
}

Autodetect the format and tolerate a few malformed rows:

{
  "type": "spreadsheet_file",
  "parameters": {
    "operation": "fromFile",
    "binaryPropertyName": "spreadsheet",
    "fileFormat": "autodetect",
    "options": {
      "headerRow": true,
      "rawData": false,
      "skipRecordsWithErrors": {
        "value": {
          "enabled": true,
          "maxSkippedRecords": 10
        }
      }
    }
  }
}

Write a CSV:

{
  "type": "spreadsheet_file",
  "parameters": {
    "operation": "toFile",
    "binaryPropertyName": "output",
    "fileFormat": "csv",
    "options": {
      "fileName": "export.csv",
      "headerRow": true
    }
  }
}

Write a compressed Excel workbook with a named sheet:

{
  "type": "spreadsheet_file",
  "parameters": {
    "operation": "toFile",
    "binaryPropertyName": "excelFile",
    "fileFormat": "xlsx",
    "options": {
      "fileName": "report.xlsx",
      "headerRow": true,
      "sheetName": "Results",
      "compression": true
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Convert between spreadsheet binary files (CSV/XLS/XLSX/ODS/HTML/RTF) and JSON items — read spreadsheet rows to JSON or write JSON to a spreadsheet file.

Behavior notes

• Autodetect only distinguishes CSV. A file is treated as CSV when its MIME type says so (or it is plain text named .csv); everything else is handed to the spreadsheet reader, which covers XLS, XLSX, ODS, HTML and RTF. Set File Format explicitly when a CSV arrives with an unhelpful MIME type.
• Several read options are CSV-only. Delimiter, Encoding, Exclude BOM, Preserve Quotes, Max Number of Rows to Load, Starting Line and Skip Records With Errors are ignored on XLS/XLSX/ODS/HTML/RTF. Use Range to limit rows in those formats instead.
• Sheet Name must match exactly. Reading a workbook with a sheet name that is not present fails the item and names the sheet; leave it at the default to take the first sheet.
• Skipping bad rows is opt-in and capped. Turn on Skip Records With Errors → Enabled to keep parsing past malformed rows; set Max Skipped Records to fail once too many have been skipped.
• Write collects the whole branch. Everything that reaches the node in one run goes into one file, so filter and sort upstream — there is no per-item file. To produce one file per group, run the node once per group.