Skip to content
Zoan Docs

Google Sheets — Open

Google Sheets — Open

Section titled “Google Sheets — Open”

Type: googlesheets-open  ·  Package: Google Sheets Activities v1.0.5  ·  Output: ZoanGoogleSheetsSession

Opens an authenticated session with a Google Sheets spreadsheet and returns it as a ZoanGoogleSheetsSession. It is the starting point: every other activity in the package works on this session.

How it works

Section titled “How it works”

Prepares access to the spreadsheet in spreadsheetId with the chosen authentication. Two ways to use it:

  • With body: the activities inside inherit the session; when the block ends the session closes by itself, also if an activity fails.
  • Without body: returns the session as output; pass it as session to the activities and close it with Google Sheets — Close.

Open does not call Google: it does not check that the spreadsheet exists or that the account has access. Those problems show up on the first read or write, with the matching API error.

Authentication

Section titled “Authentication”

The authType parameter chooses how to authenticate (the Designer shows only the fields of the chosen mode):

  • oauth (default): uses a Zoan Cloud Google OAuth connection in credential, as credential("code-name"). Zoan Cloud hands over a valid token and refreshes it. The connection must be Connected and include the Sheets permission.
  • service-account: uses a service account key stored as a credential (the full JSON downloaded from Google Cloud) in serviceAccount. No consent from a person is needed: ideal for unattended runs. The sheet must be shared with the service account’s email. With impersonateUser, it acts on behalf of a Workspace user (requires domain-wide delegation set up by the Workspace administrator).

Required parameters

Section titled “Required parameters”
ParameterTypeDefaultDescription
spreadsheetIdstring—Spreadsheet ID, from the URL docs.google.com/spreadsheets/d/{ID}/edit.

Optional parameters

Section titled “Optional parameters”
ParameterTypeDefaultDescription
authTypestringoauthAuthentication mode: oauth or service-account.
credentialcredential—OAuth mode: the Zoan Cloud Google OAuth connection, credential("code-name").
serviceAccountcredential—Service account mode: credential whose value is the full JSON key. Never paste the key into the parameter.
impersonateUserstring—Service account mode (optional): email of the Workspace user to act on behalf of.

Sub-flows

Section titled “Sub-flows”

body

Section titled “body”

Activities to run inside the session. They inherit it without setting session, and the session closes when they finish.

Output

Section titled “Output”

Without body, returns a ZoanGoogleSheetsSession: save it in a variable and pass it as session to the other activities. With body it returns nothing (the session is inherited and closes by itself).

Common errors

Section titled “Common errors”
MessageCause and fix
'spreadsheetId' is required.spreadsheetId is empty or its expression returned null.
Credential '…' could not be resolved. Verify it exists in Zoan Automation and that there is an active session.The connection or credential does not exist in the environment, the display name was used instead of the code name, or there is no Zoan Cloud session.
'credential' does not contain a valid access_token. Check the OAuth Connection in Zoan Cloud.The connection exists but has no token (for example, it is still Pending). Authorize it in Zoan Cloud.
'serviceAccount' must reference a Zoan Cloud credential containing the service account JSON key.In service account mode, the credential is empty.
The service account credential is not a valid Google service account JSON key. …The stored value is not the full JSON key. Store it again exactly as downloaded.

Example

Section titled “Example”
Google Sheets — Open   credential = credential("google-operations")   spreadsheetId = "1AbC...XyZ"
 └─ body:
      Google Sheets — Read sheet   sheet = "Orders"   has-headers = true   → output: orders
      Log   message = "Orders read: " + rowCount(orders)

With a service account, for an unattended run:

Google Sheets — Open   authType = service-account   serviceAccount = credential("google-sa-reports")
                       spreadsheetId = sheetId
 └─ body:
      Google Sheets — Append rows   sheet = "Log"   values = summary
Section titled “Related activities”