Excel Reader

1. Overview

The Excel Reader component (excel-reader) reads an Excel file (.xlsx) row by row, without loading the entire file into memory at once. This makes it possible to process large spreadsheets without freezing or consuming excessive memory.

Use it when the flow needs to import data from a received Excel spreadsheet (e.g., from an upload) and run an action for each row, such as registering records in a system.

Not suited for files other than Excel .xlsx, nor for cases where the data already comes in JSON — in that case a plain ForEach is enough.

2. Prerequisites

• The Excel file needs to be available in the message before this component runs (e.g., the result of a previous upload in the flow).
• Accepted format: binary file (.xlsx), made available as a file (File) or as a byte sequence (byte[]) inside the message.

3. Authentication and Connection

Not applicable — this component doesn't connect to external systems, it only reads a file already present in the message.

4. Configuration / Supported Operations

The component has a single operation: read the spreadsheet and, optionally, run a sub-flow for each row read.

Field	Required	Type	Description	Example
fileName	Yes	Expression	Name of the message property where the Excel file is stored.	"uploadedFile"
sheetName	No	Expression	Name of the specific sheet to read. If not informed, the first sheet found is used.	"Sheet1"
step	No	Sub-flow	Sequence of components run for each row read from the spreadsheet.	A step that saves each row to a database
firstRow	No	Number	Number of the first data row to consider (ignores any headers above it). Default value: 1.	2 (to skip a header row)
isAggregatedResult	No	Text ("true"/"false")	If true, the final result carries the response body of each row processed. If false (default), carries only counters of rows processed, with success and errors.	"true"

Each row read is delivered to the sub-flow (step) as an object with the row number and the row data. If step isn't configured, the component just reads the file without running anything extra per row.

5. Practical Examples

Simple example: a flow receives a customer spreadsheet and uses Excel Reader to read the first sheet starting from the second row (skipping the header), running a sub-flow that registers each customer in a system.

Input (message with the file already attached by a previous step, e.g. an upload):

{
  "uploadedFile": "<binary .xlsx file, made available by a previous step>"
}

Component configuration:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "uploadedFile",
    "firstRow": "2",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.example.com/customers", "method": "POST" }
    }
  }
}

Each row is delivered to the sub-flow like this (example of row 2 of the spreadsheet):

{
  "rowNumber": 2,
  "rowData": { "A": "Maria Silva", "B": "maria@example.com", "C": "34" }
}

Final response (counters, isAggregatedResult default behavior):

{
  "totalExecutedRows": 50,
  "success": 50,
  "error": 0
}

Advanced example: the flow needs to read a specific sheet called "Orders2026" from a spreadsheet with multiple sheets, and wants to get, at the end, the detail of each processed row (success or error) to generate an import report. In this case, sheetName is filled with the exact sheet name and isAggregatedResult is enabled.

Component configuration:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "uploadedFile",
    "sheetName": "Orders2026",
    "firstRow": "2",
    "isAggregatedResult": "true",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.example.com/orders", "method": "POST" }
    }
  }
}

Final response (detail of each processed row):

{
  "items": [
    { "body": "{\"status\":\"created\",\"orderId\":101}" },
    { "body": "{\"error\":\"Invalid 'amount' field on row 3\"}" }
  ]
}

6. How Reading Works

• Supports the .xlsx format (modern XML-based Excel).
• If sheetName doesn't match any existing sheet, no row is read (no explicit error).
• Reading considers the first matching sheet found per run.
• Completely empty rows are ignored automatically.

7. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"file name not found in configuration"	The fileName field wasn't filled in.	Configure fileName pointing to the correct message property.
"file name [name] not found in configuration"	The expected file wasn't found in the message under that name.	Check whether a previous step in the flow actually made the file available under that exact name.
No row processed	sheetName doesn't match any existing sheet in the spreadsheet, or the file is empty.	Check the exact sheet name (case is ignored, but it must exist) and whether the spreadsheet has data.
Generic error opening the file	The submitted file isn't a valid .xlsx, or it's corrupted.	Confirm the file is really a valid Excel .xlsx.