Google Sheets — Configuration

Node Identity

Property	Value
Resources	`spreadsheet`, `sheet`
Total Operations	10
Auth Type	Google OAuth2 (`CredentialId` Guid)
Output Ports	`success`, `error`

Common Properties (All Operations)

Property	Required	Description
`CredentialId`	Required	Guid referencing a Google OAuth2 credential in BizFirst Credentials Manager. The credential must include the `https://www.googleapis.com/auth/spreadsheets` scope. For `spreadsheet/create` and `spreadsheet/delete`, additionally include `https://www.googleapis.com/auth/drive`.

Key Enumerations

DataMode

AutoMap — The node reads the header row of the target sheet and automatically maps the current execution context data to columns by matching names. No manual mapping required.
DefineBelow — You manually define which columns to write and what value to place in each using a ColumnMappings array. Supports BizFirst expressions in the value field.
Nothing — No data mapping is performed. Use when you only need to trigger the structural operation (e.g. clearing a range) without writing data.

CellValueInputOption

UserEntered — Values are interpreted as if typed by a user. Dates, formulas (starting with =), and numbers are parsed accordingly.
Raw — Values are stored as-is without any parsing. Formulas are stored as literal strings.

ExtraDataHandling

IgnoreIt — Extra data fields not matching any column header are silently discarded.
InsertInNewColumn — Extra fields are written to new columns appended after existing headers.
Error — The node throws an error if any data field has no matching column header.

FilterCombineMode

And — All filter conditions must match for a row to be included.
Or — Any matching filter condition includes the row.

DeleteDimension

Rows — Delete the specified row range.
Columns — Delete the specified column range.

spreadsheet Resource

spreadsheet/create

Property	Required	Description
`Title`	Required	Name of the new spreadsheet file. Supports expressions: `{{ vars.report_name }}`.
`Sheets`	Optional	Array of sheet tab titles to create initially. Example: `["January", "February", "Summary"]`. If omitted, Google creates a single default tab named "Sheet1".
`Locale`	Optional	Locale for the spreadsheet, affecting date/number formatting. Example: `en_US`, `en_GB`, `fr_FR`.
`RecalculationInterval`	Optional	How often volatile functions (e.g. `NOW()`, `RAND()`) recalculate. Values: `ON_CHANGE`, `MINUTE`, `HOUR`.

spreadsheet/delete

Property	Required	Description
`SpreadsheetId`	Required	The Google Sheets file ID. Found in the spreadsheet URL: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`. Supports expressions.

Permanent deletion: spreadsheet/delete permanently removes the file from Google Drive. It bypasses Trash. Ensure the correct SpreadsheetId before executing in a production workflow.

sheet Resource

sheet/append

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Name of the sheet tab (exactly as it appears on the tab). Case-sensitive. Supports expressions.
`DataMode`	Required	`AutoMap`, `DefineBelow`, or `Nothing`. See DataMode explanation above.
`ColumnMappings`	Optional	Array of `ColumnMapping` objects. Required when `DataMode` is `DefineBelow`. Each entry: `{ "Column": "ColumnHeader", "Value": "{{ expression }}" }`.
`CellFormat`	Optional	`UserEntered` or `Raw`. Controls how values are parsed by Google Sheets. Default: `UserEntered`.
`HeaderRow`	Optional	Integer row number (1-based) containing column headers. Default: `1`.
`FirstDataRow`	Optional	Integer row number (1-based) where data rows begin. Default: `2`.
`HandlingExtraData`	Optional	`IgnoreIt`, `InsertInNewColumn`, or `Error`. Default: `IgnoreIt`.
`UseAppend`	Optional	Boolean. When `true`, uses Google's native append API (finds the first empty row after existing data). When `false`, calculates the next empty row directly. Default: `true`.

sheet/appendOrUpdate

Searches existing rows using LookupFilters. If a matching row is found, it is updated in place. If no match is found, a new row is appended.

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Sheet tab name.
`DataMode`	Required	`AutoMap`, `DefineBelow`, or `Nothing`.
`ColumnMappings`	Optional	Column-to-value mappings when `DataMode` is `DefineBelow`.
`LookupFilters`	Required	Array of `SheetFilterInfo` objects used to find an existing row. Each entry: `{ "Column": "Email", "Value": "{{ vars.email }}" }`. The node scans all data rows for a match.
`CombineFilters`	Optional	`And` (all filters must match) or `Or` (any filter matches). Default: `And`.
`CellFormat`	Optional	`UserEntered` or `Raw`. Default: `UserEntered`.
`HeaderRow`	Optional	Header row number (1-based). Default: `1`.
`FirstDataRow`	Optional	First data row number (1-based). Default: `2`.
`HandlingExtraData`	Optional	`IgnoreIt`, `InsertInNewColumn`, or `Error`. Default: `IgnoreIt`.

sheet/clear

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Sheet tab name.
`ClearAll`	Required	Boolean. When `true`, clears the entire sheet (all rows and columns). When `false`, clears only the range specified by `StartRow` and `EndRow`.
`StartRow`	Optional	First row to clear (1-based, inclusive). Only used when `ClearAll` is `false`.
`EndRow`	Optional	Last row to clear (1-based, inclusive). Only used when `ClearAll` is `false`.

sheet/create

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID to add the new tab to.
`Title`	Required	Tab name for the new sheet. Supports expressions: `{{ vars.month_name }}`.
`Hidden`	Optional	Boolean. When `true`, the new sheet tab is hidden from view. Default: `false`.
`TabColor`	Optional	Hex color string for the tab (e.g. `#4CAF50` for green). Sets the visual tab color in the Sheets UI.

