Spreadsheet Triggers

Spreadsheet triggers send your scraped data directly to spreadsheets — either in Google Sheets (cloud-based, accessible from anywhere) or in local Excel files on your computer. These triggers are among the most popular because spreadsheets are the universal format for reviewing, analyzing, and sharing data.

If your team lives in Google Sheets or Microsoft Excel, these triggers eliminate the need to manually copy-paste data. Your automation runs, extracts data, and it appears in your spreadsheet automatically — every single time.

When to Use Spreadsheet Triggers

Use Case	Recommended Trigger	Why
Team collaboration on scraped data	Google Sheets	Multiple people can view and edit simultaneously
Client-facing reports	Google Sheets	Share a live link; data updates automatically
Offline analysis	Excel	No internet required to open the file
Integration with Excel macros/formulas	Excel	Native Excel features like pivot tables
Scheduled data delivery	Google Sheets	Combine with Task Scheduler for daily updates
Large datasets (100K+ rows)	Excel	Handles large datasets more reliably than Sheets
Real-time dashboard feeding	Google Sheets	Can connect to Google Data Studio for live dashboards
Archival / record-keeping	Excel	Self-contained file that doesn’t depend on cloud access

---

Google Sheets

The Google Sheets trigger reads from or writes to Google Sheets spreadsheets. Google Sheets is Google’s free, cloud-based spreadsheet application. It works like Excel but lives in your browser, supports real-time collaboration, and can be shared with anyone via a link.

Description

The Google Sheets trigger connects to your Google Drive using a service account and performs operations on a spreadsheet: appending rows, updating specific cells, or reading cell values. This is a per-record trigger when used with append_row, meaning it can write each extracted record as a new row in your spreadsheet.

How It Works

When your automation completes, the Google Sheets trigger:

1. Authenticates with Google using your service account credentials.
2. Locates the target spreadsheet (by ID or by title).
3. Navigates to the specified worksheet (tab).
4. Performs the requested operation (append, update, or read).
5. Stores the result in the output variable (for read operations).

Parameters

Parameter	Type	Required	Default	Description
gcp_credentials_json	string	✅ Yes	—	Your Google Cloud service account JSON credentials. This is the full JSON content of the service account key file. Supports ${variable} substitution.
spreadsheet_id	string	No	—	The unique ID of the target spreadsheet. Found in the spreadsheet’s URL between /d/ and /edit. Use this if you know the exact spreadsheet.
spreadsheet_title	string	No	—	The title (name) of the spreadsheet. Used to find the spreadsheet if you don’t know its ID. If a spreadsheet with this title doesn’t exist, it will be created.
parent_folder_id	string	No	—	The Google Drive folder ID where the spreadsheet should be located (or created). If the spreadsheet doesn’t exist and this is set, the new spreadsheet is placed in this folder.
parent_folder_name	string	No	—	The Google Drive folder name. Alternative to parent_folder_id. If the folder doesn’t exist, it will be created.
share_with_email	string	No	—	An email address to share the spreadsheet with. Useful when the spreadsheet is created automatically and you need to grant access to a specific person.
worksheet_name	string	No	"Sheet1"	The name of the worksheet (tab) within the spreadsheet to operate on. Default is Sheet1.
operation	string	✅ Yes	—	The operation to perform. Options: append_row, update_cell, read_cell.
cell	string	If update_cell or read_cell	—	The cell address to update or read (e.g., A1, B5, D10). Required for update_cell and read_cell operations.
data	any	If append_row or update_cell	—	The data to write. For append_row, this is a list of values (one per column). For update_cell, this is the single value to write. Supports ${variable} substitution.

Operations

The Google Sheets trigger supports three operations:

Operation	Description	Required Parameters
append_row	Adds a new row at the bottom of the worksheet with your data.	data (list of values)
update_cell	Writes a value to a specific cell address.	cell and data
read_cell	Reads the value from a specific cell and stores it in the output variable.	cell

Example 1: Append Scraped Data as Rows

This example appends each extracted product as a new row in a Google Sheet:

{
  "gcp_credentials_json": "${gcp_credentials}",
  "spreadsheet_title": "Product Scraper Results",
  "worksheet_name": "Products",
  "operation": "append_row",
  "data": ["${product_name}", "${product_price}", "${product_url}", "${scrape_date}"]
}

Each time your automation runs, a new row is added with the product name, price, URL, and scrape date.

Example 2: Update a Specific Cell

This example writes the total record count into cell B1 of a summary sheet:

