Google Sheets

1. Overview

The Google Sheets component (google-sheets) allows creating spreadsheets, reading, updating, appending, and clearing data in a Google Sheets spreadsheet.

Use it when the flow needs to write or query data in a shared spreadsheet. Works only as an output action.

2. Prerequisites

• An OAuth 2.0 application configured at the platform level (clientId, clientSecret, applicationName — configured globally, not in the step).
• A valid accessToken and refreshToken for the Google account with access to the spreadsheet.
• The ID of the spreadsheet (spreadsheetId) to use.

3. Authentication and Connection

Field	Required	Type	Description	Example
accessToken	Yes	Text	Google OAuth access token.	An OAuth token
refreshToken	Yes	Text	Google OAuth refresh token.	An OAuth refresh token

TO CONFIRM: this component's clientId, clientSecret, and applicationName come exclusively from a global application configuration (they can't be set per flow), unlike the Google Calendar component, which also accepts these fields in the step.

4. Configuration / Supported Operations

Field	Required	Type	Description	Example
operation	Yes	Text: CREATE, CLEAR, UPDATE, APPEND, READ	Operation to run on the spreadsheet.	"APPEND"
spreadsheetId	Yes, except in CREATE	Text	Spreadsheet ID (found in the Google Sheets URL).	"1AbCdEfGhIjKlMnOpQrStUvWxYz"
range	No	Text	Cell range to consider.	"Sheet1!A1:C10"
valueInput	No	Text	How the sent values are interpreted by Google Sheets. Default value: "USER_ENTERED" (as if typed by a user, applying formatting/formulas).	"RAW"
payload	Yes, in APPEND and UPDATE	Text (JSON, row matrix)	Data to insert or update, in the format of a list of rows, each row a list of values.	[["Maria", "maria@example.com"]]

5. Practical Examples

Simple example: add a new row with a customer's data in a spreadsheet.

Input:

{
  "customer": { "name": "Maria Silva", "email": "maria@example.com" }
}

Component configuration:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "APPEND",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Customers!A1",
    "payload": "[[\"{$.body.customer.name}\", \"{$.body.customer.email}\"]]"
  }
}

Response:

{
  "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "updates": { "updatedRange": "Customers!A5:B5", "updatedRows": 1 }
}

Advanced example: read a data range from a spreadsheet to process in the flow.

Component configuration:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "READ",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Customers!A1:B10"
  }
}

Response:

{
  "range": "Customers!A1:B10",
  "values": [
    ["Maria Silva", "maria@example.com"],
    ["John Smith", "john@example.com"]
  ]
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"Missing required environment variables for Google Sheets configuration: ..."	Global credentials (clientId/clientSecret/applicationName) aren't configured on the platform.	Configure OAuth credentials at the application level.
"Operation not specified or invalid."	The operation field wasn't filled in or isn't recognized.	Fill in operation with one of the supported values.
"Spreadsheet ID is empty."	The spreadsheetId field wasn't filled in.	Fill in spreadsheetId with the spreadsheet's ID.
"Payload is empty."	The APPEND/UPDATE operations were used without the payload field.	Fill in payload with the values matrix to insert/update.
"Failed to parse payload: ..."	The payload text isn't valid JSON in the expected format.	Review the JSON format in payload (must be a list of lists).
"Request to Google Sheets failed: ..."	Communication error with the Google Sheets API (permission, expired token, nonexistent spreadsheet).	Review the account's permissions and the tokens' validity.