Excel Activities

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

El paquete Excel lee y escribe libros de Excel sin necesidad de tener Microsoft Excel instalado: trabaja directamente sobre el archivo, así que funciona igual en un robot de Windows que en los robots en la nube de Zoan Cloud. 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.

Formatos y requisitos

Formato	Leer y escribir con el paquete	Convertir a PDF (Excel to PDF)
.xlsx	Sí	Sí
.xlsm (con macros)	Sí — las macros no se ejecutan	Sí
.xltx / .xltm (plantillas)	Sí	Sí
.xls (Excel 97-2003)	No	Sí
.csv	No — usa el paquete CSV	Sí
.ods	No	Sí

• Ninguna actividad necesita Microsoft Excel, salvo Excel to PDF, que necesita LibreOffice o Microsoft Excel en la máquina del robot (los robots en la nube de Zoan Cloud ya traen LibreOffice).
• Si pasas un .xls o un .csv a una actividad de lectura o escritura, falla con Extension 'xls' is not supported. Supported extensions are '.xlsx', '.xlsm', '.xltx' and '.xltm'. Para trabajar con un .xls, conviértelo antes a .xlsx (por ejemplo, guardándolo desde Excel).
• Las fórmulas se leen con su resultado (no el texto de la fórmula). Lo que escribe el paquete son valores, no fórmulas.

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 (si escribe) y cierra automáticamente. Ideal para una operación suelta.

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

• Las actividades de lectura (y Clear Excel Range) exigen que el archivo exista: si no, fallan con No se encontró el archivo.
• Las actividades de escritura crean el archivo (y las carpetas que falten) si no existe.

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

En modo sesión el libro vive en memoria: las escrituras no llegan al disco hasta que guardas con Excel Save o Excel Close (o hasta que termina el body de Excel Open).

¿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 sin indicar session ni path y, al terminar, se guarda y cierra solo — un punto intermedio cómodo.

Si indicas session y path a la vez, manda session. Dentro de un body de Excel Open, una actividad sin session ni path usa el libro del body; si le pones path, trabaja sobre ese otro archivo en modo rápido.

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	DataTable: al leer, con o sin encabezados; al escribir, solo los valores
Celda	Read Excel Cell	Write Excel Cell	Un valor suelto, con su tipo

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.

Cómo llegan los datos

• DataTable leída de Excel (Read Excel Sheet, Read Excel Range): desde la versión 1.0.6 cada celda conserva su tipo: los números llegan como número (double), las fechas como fecha (DateTime), los booleanos como booleano y los textos como texto, sin depender de la configuración regional del robot. Una columna que solo tiene texto (o está vacía) es de tipo texto; si trae números, fechas o booleanos admite cualquier valor, así que luego puedes asignarle también un texto. Las celdas vacías son DBNull. Por eso leer una hoja y volver a escribirla deja los números y las fechas como números y fechas en el archivo.
• Celda suelta (Read Excel Cell, y la clave value de Find Excel Cell): conserva el tipo — número (double), fecha (DateTime), booleano o texto; null si está vacía.
• Al escribir: los números, fechas y booleanos se guardan con su tipo; un texto se guarda como texto aunque parezca un número ("1500"). Write Excel Range y Append Excel Range aceptan además listas: una lista de filas (arr(arr("a", 1), arr("b", 2))) o una sola fila (arr("a", 1)). Los valores nulos o DBNull no se escriben: la celda conserva lo que tenía.

Números en una DataTable

Usa num(fila["Total"]): devuelve el número de la celda tal cual y 0 si está vacía. Si la celda guarda el número como texto (una celda con formato de texto en Excel, o un CSV), num lee bien "1500,5", "1.500,5" y "1500.5", y si el texto es ambiguo ("1.500") falla en vez de dar otro número; indica entonces la cultura: num(fila["Total"], "es-CO"). Ver cómo lee num un número escrito como texto.

Notación de celdas y hojas

• Celdas: notación A1 — A1, B3, AA10 (mayúsculas o minúsculas, sin $).
• Rangos: A1:D50 (de la celda superior izquierda a la inferior derecha). Evita rangos de columna completa como A:A: abarcan 1 048 576 filas.
• Hojas: por nombre ("Datos", sin distinguir mayúsculas) o por índice contado desde 1 (1 = primera hoja). Por defecto, la primera hoja.

Hojas con nombre numérico

Un valor de sheet que sea un número —también el texto "2024"— se interpreta siempre como índice, no como nombre. Para una hoja que se llama 2024, usa su posición (sheet = 3) o dale un nombre que no sea solo un número ("Año 2024").

Hojas que no existen

• Al leer (y en Clear Excel Range): la actividad falla con There isn't a worksheet named '…'. (por nombre) o There isn't a worksheet associated with that position. (por índice).
• Al escribir: la hoja se crea. Por nombre, con ese nombre; por un índice mayor que el número de hojas, con el nombre Sheet<n> (por ejemplo Sheet5). Sin sheet, se usa la primera hoja, o se crea Sheet1 si el libro es nuevo.

Actividades

Sesión (abrir, guardar, cerrar)

Actividad	Tipo	Salida	Qué hace
Excel Open (Session)	excel-open	ZoanExcelSession	Abre un libro y devuelve una sesión
Excel Save (Session)	excel-save	—	Guarda la sesión a disco (o a otra ruta)
Excel Close (Session)	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	DataTable	Lee un rango exacto a una DataTable
Read Excel Cell	excel-read-cell	object	Lee una celda
Get Excel Sheet Names	excel-get-sheet-names	List	Nombres de todas las hojas
Get Excel 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

Convertir

Actividad	Tipo	Salida	Qué hace
Excel to PDF	excel-to-pdf	string	Convierte un libro a PDF (requiere LibreOffice o Microsoft Excel)

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

Errores frecuentes en todo el paquete

Mensaje	Causa y solución
Indica 'session' o 'path'.	La actividad no recibió ni sesión ni ruta, y no está dentro del body de un Excel Open. Indica uno de los dos.
No se encontró el archivo.	Una lectura en modo rápido apunta a un archivo que no existe. Comprueba la ruta, o valida antes con File Exists.
Extension 'xls' is not supported. Supported extensions are '.xlsx', '.xlsm', '.xltx' and '.xltm'.	El archivo es .xls, .csv u otro formato. Conviértelo a .xlsx; para CSV usa el paquete CSV.
There isn't a worksheet named '…'.	La hoja no existe al leer. Revisa el nombre o lista las hojas con Get Excel Sheet Names.
The process cannot access the file '…' because it is being used by another process.	El archivo está abierto en Excel (u otro programa) cuando el robot guarda. Ciérralo; en procesos desatendidos, envuelve la escritura en un Retry.

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.