Excel Online Activities

Version: 1.0.4 · ID: zoan-packages-excelonline · Author: Zoan Software

The Excel Online package reads and writes .xlsx workbooks stored in OneDrive or SharePoint through Microsoft Graph. It offers the same operations as the local Excel package (sheet, range, cell), but in the cloud and with autosave: every write is saved to the workbook immediately, with no Save step, and people who have it open see it right away. Excel does not need to be installed on the robot’s machine.

Concept 1: authentication and permissions

The activities authenticate with a Microsoft 365 OAuth connection from Zoan Cloud. In Connect you reference it with the credential() function and its key name:

Excel Online — Connect   credential = credential("m365-finance")   path = "Reports/Sales.xlsx"

Zoan Cloud hands the activity a valid access token (and renews it on its own). When you create the connection, select the Microsoft Graph permissions (scopes) that cover the workbooks you will open:

Microsoft Graph permission	What it is for
`Files.ReadWrite`	Read and write workbooks in the OneDrive of the account that authorized the connection.
`Files.ReadWrite.All`	Workbooks of other users (`mailbox`) or shared with the account.
`Sites.ReadWrite.All`	Workbooks stored in SharePoint document libraries (`driveId`).
`offline_access`	Lets Zoan Cloud renew the token without asking for consent again.

If you only read, the equivalent .Read permissions are enough (Files.Read, Files.Read.All, Sites.Read.All); with them, writes fail with accessDenied.

Concept 2: how the workbook is identified

Connect locates the workbook with two pieces of data:

Data	What it is	Where it comes from
Drive (`driveId`)	The OneDrive or document library that holds the workbook.	By default, the OneDrive of the connection’s account (or of `mailbox`). For SharePoint, the library ID (Microsoft Graph returns it at `/sites/{site}/drives`).
Workbook (`path` or `itemId`)	The file inside that drive.	`path` is the path from the drive root (`Reports/Sales.xlsx`); `itemId` is the file ID, for example the `id` returned by OneDrive/SharePoint — List files.

Inside the workbook, sheets are referenced by name (sheet) and cells and ranges in A1 notation (B3, A1:D20). The workbook must be .xlsx.

Concept 3: the session

All operations work on the session opened by Connect:

With body: the activities you place inside inherit the session, and it closes on its own when the block ends.
Without body: Connect returns the session; pass it through session to the other activities and close it with Close.

Concept 4: output shapes

Activity	Returns
Read sheet	`DataTable` with the sheet’s used range.
Read range	`DataTable` if `has-headers = true`; otherwise a `List` of rows (each row is a `List` of values).
Read cell	The cell value (`string`, number or `bool`).
Used range	`Dictionary` with `rows`, `columns` and `address`.
Find cell	`Dictionary` with `address`, `row`, `column` and `value`, or `null` when nothing matches.
Get sheet names	`List<string>` with the sheet names, in tab order.

Values arrive as Excel stores them: numbers as numbers, text as string, empty cells as empty text ("") and dates as Excel serial numbers (for example 45458); convert them with DateTime.FromOADate(...) when you need a date. Writes (Write sheet, Write range, Append rows) take a DataTable (or a single DataRow) and write only the row values, without the column-name row.

Concept 5: API errors

Besides each activity’s own validations, Microsoft Graph can reject an operation. The error carries the message and code returned by Microsoft:

Microsoft Graph code	Usual cause	What to do
`InvalidAuthenticationToken` (401)	The `credential` value is not a valid token (for example, the connection name was written without `credential()`), or the token expired.	Use `credential("key-name")` and check that the connection is Connected in Zoan Cloud.
`accessDenied` (403)	The connection is missing a permission, or the account has no access to the workbook.	Add the permission to the connection and reconnect it, or share the workbook with the account.
`itemNotFound` (404)	The workbook, drive or sheet does not exist with that name, path or ID.	Check `path`/`itemId`/`driveId` and the sheet name (with Get sheet names).
`InvalidArgument` (400)	Invalid A1 address, or a range whose size does not match the data.	Check `cell`/`range`; use Write sheet to have the range computed for you.
429, 503 or 504	Microsoft is temporarily throttling requests or the service is not responding.	Wrap the activity in a Retry with a delay between attempts.

To keep the process going after a failure, use Try / Catch.

Activities

Activity	Type	Output	Description
Excel Online — Connect	`excelonline-connect`	`ZoanExcelOnlineSession`	Opens an Excel Online workbook (Microsoft Graph) by path or item ID
Excel Online — Read sheet	`excelonline-read-sheet`	`DataTable`	Reads all data from a sheet and returns it as a DataTable
Excel Online — Read range	`excelonline-read-range`	`DataTable \| List`	Reads a range of cells
Excel Online — Read cell	`excelonline-read-cell`	`object`	Reads the value of a single cell
Excel Online — Write sheet	`excelonline-write-sheet`	—	Writes a dataset to the sheet starting at A1
Excel Online — Write range	`excelonline-write-range`	—	Writes values to a range (must match the data size)
Excel Online — Write cell	`excelonline-write-cell`	—	Writes a value to a single cell
Excel Online — Append rows	`excelonline-append-rows`	—	Appends rows after the last existing data in a sheet
Excel Online — Clear range	`excelonline-clear-range`	—	Clears the contents of a range of cells
Excel Online — Used range	`excelonline-get-used-range`	`Dictionary<string,object>`	Returns the dimensions of the used area: rows, columns and address
Excel Online — Get sheet names	`excelonline-get-sheet-names`	`List<string>`	Returns the list of sheet names in the workbook
Excel Online — Find cell	`excelonline-find-cell`	`Dictionary<string,object>`	Finds the first cell with a given value
Excel Online — Close	`excelonline-close`	—	Closes an Excel Online session