Excel Activities

Versión: 1.0.0  ·  ID: zoan-packages-excel  ·  Autor: Zoan Software

El paquete Excel lee y escribe archivos .xlsx sin necesidad de tener Microsoft Excel instalado. Es uno de los paquetes más usados en automatización: casi todo proceso de oficina pasa por una hoja de cálculo — leer un listado, llenar una plantilla, consolidar datos, generar un reporte.

Antes de empezar

Hay dos conceptos transversales que conviene entender una vez: los dos modos de trabajo (rápido vs sesión) y los tres niveles de lectura/escritura (hoja, rango, celda). Los explicamos aquí; las páginas de cada actividad los dan por conocidos.

Concepto 1: modo rápido vs. modo sesión

Casi todas las actividades aceptan uno de dos parámetros para indicar sobre qué archivo trabajar: path o session.

Modo rápido (path)

Le pasas la ruta del archivo directamente a la actividad. Esta lo abre, hace la operación, guarda y cierra automáticamente. Ideal para una operación suelta.

Read Excel Sheet   path = = asset("clientes.xlsx")   → output: tabla

Modo sesión (session) — para varias operaciones

Si vas a hacer varias operaciones sobre el mismo archivo, abrirlo y cerrarlo cada vez es lento. En su lugar, lo abres una vez con Excel Open, obtienes una sesión (ZoanExcelSession), y se la pasas a las demás actividades con session. Al final lo cierras con Excel Close (que guarda).

Excel Open   path = = asset("reporte.xlsx")   → output: libro
Write Excel Sheet   session = = libro   sheet = "Datos"     data = = tabla
Write Excel Cell    session = = libro   sheet = "Resumen"   cell = "B2"   value = = total
Excel Close  session = = libro

¿Cuál uso?

• Una sola operación sobre el archivo → modo rápido (path). Más simple.
• Varias operaciones sobre el mismo archivo → modo sesión (session). Más eficiente, y todas las operaciones se ven entre sí antes de guardar.

Excel Open también ofrece un body: las actividades dentro trabajan sobre el libro y, al terminar, se guarda y cierra solo — un punto intermedio cómodo.

Concepto 2: hoja, rango o celda

Puedes leer y escribir con tres granularidades, según lo que necesites:

Nivel	Leer	Escribir	Formato de datos
Hoja	Read Excel Sheet	Write Excel Sheet	DataTable (con encabezados) — el más cómodo
Rango	Read Excel Range	Write Excel Range	Lista de listas (valores crudos)
Celda	Read Excel Cell	Write Excel Cell	Un valor suelto

Empieza por la hoja

Para la mayoría de los casos, Read Excel Sheet (que devuelve una DataTable con encabezados) es la opción más práctica: la recorres con For Each, accedes a celdas con str(fila["Columna"]) y la vuelcas a otra fuente sin convertir.

Notación de celdas y hojas

• Celdas: notación A1 — A1, B3, AA10.
• Rangos: A1:D50 (de la celda superior izquierda a la inferior derecha).
• Hojas: por nombre ("Datos") o por índice 1-based (1 = primera hoja). Por defecto, la primera hoja.

Actividades

Sesión (abrir, guardar, cerrar)

Actividad	Tipo	Salida	Qué hace
Excel Open	excel-open	ZoanExcelSession	Abre un libro y devuelve una sesión
Excel Save	excel-save	—	Guarda la sesión a disco (o a otra ruta)
Excel Close	excel-close	—	Guarda y cierra la sesión

Leer

Actividad	Tipo	Salida	Qué hace
Read Excel Sheet	excel-read-sheet	DataTable	Lee una hoja a una DataTable
Read Excel Range	excel-read-range	List	Lee un rango como valores crudos
Read Excel Cell	excel-read-cell	object	Lee una celda
Get Sheet Names	excel-get-sheet-names	List	Nombres de todas las hojas
Get Used Range	excel-get-used-range	Dictionary	Dimensiones del área con datos
Find Excel Cell	excel-find-cell	Dictionary	Encuentra la primera celda con un valor

Escribir

Actividad	Tipo	Salida	Qué hace
Write Excel Sheet	excel-write-sheet	—	Escribe una DataTable en una hoja
Write Excel Range	excel-write-range	—	Escribe valores desde una celda
Write Excel Cell	excel-write-cell	—	Escribe un valor en una celda
Append Excel Range	excel-append-range	—	Añade filas debajo de los datos existentes
Append Excel Rows	excel-append-rows	—	Añade filas de una DataTable al final (encabezado solo si está vacía)
Clear Excel Range	excel-clear-range	—	Borra el contenido de un rango o la hoja

Un flujo típico

Leer un listado, procesarlo y escribir un reporte:

Read Excel Sheet   path = = asset("pedidos.xlsx")   sheet = "Pedidos"   → output: pedidos

For Each   items = = pedidos   itemVariable = fila
 └─ activities:
      ... procesar cada pedido ...

Write Excel Sheet   path = = "C:/salida/reporte.xlsx"   sheet = "Resultado"   data = = pedidos

Siguientes pasos

• Excel Open — empezar a trabajar con un archivo en modo sesión.
• Read Excel Sheet — la lectura más común.
• Tipos de datos › DataTable — trabajar con los datos leídos.