The Google Sheets Node enables Rayven workflows to read structured data from a Google Sheets document via the Google Sheets API. It supports extracting specific cell ranges using secure API access and can optionally be used to trigger downstream
What It Does
This node connects to the Google Sheets API v4, reads a defined range from a specified spreadsheet, and emits the resulting data as structured JSON. It is ideal for use cases where data is sourced or maintained in spreadsheets external to Rayven (e.g., operator-entered data, configuration files, batch inputs).
Step-by-Step: How to Configure the Google Sheets Node
-
Add the node
-
Drag the Google Sheets Node from the Inputs panel onto the canvas.
-
-
Open configuration panel
-
Double-click the node to enter credentials, specify the spreadsheet and range, and enable optional polling triggers.
-
-
Connect downstream processing or storage nodes
-
Data will be emitted in structured format, suitable for transformation, filtering, or table storage.
-
Configuration Fields
Basic Settings
| Field | Requirement | Description |
|---|---|---|
| Node Name* | Required | Internal name used to identify the node in the workflow. |
| Endpoint Type* | Required | Currently supported: Read a single range. |
| API URL* | Required | Base API endpoint (default: https://sheets.googleapis.com/v4/spreadsheets/). Do not modify unless explicitly needed. |
| Spreadsheet ID* | Required | The unique ID of the Google Sheet (visible in the URL after /spreadsheets/d/). |
| Range* | Required | The A1-style range of cells to read (e.g., Sheet1!A1:D10). |
Authentication
| Field | Requirement | Description |
|---|---|---|
| JSON Credentials Content* | Required | Paste the full JSON credentials object generated from your Google Cloud Service Account. This must include scopes for https://www.googleapis.com/auth/spreadsheets.readonly. |
Trigger (Optional)
| Field | Description |
|---|---|
| Enable Trigger | If enabled, the node will automatically poll the spreadsheet. |
| Interval Between Trigger Events | Delay between each polling event. |
| Interval Units | Unit of time for the polling interval (Minutes, Hours, Days). |
Activation Filters
| Field | Description |
|---|---|
| Logical Operand | Determines how multiple filters are evaluated: AND or OR. |
| Select Data Source Filter | Limit execution based on UID, device label, or other metadata. |
Output Behavior
The node reads the cell values as rows, converting each into a JSON object using the first row (headers) as keys.
Example:
A sheet like:
| Name | Temperature | Status |
|---|---|---|
| Pump-1 | 65.2 | OK |
| Pump-2 | 74.1 | Fault |
With range Sheet1!A1:C3, would emit:
[
{
"Name": "Pump-1",
"Temperature": "65.2",
"Status": "OK"
},
{
"Name": "Pump-2",
"Temperature": "74.1",
"Status": "Fault"
}
]
Each row is then emitted as a separate payload into the workflow.
Best Practices
-
Always verify sheet permissions and use a service account with read-only access.
-
Keep header row (
A1, etc.) consistent to ensure correct key mapping. -
Use data validation or formatting inside Sheets to reduce errors in downstream parsing.
-
Disable trigger polling if you only want one-time or manual imports.
Use Cases
-
Periodically ingest external configuration files
-
Trigger workflows from shared spreadsheet edits
-
Centralize non-technical user input for structured ingestion
-
Batch load lookup tables, device thresholds, or override values
FAQ
Q: What if the JSON credentials are invalid or missing scopes?
A: The node will fail to authenticate and return a 401 or 403 error. Use a service account with spreadsheets.readonly scope.
Q: Can the node write back to Google Sheets?
A: No. This node is currently read-only.
Q: What happens if the range is empty or partially filled?
A: Empty rows are ignored. Missing fields will be null or omitted in the output.