Excel Reader

1. Visión General

El componente Excel Reader (excel-reader) lee un archivo Excel (.xlsx) fila por fila, sin cargar el archivo entero en memoria de una sola vez. Eso hace posible procesar planillas grandes sin trabarse ni consumir memoria excesiva.

Úsalo cuando el flujo necesita importar datos de una planilla Excel recibida (por ejemplo, en una carga) y ejecutar una acción para cada fila, como dar de alta registros en un sistema.

No es recomendable para archivos que no sean Excel .xlsx, ni para casos en que los datos ya vienen en JSON — en ese caso un ForEach común es suficiente.

2. Prerrequisitos

• El archivo Excel debe estar disponible en el mensaje antes de que corra este componente (por ejemplo, resultado de una carga anterior en el flujo).
• Formato aceptado: archivo binario (.xlsx), provisto como archivo (File) o como secuencia de bytes (byte[]) dentro del mensaje.

3. Autenticación y Conexión

No aplica — este componente no se conecta a sistemas externos, solo lee un archivo ya presente en el mensaje.

4. Configuración / Operaciones Soportadas

El componente tiene una única operación: leer la planilla y, opcionalmente, ejecutar un subflujo para cada fila leída.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
fileName	Sí	Expresión	Nombre de la propiedad del mensaje donde está almacenado el archivo Excel.	"archivoCarga"
sheetName	No	Expresión	Nombre de la hoja específica a leer. Si no se informa, se usa la primera hoja encontrada.	"Hoja1"
step	No	Subflujo	Secuencia de componentes ejecutada para cada fila leída de la planilla.	Un paso que graba cada fila en una base de datos
firstRow	No	Número	Número de la primera fila de datos a considerar (ignora los encabezados por encima de ella). Valor por defecto: 1.	2 (para saltar una fila de encabezado)
isAggregatedResult	No	Texto ("true"/"false")	Si es true, el resultado final trae el cuerpo de respuesta de cada fila procesada. Si es false (por defecto), trae solo contadores de filas procesadas, con éxito y con error.	"true"

Cada fila leída se entrega al subflujo (step) como un objeto con el número de fila y los datos de la fila. Si step no se configura, el componente solo lee el archivo sin ejecutar nada extra por fila.

5. Ejemplos Prácticos

Ejemplo simple: un flujo recibe una planilla de clientes y usa Excel Reader para leer la primera hoja a partir de la segunda fila (saltando el encabezado), ejecutando un subflujo que da de alta a cada cliente en un sistema.

Entrada (mensaje con el archivo ya adjuntado por un paso anterior, por ejemplo una carga):

{
  "archivoCarga": "<archivo .xlsx binario, provisto por un paso anterior>"
}

Configuración del componente:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "archivoCarga",
    "firstRow": "2",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.ejemplo.com/clientes", "method": "POST" }
    }
  }
}

Cada fila se entrega al subflujo así (ejemplo de la fila 2 de la planilla):

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

Respuesta final (contadores, comportamiento por defecto de isAggregatedResult):

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

Ejemplo avanzado: el flujo necesita leer una hoja específica llamada "Pedidos2026" de una planilla con varias hojas, y quiere recibir, al final, el detalle de cada fila procesada (éxito o error) para generar un informe de importación. En ese caso, sheetName se completa con el nombre exacto de la hoja y se activa isAggregatedResult.

Configuración del componente:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "archivoCarga",
    "sheetName": "Pedidos2026",
    "firstRow": "2",
    "isAggregatedResult": "true",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.ejemplo.com/pedidos", "method": "POST" }
    }
  }
}

Respuesta final (detalle de cada fila procesada):

{
  "items": [
    { "body": "{\"status\":\"creado\",\"pedidoId\":101}" },
    { "body": "{\"error\":\"Campo 'valor' inválido en la fila 3\"}" }
  ]
}

6. Cómo funciona la lectura

• Soporta el formato .xlsx (Excel moderno basado en XML).
• Si sheetName no corresponde a ninguna hoja existente, no se lee ninguna fila (sin error explícito).
• La lectura considera la primera hoja compatible encontrada por ejecución.
• Las filas totalmente vacías se ignoran automáticamente.

7. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"file name not found in configuration"	El campo fileName no fue completado.	Configurar fileName apuntando a la propiedad correcta del mensaje.
"file name [nombre] not found in configuration"	El archivo esperado no fue encontrado en el mensaje con ese nombre.	Verificar que un paso anterior del flujo realmente haya provisto el archivo con ese nombre exacto.
Ninguna fila procesada	sheetName no corresponde a ninguna hoja existente en la planilla, o el archivo está vacío.	Comprobar el nombre exacto de la hoja (no distingue mayúsculas/minúsculas, pero debe existir) y que la planilla tenga datos.
Error genérico al abrir el archivo	El archivo enviado no es un .xlsx válido, o está corrupto.	Confirmar que el archivo sea realmente un Excel .xlsx válido.