Excel Open (Session)

Excel Open (Session)

Type: excel-open  ·  Package: Excel Activities v1.0.6  ·  Output: ZoanExcelSession

Opens an Excel workbook and returns a session (ZoanExcelSession) that you share with the other Excel activities. It is the starting point of session mode, recommended when you are going to perform several operations on the same file: opening it once is much faster than opening and closing it at every step.

If the file does not exist, it starts with a new workbook that is created on disk when saved.

How it works

It loads the workbook into memory. There are two ways to use it:

• With an output variable: store the session in a variable (e.g. workbook), pass it to the activities with session = workbook, and close it at the end with Excel Close.
• With body: the activities inside the sub-flow work on the workbook without setting session or path and, when they finish, it is saved and closed automatically. No Excel Close needed.

Worth knowing:

• While the session is open, changes live in memory; they reach the disk with Excel Save, Excel Close or when the body ends.
• With body, if an activity in the sub-flow fails, the workbook is closed without saving and the error propagates (catch it with a Try / Catch around it). To keep partial progress, save with Excel Save at key points.
• You can nest an Excel Open inside another one’s body: activities use the workbook of the nearest body, and the outer one is restored on exit.
• Formats: .xlsx, .xlsm, .xltx and .xltm. An existing .xls or .csv fails to open — see formats.

Required parameters

Parameter	Type	Default	Description
path	string	—	Path to the .xlsx file. If it does not exist, it is created when saved. Accepts expressions (e.g. asset("data.xlsx")).

Optional parameters

None.

Sub-flows

body

Optional. Activities to run with this workbook. When they finish without errors, the workbook is saved and closed. If omitted, the activity returns the session as its output and you must close it yourself with Excel Close.

Output

Without body, it returns a ZoanExcelSession: pass it as session to the other Excel activities. With body, the activity does not return a value (the session only exists inside the sub-flow).

Common errors

Message	Cause and fix
'path' is required.	path is empty or the expression returned null.
Extension 'xls' is not supported. Supported extensions are '.xlsx', '.xlsm', '.xltx' and '.xltm'.	The file is .xls, .csv or another format the package does not open. Convert it to .xlsx.
The process cannot access the file '…' because it is being used by another process.	Another program has the file locked. Close it or retry with Retry.
Workbooks need at least one worksheet.	The file did not exist and a save was attempted (on close or at the end of the body) without writing anything: a workbook needs at least one sheet. Write something before saving, or close with save = false.

Example

With an output variable:

Excel Open   path = asset("report.xlsx")   → output: workbook
Write Excel Sheet   session = workbook   sheet = "Data"      data = table
Write Excel Cell    session = workbook   sheet = "Summary"   cell = "B2"   value = total
Excel Close  session = workbook

With body (no session in the activities inside):

Excel Open   path = "C:/reports/sales.xlsx"
 └─ body:
      Read Excel Sheet   sheet = "Orders"    → output: orders
      Write Excel Cell   sheet = "Summary"   cell = "B2"   value = rowCount(orders)

Fast mode for a single operation

If you are only doing one read or write, you don’t need a session: use the activity’s path parameter directly, which opens and closes the file for you. See fast mode vs. session.

Related activities

• Excel Close — save and close the session.
• Excel Save — save without closing.
• Read Excel Sheet / Write Excel Sheet — work with the session.