sheet/delete

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Name of the sheet tab to permanently delete. All data in the tab is removed.

sheet/deleteRowsOrColumns

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Sheet tab name.
`Dimension`	Required	`Rows` or `Columns`. Specifies whether to delete rows or columns.
`StartIndex`	Required	0-based index of the first row or column to delete. Row 1 (header) = index 0. First data row = index 1.
`Amount`	Required	Number of rows or columns to delete starting from `StartIndex`. Example: `StartIndex: 1, Amount: 5` deletes the first 5 data rows (rows 2–6 in the sheet).

sheet/get

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Sheet tab name to read from.
`Filters`	Optional	Array of `SheetFilterInfo` objects to filter returned rows. Each entry: `{ "Column": "Status", "Value": "Pending" }`. If omitted, all data rows are returned.
`CombineFilters`	Optional	`And` or `Or`. Controls how multiple filters are combined. Default: `And`.
`HeaderRow`	Optional	Row number of the header row (1-based). Default: `1`.
`FirstDataRow`	Optional	Row number where data begins (1-based). Default: `2`.
`ValueRender`	Optional	How cell values are rendered in the output. `FORMATTED_VALUE` (as displayed), `UNFORMATTED_VALUE` (raw number/string), or `FORMULA` (the formula string if a formula is present). Default: `FORMATTED_VALUE`.
`DateTimeRender`	Optional	How dates and times are represented. `SERIAL_NUMBER` (Google Sheets numeric serial) or `FORMATTED_STRING` (locale-formatted date string). Default: `FORMATTED_STRING`.
`ReturnFirstMatch`	Optional	Boolean. When `true`, the node returns only the first matching row object instead of an array. Useful when you expect exactly one result. Default: `false`.

sheet/update

Property	Required	Description
`SpreadsheetId`	Required	Google Sheets file ID.
`SheetName`	Required	Sheet tab name.
`DataMode`	Required	`AutoMap`, `DefineBelow`, or `Nothing`.
`ColumnMappings`	Optional	Column-to-value mappings when `DataMode` is `DefineBelow`.
`LookupFilters`	Required	Array of `SheetFilterInfo` objects to identify which rows to update. All matching rows are updated.
`CombineFilters`	Optional	`And` or `Or`. Default: `And`.
`CellFormat`	Optional	`UserEntered` or `Raw`. Default: `UserEntered`.
`HeaderRow`	Optional	Header row number (1-based). Default: `1`.
`FirstDataRow`	Optional	First data row number (1-based). Default: `2`.

ColumnMapping Object Reference

Field	Type	Description
`Column`	string	The exact column header name as it appears in the sheet's header row. Case-sensitive.
`Value`	string	The value to write. Supports BizFirst expressions: `{{ vars.order_id }}`, `{{ nodes.prevNode.output.total }}`, static strings, or formula strings when `CellFormat` is `UserEntered`.

SheetFilterInfo Object Reference

Field	Type	Description
`Column`	string	The column header name to filter on.
`Value`	string	The value to match. Supports BizFirst expressions. Comparison is an exact string match against the cell value (after applying `ValueRender` formatting).

HeaderRow and FirstDataRow defaults: If your sheet has a header in row 1 and data starting in row 2 (the most common layout), you can omit both HeaderRow and FirstDataRow. Only override these if your sheet has a different structure, such as a title in row 1, headers in row 2, and data from row 3.