{
  "gcp_credentials_json": "${gcp_credentials}",
  "spreadsheet_id": "1abc123def456ghi789jkl012mno345pqr678stu",
  "worksheet_name": "Summary",
  "operation": "update_cell",
  "cell": "B1",
  "data": "${record_count}"
}

Example 3: Read a Cell Value

This example reads a configuration value from cell A1 and stores it in an output variable:

{
  "gcp_credentials_json": "${gcp_credentials}",
  "spreadsheet_title": "Configuration",
  "worksheet_name": "Settings",
  "operation": "read_cell",
  "cell": "A1"
}

The value read from cell A1 is stored in the trigger’s output variable, which can be used by subsequent triggers.

Example 4: Auto-Create and Share a Spreadsheet

This example creates a new spreadsheet in a specific folder and shares it with a colleague:

{
  "gcp_credentials_json": "${gcp_credentials}",
  "spreadsheet_title": "Weekly Report - ${date}",
  "parent_folder_name": "Automation Reports",
  "share_with_email": "manager@company.com",
  "worksheet_name": "Data",
  "operation": "append_row",
  "data": ["${product_name}", "${product_price}"]
}

If no spreadsheet named “Weekly Report - 2025-01-15” exists in the “Automation Reports” folder, it is created automatically and shared with manager@company.com.

Setting Up Google Sheets Access

Before you can use the Google Sheets trigger, you need to create a Google Cloud service account:

1. Go to the Google Cloud Console.
2. Create a new project (or use an existing one).
3. Go to APIs & Services → Library.
4. Search for and enable the Google Sheets API.
5. Also enable the Google Drive API (needed for folder operations and sharing).
6. Go to IAM & Admin → Service Accounts.
7. Click Create Service Account.
8. Give it a name (e.g., “RTILA Sheets Bot”) and click Create.
9. Under Service Account Permissions, grant Editor access.
10. Click Done.
11. Find your new service account in the list. Click the three dots (⋮) → Manage Keys.
12. Click Add Key → Create New Key → JSON.
13. A JSON file downloads. Open it and copy the entire JSON content.
14. Paste this JSON into the gcp_credentials_json field in RTILA X.

Tip: Store the JSON credentials as a project variable (e.g., ${gcp_credentials}) so you don’t have to paste them into every trigger.

Important: The service account needs access to the spreadsheet. Either:

• Share the spreadsheet with the service account’s email address (found in the JSON file under client_email), OR
• Use the share_with_email parameter to have RTILA share it automatically.

Google Sheets Limits

Limit	Value	What It Means
Maximum rows per sheet	10,000,000	You won’t hit this in normal use
Maximum columns	18,278	More than enough for any dataset
API rate limit	~300 requests per minute	Very high volume scrapes may need delays
Cell content length	50,000 characters	Very long text fields may be truncated

---

Excel

The Excel trigger reads from or writes to local Excel (.xlsx) files on your computer. Unlike Google Sheets, Excel files are stored locally and don’t require an internet connection to open.

Description

The Excel trigger opens a local Excel file and performs operations on it: writing a value to a specific cell or reading a value from a cell. This is useful for offline data processing, integration with Excel macros, or when you need a self-contained file that doesn’t depend on cloud services.

Parameters

Parameter	Type	Required	Default	Description
file_path	string	✅ Yes	—	The path to the Excel file. Relative to RTILA X’s output directory. Example: output/report.xlsx. Supports ${variable} substitution.
sheet_name	string	✅ Yes	—	The name of the worksheet (tab) within the Excel file. Example: Sheet1, Data, Summary.
operation	string	✅ Yes	—	The operation to perform. Options: read_cell, write_cell.
cell	string	If read_cell or write_cell	—	The cell address to read from or write to. Example: A1, B5, D10.
data	any	If write_cell	—	The value to write to the cell. Supports ${variable} substitution.

Operations

The Excel trigger supports two operations:

Operation	Description	Required Parameters
write_cell	Writes a value to a specific cell in the Excel file.	cell and data
read_cell	Reads the value from a specific cell and stores it in the output variable.	cell

Note: Unlike Google Sheets, the Excel trigger does not currently support an append_row operation. To add data to an Excel file, you would typically use the Export to File trigger to create the file, then use the Excel trigger to update specific cells.

Example 1: Write Data to a Cell

This example writes the total record count into cell B1 of an Excel file:

{
  "file_path": "output/monthly_report.xlsx",
  "sheet_name": "Summary",
  "operation": "write_cell",
  "cell": "B1",
  "data": "${record_count}"
}

