Excel

📊

Excel

Read spreadsheet rows into structured JSON

The Excel node reads a worksheet from an .xlsx or .xls file and converts each row into a JSON object keyed by the header row. It resolves the file either from the Automation Hub file store or from an artifact storage path, and can filter rows before returning them so downstream steps receive only the data they need.

Common uses include:

• Loading reference data from an uploaded spreadsheet into a workflow.
• Filtering rows by column value before processing (for example, only status = active).
• Turning a report export into a JSON array for iteration or lookups.
• Feeding spreadsheet rows into a downstream API, database, or comparison step.

Before You Start

What you may need	Where to set it up	Why it matters
The Excel file to read	Files	Upload the workbook to the file store and reference it by fileId.
Common sheet names or filter values	Global Variables	Keep repeated sheet names and filter values consistent across workflows.

Actions

Action	Description
excel:readToJsonArray	Read a worksheet and return its rows as a JSON array

---

excel:readToJsonArray

Reads a single worksheet and returns each data row as an object. The header row supplies the object keys; every row below it becomes one object in the output array. When a filter is configured, only rows that satisfy the filter criteria are returned.

All configuration lives under the excelReadDetails root. Filters may be supplied under excelReadDetails.filters (or an optional top-level filters block).

Parameters

Parameter	Type	Required	Default	Description
fileSource	string	Yes	--	Where to load the file from: FILE_STORE or STORAGE_PATH
fileId	string	If fileSource is FILE_STORE	--	Identifier of the file in the Automation Hub file store
filePath	string	If fileSource is STORAGE_PATH	--	Artifact storage path of the workbook
sheetName	string	No	first sheet	Name of the worksheet to read. When omitted, the first sheet is used
headerRowIndex	integer	No	0	Zero-based index of the header row that supplies the object keys
filterOperator	string	No	NONE	How to combine filter criteria. NONE disables filtering and returns all rows
filters[].fieldName	string	Per filter	--	Column name the filter applies to
filters[].operator	string	Per filter	--	Comparison operator for the criterion
filters[].fieldValue	string	Per filter	--	Value to compare the column against

Example: Read active customers from an uploaded workbook

Field	Value
fileSource	FILE_STORE
fileId	cust-2026-q3
sheetName	Customers
headerRowIndex	0
filterOperator	AND
filters[0]	fieldName: status, operator: equals, fieldValue: active

What happens:

1. The node loads the workbook cust-2026-q3 from the file store.
2. It opens the Customers sheet and reads row 0 as the header.
3. Each remaining row is converted into an object keyed by the header cells.
4. Rows where status equals active are kept; the rest are dropped.
5. The filtered rows are returned as the data array for later steps.

---

Output

The action returns a result object with the following fields:

Field	Type	Description
status	string	success when the sheet is read without error
rowCount	integer	Number of rows returned after any filtering
data	array	Array of row objects, each keyed by the header row cells

Example output:

{
  "status": "success",
  "rowCount": 2,
  "data": [
    {"id": "1001", "name": "Acme Corp", "status": "active"},
    {"id": "1002", "name": "Globex", "status": "active"}
  ]
}

---

Common Error Scenarios

Error	Likely Cause	What to Check
Missing excelReadDetails	The configuration root is absent from the step	Ensure the step config contains an excelReadDetails block
fileSource required	No file source was provided	Set fileSource to FILE_STORE or STORAGE_PATH
fileId / filePath missing	The identifier for the chosen source is not set	Provide fileId for FILE_STORE, or filePath for STORAGE_PATH
FILE_ERROR	The workbook is empty or could not be loaded	Confirm the file exists, is a valid .xlsx/.xls, and is not empty
EXCEL_READ_ERROR	The sheet or header row could not be parsed	Check that sheetName exists and headerRowIndex points at a real header row

---

Best Practices

• Pin the header row. Set headerRowIndex explicitly when the sheet has title or banner rows above the real header, so the object keys are correct.
• Name the sheet. Provide sheetName rather than relying on the first sheet, so the step keeps working if the workbook is reordered.
• Filter early. Use filters to drop unwanted rows in the node rather than filtering later, reducing the data downstream steps must process.
• Keep filter values in variables. Store repeated filter values in Global Variables so they are easy to update.
• Validate the source. Match fileSource to how the file actually arrives — FILE_STORE for uploaded files, STORAGE_PATH for artifacts produced by earlier steps.