Skip to content
Zoan Docs

Excel Online — Read range

Excel Online — Read range

Section titled “Excel Online — Read range”

Type: excelonline-read-range  ·  Package: Excel Online v1.0.4  ·  Output: DataTable \| List

Reads a range of cells from a sheet. With has-headers the first row is taken as headers and the result is a DataTable; without headers, it returns a list of rows with the values in their original type.

How it works

Section titled “How it works”

It works on the session created with Excel Online — Connect. Pass it in the session parameter, or place this activity inside the body of Excel Online — Connect to inherit it automatically.

Give the sheet and the range in A1 notation (A1:E10). If you do not know the size of the data, get the address with Used range or read the whole sheet with Read sheet.

The two output shapes treat values differently:

  • With has-headers = true (DataTable): every column is text; numbers arrive as string with the decimal separator of the robot’s regional settings.
  • Without headers (list of rows): each value keeps its type — number, string or bool. Empty cells are empty text ("") and dates are their Excel serial number (convert with DateTime.FromOADate(...)).

It is read-only: it does not modify the workbook.

Required parameters

Section titled “Required parameters”
ParameterTypeDefaultDescription
sheetstring—Sheet name.
rangestring—Range in A1 notation. E.g. A1:E10.

Optional parameters

Section titled “Optional parameters”
ParameterTypeDefaultDescription
sessionZoanExcelOnlineSession—Excel Online — Connect session. Inherited inside Connect’s body.
has-headersboolfalseIf true, the first row of the range holds the headers and the result is a DataTable. If false, the result is a list of rows.

Output

Section titled “Output”

With has-headers = true it returns a DataTable: one row per row of the range (without the header row), with columns named after the first row. Loop over it with a For each and access by column name (row["Customer"]).

Without headers, it returns a list of rows: each row is a list of values, in the order of the range’s columns. Access by index: data[0][1] is the second column of the first row. The row count is in data.Count.

In both cases the size matches the requested range, even if it has empty cells.

Common errors

Section titled “Common errors”
MessageCause and fix
No Excel Online session available. Provide 'session' from an excelonline-connect activity, or place this activity inside the Connect activity's body so the session is inherited automatically.The activity is outside Connect’s body and did not receive session. Place it inside the body or pass session = workbook.
'sheet' is required. / 'range' is required.The parameter is empty or its expression returned null.
itemNotFound (Microsoft Graph, 404)There is no sheet with that name. Check the name with Get sheet names.
InvalidArgument (Microsoft Graph, 400)The range address is not valid A1 notation.
A column named '…' already belongs to this DataTable.With has-headers = true, the first row has two identical headers.

Example

Section titled “Example”
Excel Online — Connect   credential = credential("m365-finance")   path = "Reports/Sales.xlsx"
 └─ body:
      Excel Online — Read range   sheet = "Sales"   range = "A1:D100"   has-headers = true   → output: table
      For each   row in table
       └─ Log   message = row["Customer"]

Reading without headers, using values by position:

Excel Online — Read range   sheet = "Summary"   range = "B2:C2"   → output: totals
Log   message = "Invoiced: " + totals[0][0] + " · Outstanding: " + totals[0][1]
Section titled “Related activities”