Example 2: Read a Configuration Value

This example reads a threshold value from cell A1 and stores it in the output variable for use by subsequent triggers:

{
  "file_path": "output/config.xlsx",
  "sheet_name": "Settings",
  "operation": "read_cell",
  "cell": "A1"
}

Example 3: Write a Formatted Value

This example writes a formatted date string into a cell:

{
  "file_path": "output/report_${date}.xlsx",
  "sheet_name": "Data",
  "operation": "write_cell",
  "cell": "A2",
  "data": "Last scraped: ${completion_time}"
}

Excel File Path Rules

Rule	Example
Paths are relative to the output directory	output/report.xlsx resolves to ~/.rtila-x/output/output/report.xlsx
Use forward slashes	output/data/report.xlsx (not backslashes)
You can use variables in paths	output/report_${date}.xlsx
The file must exist for read_cell	The Excel file must already exist before reading
For write_cell, the file is created if missing	A new Excel file is created if it doesn’t exist

Tips for Excel Triggers

Tip	Why It Matters
Use Export to File for bulk data	The Excel trigger is best for cell-level updates, not bulk data. Use the File Format trigger for exporting large datasets to .xlsx.
Create the file first	If you’re using read_cell, make sure the Excel file already exists.
Use descriptive sheet names	Name your worksheets meaningfully (e.g., “Products”, “Summary”) instead of “Sheet1”.
Combine with other triggers	Write a summary cell after exporting data with the File Format trigger.
Use variables in file paths	Include dates in filenames to create timestamped reports: report_${date}.xlsx.

---

Choosing Between Google Sheets and Excel

Factor	Google Sheets	Excel
Internet required?	✅ Yes	❌ No
Collaboration	✅ Real-time, multiple users	❌ One user at a time
Sharing	✅ Share via link	❌ Must send the file
Offline access	❌ No	✅ Yes
Large datasets	⚠️ May slow down over 100K rows	✅ Handles large files well
Append rows	✅ Supported	❌ Not currently supported
Update cells	✅ Supported	✅ Supported
Read cells	✅ Supported	✅ Supported
Setup complexity	Moderate (service account)	Low (just a file path)
Cost	Free (Google account)	Requires Excel license (or free viewer)

Tip: If your team collaborates on data, use Google Sheets. If you need offline access or are building files for archival, use Excel.

Combining Spreadsheet Triggers with Other Triggers

Here are common trigger chains that include spreadsheet triggers:

Pattern 1: Scrape → Append to Google Sheets

Project Run → Extract Data → Google Sheets (append_row)

Every run adds new rows to your Google Sheet. Over time, your spreadsheet builds up a complete dataset.

Pattern 2: Scrape → Export to Excel → Update Summary Cell

Project Run → Extract Data → Export to File (.xlsx) → Excel (write_cell: total count)

Exports all data to an Excel file, then writes a summary statistic into a specific cell.

Pattern 3: Scrape → Google Sheets → Email Notification

Project Run → Extract Data → Google Sheets (append_row) → Email (send notification)

Data goes to Google Sheets, and you get an email confirming the update.

Pattern 4: Read Config from Sheets → Scrape → Append Results

Google Sheets (read_cell: config) → Scrape → Google Sheets (append_row: results)

Reads configuration values from a spreadsheet before scraping, then appends the results.

---

Error Handling

Error	Cause	Solution
“Invalid credentials”	Service account JSON is wrong or expired	Verify the JSON is complete and the service account hasn’t been deleted
“Spreadsheet not found”	The spreadsheet ID or title doesn’t match	Check the ID/title. If using title, make sure the name is exact.
“Permission denied”	Service account doesn’t have access	Share the spreadsheet with the service account’s email address
“Worksheet not found”	The worksheet name doesn’t match	Check the worksheet name. Names are case-sensitive.
“Cell not found”	Invalid cell address	Use standard cell notation like A1, B5, Z100
“File not found” (Excel)	The Excel file doesn’t exist	For read_cell, make sure the file exists first
“API rate limit exceeded”	Too many requests too quickly	Add delays between runs or reduce request frequency

Security Best Practices

Practice	Why It Matters
Store credentials as project variables	Avoids hardcoding sensitive JSON in your project configuration
Use least-privilege service accounts	Only grant Editor access to the specific spreadsheets needed
Don’t share credentials in project exports	If you export your project, credentials in variables are included. Be careful who you share exports with.

| Use separate service accounts per project | Isolates access and makes auditing easier |

##