<!-- BusyBot node reference — https://busybot.net/tools/spreadsheet-file/ -->

> Node: Spreadsheet File (`spreadsheet_file`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# 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:

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

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Write a CSV:

```json
{
  "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:

```json
{
  "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.