Spreadsheet File node

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.

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

Parameter	Type	Required	Default	Description
Input Binary Field	string	Yes	data	Name of the binary field the spreadsheet file is read from (fromFile) or written to (toFile); case-sensitive.
File Format (inputFileFormat)	options	No	autodetect	The format of the spreadsheet file being read. Autodetect picks CSV or XLSX from the binary MIME type and file extension.
				Options: autodetect, csv (comma-separated values), html (HTML Table), ods (openDocument Spreadsheet), rtf (rich Text Format), xls (excel), xlsx (excel)
Options	collection	No	{}
				Options: ascii
— Delimiter	string	No	,	Set the field delimiter, usually a comma. (shown when /inputFileFormat is csv)
— Encoding	options	No	utf-8	(shown when /inputFileFormat 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 /inputFileFormat 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 /inputFileFormat 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 /inputFileFormat 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 /inputFileFormat is csv)
— Skip Records With Errors	fixedCollection	No	{"value":{"enabled":false,"maxSkippedRecords":-1}}	(shown when /inputFileFormat 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

Parameter	Type	Required	Default	Description
File Format (outputFileFormat)	options	No	xlsx	The spreadsheet format to write the file 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	string	Yes	data	Name of the binary field the spreadsheet file is read from (fromFile) or written to (toFile); case-sensitive.
Options	collection	No	{}
				Options: ascii
— Compression	boolean	No	false	Whether compression will be applied or not. (shown when /outputFileFormat is xlsx, ods)
— File Name	string	No	—	File name to set in binary data. Defaults to “spreadsheet.”.
— 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 /outputFileFormat is ods, xls, 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.

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

This tool converts spreadsheet files to and from structured items. It is ideal when you need to read rows from a CSV, XLS, XLSX, ODS, HTML, or RTF file, or when you need to write structured data into one of these formats. The tool produces either structured items from a file or a new spreadsheet file from structured items.

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.