Excel Online — Connect

Excel Online — Connect

Tipo: excelonline-connect  ·  Paquete: Excel Online v1.0.4  ·  Salida: ZoanExcelOnlineSession

Abre un libro de Excel Online (en OneDrive o SharePoint) a través de Microsoft Graph. Es el punto de partida del paquete: todas las actividades de lectura y escritura trabajan sobre esta sesión, que representa un libro abierto. Es el equivalente en la nube del paquete Excel local.

Cómo funciona

Se autentica con una conexión OAuth de Microsoft 365 de Zoan Cloud y abre el libro indicado por path o por itemId. Tiene dos formas de uso:

• Con body: las actividades que coloques dentro heredan la sesión automáticamente; al terminar el bloque, se cierra sola (también si una actividad del bloque falla).
• Sin body: devuelve la sesión como salida; guárdala en una variable, pásala por session a las demás actividades y ciérrala con Excel Online — Close.

Paso a paso:

1. Obtiene el token de la conexión. La sesión usa ese mismo token hasta cerrarse (no lo renueva); para procesos de más de una hora, abre la sesión por bloques.
2. Si no indicas driveId, resuelve la unidad: el OneDrive de la cuenta de la conexión o, con mailbox, el OneDrive de ese usuario.
3. Busca el libro: por itemId si lo indicas (tiene prioridad sobre path) o por path, la ruta desde la raíz de la unidad.

Connect no abre ni bloquea el archivo: solo lo localiza. Otras personas pueden seguir editándolo mientras el robot trabaja. Que el archivo sea un libro .xlsx válido se comprueba en la primera lectura o escritura.

Autenticación y permisos

La conexión debe incluir los permisos de Microsoft Graph sobre archivos: Files.ReadWrite para el OneDrive de la cuenta, Files.ReadWrite.All para libros de otros usuarios (mailbox) y Sites.ReadWrite.All para bibliotecas de SharePoint (driveId). Más detalle en Excel Online Activities.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
credential	credential	—	Conexión OAuth de Microsoft 365 de Zoan Cloud, referida por su nombre clave: credential("m365-finanzas").

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
path	string	—	Ruta del libro desde la raíz de la unidad, con carpetas y extensión. Ej.: Reportes/Ventas.xlsx. Usa esto o itemId.
itemId	string	—	ID del libro en la unidad (alternativa a path; si das ambos, gana itemId). Lo devuelve, por ejemplo, OneDrive/SharePoint — List files en id.
driveId	string	—	ID de la unidad. Si se omite, se usa el OneDrive de la cuenta de la conexión (o el de mailbox). Usa el ID de una biblioteca de documentos de SharePoint para trabajar con libros de SharePoint.
mailbox	string	—	Usuario (correo o UPN) cuyo OneDrive se usa cuando no das driveId. Omítelo para usar la cuenta que autorizó la conexión. Obligatorio si la credencial trae un token de aplicación (app-only).

Sub-flujos

body opcional

Actividades a ejecutar dentro de la sesión. Heredan la sesión automáticamente y, al terminar, esta se cierra.

Salida

Devuelve un ZoanExcelOnlineSession con el libro abierto. Expone DriveId, ItemId y FileName (nombre del archivo), útiles para registrar qué libro se procesó. Si usas body no necesitas la salida (la sesión se hereda sola) y Connect no devuelve nada. Sin body, asígnala a una variable y pásala como session a las demás actividades.

Errores comunes

Mensaje	Causa y solución
Credential 'm365-finanzas' could not be resolved. Verify it exists in Zoan Automation and that there is an active session.	No existe una credencial o conexión con ese nombre clave en el ambiente, o el robot no tiene sesión en Zoan Cloud. Revisa el nombre clave (no el legible) y que la conexión esté Conectada.
'credential' no contiene un access_token válido. Revisa la conexión OAuth de Microsoft 365 en Zoan Cloud.	La credencial resolvió a un valor vacío. Reconecta la conexión en Zoan Cloud.
InvalidAuthenticationToken (Microsoft Graph, 401)	El valor de credential no es un token: suele pasar al escribir "m365-finanzas" en vez de credential("m365-finanzas"). También aparece si el token venció.
No se pudo determinar la unidad del usuario. Indica 'driveId'.	Microsoft Graph no devolvió una unidad para la cuenta o el mailbox. Indica driveId explícitamente.
Indica 'path' o 'itemId' para ubicar el libro.	No diste ni path ni itemId.
itemNotFound (Microsoft Graph, 404)	No hay un archivo en esa ruta o con ese ID dentro de la unidad, o el mailbox/driveId no existe. Revisa la ruta (sin barra inicial, con extensión) y la unidad.
accessDenied (Microsoft Graph, 403)	A la conexión le falta el permiso para esa unidad (por ejemplo Sites.ReadWrite.All para SharePoint) o la cuenta no tiene acceso al archivo.

Para reintentar ante fallos temporales de Microsoft 365, envuelve el bloque en Retry; para tratar el error y continuar, en Try / Catch.

Ejemplo

Excel Online — Connect   credential = credential("m365-finanzas")   path = "Reportes/Presupuesto.xlsx"
 └─ body:
      Excel Online — Read range   sheet = "Datos"   range = "A1:E20"   has-headers = true   → output: tabla
      Excel Online — Write cell   sheet = "Datos"   cell = "G1"   value = "Procesado"

Libro en una biblioteca de SharePoint, con la sesión en una variable:

Excel Online — Connect   credential = credential("m365-finanzas")   driveId = idBiblioteca   path = "Facturas/Control.xlsx"   → output: libro
Excel Online — Read sheet   session = libro   sheet = "Pendientes"   has-headers = true   → output: pendientes
Excel Online — Close   session = libro

Sin “Guardar” — autoguarda

Excel Online guarda automáticamente cada escritura, por eso no existe una actividad Save. Abre el libro por ruta (Reportes/archivo.xlsx) o por itemId. Para un libro en SharePoint, pasa el driveId de la biblioteca de documentos.

Actividades relacionadas

• Excel Online — Read range — leer un rango de celdas.
• Excel Online — Write range — escribir un rango.
• Excel Online — Close — cerrar la sesión (modo sin body).
• OneDrive/SharePoint — List files — obtener el itemId de un libro.
• Todas las actividades de Excel Online