Excel Online — Connect

Excel Online — Connect

Type: excelonline-connect  ·  Package: Excel Online v1.0.4  ·  Output: ZoanExcelOnlineSession

Opens an Excel Online workbook (in OneDrive or SharePoint) through Microsoft Graph. It is the starting point of the package: every read and write activity works on this session, which represents an open workbook. It is the cloud counterpart of the local Excel package.

How it works

It authenticates with a Microsoft 365 OAuth connection from Zoan Cloud and opens the workbook given by path or itemId. It can be used in two ways:

• With body: the activities you place inside inherit the session automatically; when the block ends, it closes on its own (also if an activity in the block fails).
• Without body: it returns the session as output; store it in a variable, pass it through session to the other activities and close it with Excel Online — Close.

Step by step:

1. It gets the connection’s token. The session keeps using that token until it is closed (it is not renewed); for processes longer than an hour, open the session in blocks.
2. If you do not give driveId, it resolves the drive: the OneDrive of the connection’s account or, with mailbox, that user’s OneDrive.
3. It looks up the workbook: by itemId if given (it takes precedence over path) or by path, the path from the drive root.

Connect neither opens nor locks the file: it only locates it. Other people can keep editing it while the robot works. Whether the file is a valid .xlsx workbook is checked on the first read or write.

Authentication and permissions

The connection must include Microsoft Graph file permissions: Files.ReadWrite for the account’s OneDrive, Files.ReadWrite.All for other users’ workbooks (mailbox) and Sites.ReadWrite.All for SharePoint libraries (driveId). More detail in Excel Online Activities.

Required parameters

Parameter	Type	Default	Description
credential	credential	—	Zoan Cloud Microsoft 365 OAuth connection, referenced by its key name: credential("m365-finance").

Optional parameters

Parameter	Type	Default	Description
path	string	—	Path of the workbook from the drive root, with folders and extension. E.g. Reports/Sales.xlsx. Use this or itemId.
itemId	string	—	Drive item ID of the workbook (alternative to path; if both are given, itemId wins). OneDrive/SharePoint — List files returns it as id, for example.
driveId	string	—	Drive ID. When omitted, the OneDrive of the connection’s account (or of mailbox) is used. Use the ID of a SharePoint document library to work with SharePoint workbooks.
mailbox	string	—	User (email or UPN) whose OneDrive is used when no driveId is given. Omit it to use the account that authorized the connection. Required if the credential holds an app-only token.

Sub-flows

body optional

Activities to run inside the session. They inherit the session automatically and, when they finish, the session is closed.

Output

Returns a ZoanExcelOnlineSession for the open workbook. It exposes DriveId, ItemId and FileName (the file name), handy for logging which workbook was processed. With body you do not need the output (the session is inherited) and Connect returns nothing. Without body, assign it to a variable and pass it as session to the other activities.

Common errors

Message	Cause and fix
Credential 'm365-finance' could not be resolved. Verify it exists in Zoan Automation and that there is an active session.	There is no credential or connection with that key name in the environment, or the robot has no Zoan Cloud session. Check the key name (not the display name) and that the connection is Connected.
'credential' does not contain a valid access_token. Check the Microsoft 365 OAuth Connection in Zoan Cloud.	The credential resolved to an empty value. Reconnect the connection in Zoan Cloud.
InvalidAuthenticationToken (Microsoft Graph, 401)	The credential value is not a token: this usually happens when writing "m365-finance" instead of credential("m365-finance"). It also appears when the token expired.
Could not resolve the user's drive. Provide 'driveId'.	Microsoft Graph returned no drive for the account or mailbox. Give driveId explicitly.
Provide either 'path' or 'itemId' to locate the workbook.	Neither path nor itemId was given.
itemNotFound (Microsoft Graph, 404)	There is no file at that path or with that ID in the drive, or the mailbox/driveId does not exist. Check the path (no leading slash, with extension) and the drive.
accessDenied (Microsoft Graph, 403)	The connection lacks permission for that drive (for example Sites.ReadWrite.All for SharePoint) or the account has no access to the file.

To retry on transient Microsoft 365 failures, wrap the block in Retry; to handle the error and continue, in Try / Catch.

Example

Excel Online — Connect   credential = credential("m365-finance")   path = "Reports/Budget.xlsx"
 └─ body:
      Excel Online — Read range   sheet = "Data"   range = "A1:E20"   has-headers = true   → output: table
      Excel Online — Write cell   sheet = "Data"   cell = "G1"   value = "Processed"

Workbook in a SharePoint library, with the session in a variable:

Excel Online — Connect   credential = credential("m365-finance")   driveId = libraryId   path = "Invoices/Tracking.xlsx"   → output: workbook
Excel Online — Read sheet   session = workbook   sheet = "Pending"   has-headers = true   → output: pending
Excel Online — Close   session = workbook

No “Save” — it autosaves

Excel Online saves every write automatically, which is why there is no Save activity. Open the workbook by path (Reports/file.xlsx) or by itemId. For a workbook in SharePoint, pass the driveId of the document library.

Related activities

• Excel Online — Read range — read a range of cells.
• Excel Online — Write range — write a range.
• Excel Online — Close — close the session (no-body mode).
• OneDrive/SharePoint — List files — get a workbook’s itemId.
• All Excel Online activities