Google Apps Script HTTP Service for Google Sheets

An n8n community node that provides a user-friendly interface to interact with Google Sheets via the oogle Apps Script HTTP Service. This node abstracts away HTTP/JSON complexity and provides intuitive form fields for all GAS service operations.

n8n is a fair-code licensed workflow automation platform.

Features

• All 10 GAS HTTP Service Operations: Complete support for 4 GET and 6 POST operations
• Smart UI: Dynamic form fields that show/hide based on operation type
• Read Operations: Get rows, named rows, ranges, and cells with column mapping support
• Write Operations: Append/write rows (named or indexed), ranges, and cells
• Column Mapping: Named operations use field-to-column mappings from Master Sheet
• Error Handling: Comprehensive error messages with user-friendly descriptions
• Type Safety: Full TypeScript implementation with strict type checking
• Secure: Token-based authentication with granular permission system

Table of Contents

• Quick Start (5 Minutes)
• Installation
• Prerequisites
• Master Sheet Configuration
• Operations
• Usage Examples
• Field Reference
• Workflow Patterns
• Response Formats
• Troubleshooting
• Advanced Usage
• Security
• Development
• Resources

Quick Start (5 Minutes)

Step 1: Install and Build

cd /home/den/w/AI/AI_WF/GAS_Server/n8n_plugin
npm install
npm run build

Step 2: Deploy to n8n

# Copy to n8n custom nodes
mkdir -p ~/.n8n/custom
cp -r dist/* ~/.n8n/custom/

# Start n8n
n8n start

Step 3: Deploy GAS Service

1. Open Google Apps Script
2. Create new project
3. Copy content of GAS_HTTP_Service_...js file provided with your product distribution.
4. Click Deploy → New deployment
5. Type: Web app
6. Execute as: Me
7. Who has access: Anyone
8. Click Deploy
9. Copy the deployment URL (you'll need this!)

Step 4: Configure Master Sheet

Create a new Google Sheet with these tabs:

Tab 1: permissions

user_email          | user_token    | sheet_url                                        | can_read_tabs | can_write_tabs | allowed_operations
demo@example.com    | demo123       | https://docs.google.com/spreadsheets/d/YOUR_ID  | data          | data           | get_row,append_row

Tab 2: logs

timestamp | google_sheet_url | operation | error_name | error_and_request_contents
(empty - will be auto-populated)

Important: Keep this Master Sheet private (don't share it)!

Step 5: Test in n8n

1. Open n8n at http://localhost:5678
2. Create new workflow
3. Search for "GAS HTTP Service"
4. Drag node to canvas
5. Configure:
   • GAS Service URL: Your deployment URL from Step 3
   • Master Sheet URL: URL of sheet from Step 4
   • Target Sheet URL: Same as Master Sheet (for testing)
   • User Token: demo123
   • Operation: Select "Get Row"
   • Tab Name: permissions
   • Row Number: 2
6. Click Execute Node

✅ Success! You should see the row data in the output.

Installation

Via n8n Community Nodes (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-google-sheets-gas-http-service
4. Agree to the risks
5. Select Install

Local Development

cd /home/den/w/AI/AI_WF/GAS_Server/n8n_plugin
npm install
npm run build
mkdir -p ~/.n8n/custom
cp -r dist/* ~/.n8n/custom/
n8n start

Prerequisites

You need:

1. GAS HTTP Service Deployed: GAS_HTTP_Service_v2.js as Google Apps Script web app
2. Master Sheet with:
   • permissions tab: User permissions and tokens
   • logs tab: Operation logging
   • Mapping tabs: Column name mappings (optional)
3. Service URL: Deployed web app URL
4. User Token: Authentication token from permissions table

Master Sheet Configuration

1. Permissions Tab

user_email,user_token,sheet_url,can_read_tabs,can_write_tabs,allowed_operations
user@example.com,secret_token,https://docs.google.com/spreadsheets/d/ID,"tab1,tab2","tab1,tab3","get_row,append_row"

Fields:

• user_email: User's email
• user_token: Secret authentication token
• sheet_url: Target sheet URL (must match exactly)
• can_read_tabs: Comma-separated readable tabs
• can_write_tabs: Comma-separated writable tabs
• allowed_operations: Comma-separated allowed operations

Note: Sequential rows can omit user_email/user_token to inherit.

2. Logs Tab

timestamp,google_sheet_url,operation,error_name,error_and_request_contents

Auto-populated by GAS service for auditing.

3. Mapping Tabs (Optional)

request_field_name,column_name
name,Full Name
email,Email Address
status,Status

Maps workflow field names to sheet column headers.

Operations

Read Operations (GET)

Get Row

Read row by number, returns array.

Parameters: Tab Name, Row Number
Returns: ["value1", "value2", "value3"]

Get Named Row

Read row with mappings, returns object.

Parameters: Tab Name, Row Number, Mapping Tab Name
Returns: {"name": "John", "email": "john@example.com"}

Get Range

Read cell range, returns 2D array.

Parameters: Tab Name, Range (e.g., A1:C10)
Returns: [["r1c1", "r1c2"], ["r2c1", "r2c2"]]

Get Cell

Read single cell.

Parameters: Tab Name, Cell (e.g., B5)
Returns: Cell value

Write Operations (POST)

Append Row

Append array data.

Parameters: Tab Name, Row Data (JSON array)

Append Named Row

Append with mappings.

Parameters: Tab Name, Mapping Tab Name, Row Data (JSON object)

Write Row

Write to specific row.

Parameters: Tab Name, Row Number, Row Data (JSON array)

Write Named Row

Write with mappings.

Parameters: Tab Name, Row Number, Mapping Tab Name, Row Data (JSON object)

Write Range

Write 2D array.

Parameters: Tab Name, Range, Range Data (2D JSON array)

Write Cell

Write single value.

Parameters: Tab Name, Cell, Cell Value

Field Reference

Always Required

• GAS Service URL: Deployed script URL
• Master Sheet URL: Master sheet URL or ID
• Target Sheet URL: Target sheet URL or ID
• User Token: From permissions table (password field)
• Operation: Operation dropdown (grouped by type)
• Tab Name: Sheet tab name (case-sensitive)

Operation-Specific

Operation	Additional Fields
get_row, write_row	Row Number
get_named_row, write_named_row	Row Number, Mapping Tab Name
append_row	Row Data (array)
append_named_row	Mapping Tab Name, Row Data (object)
get_range, write_range	Range (A1 notation)
get_cell, write_cell	Cell (A1 notation)

Smart UI: Fields auto-show based on operation.

Usage Examples

Append Named Row

{
  "parameters": {
    "gasServiceUrl": "https://script.google.com/macros/s/ID/exec",
    "masterSheetUrl": "https://docs.google.com/spreadsheets/d/MASTER_ID",
    "targetSheetUrl": "https://docs.google.com/spreadsheets/d/TARGET_ID",
    "userToken": "token",
    "operation": "append_named_row",
    "tabName": "data",
    "mappingTabName": "mapping",
    "namedRowData": "{\"name\": \"John\", \"email\": \"john@example.com\"}"
  }
}

Workflow Patterns

# Read and Transform
Trigger → Get Named Row → Transform → Append Named Row

# Batch Write
Webhook → Loop → Append Row

# Sheet Sync
Schedule → Get Range → Loop → Transform → Write Row

Response Formats

GET Success

{"operation": "get_named_row", "success": true, "data": {"name": "John"}}

POST Success

{"operation": "append_row", "success": true}

Error

{"error": "Invalid user_token", "operation": "append_row"}

Troubleshooting

Node Not Appearing

rm -rf ~/.n8n/custom && npm run build && cp -r dist/* ~/.n8n/custom/

Invalid Token

• Check exact match in permissions (case-sensitive)
• No extra spaces
• Token not removed/changed

Master Sheet Not Found

• Verify URL/ID correct
• Script can access sheet
• Sheet private to script owner

Target Sheet Not Found

• Correct URL in permissions
• Sheet exists and accessible
• URLs match exactly

Operation Not Permitted

• Check allowed_operations includes operation
• Exact name match (lowercase, underscore)

Tab Not Permitted

• Check can_read_tabs/can_write_tabs
• Exact name (case-sensitive)
• Tab exists

Advanced Usage

n8n Expressions

// Dynamic operation
{{ $json.operation }}

// Dynamic row number
{{ $json.rowIndex }}

// Build data object
{{ {"name": $json.name, "email": $json.email} }}

Continue On Fail

Enable to handle errors gracefully without stopping workflow.

Performance Tips

1. Use write_range vs multiple write_cell
2. Cache mapping tab names
3. Read ranges vs individual rows
4. Use Split In Batches for large data

Security

Token Management

• Unique tokens per user/workflow
• Store in credentials/env vars
• Rotate regularly (90 days)
• Never commit to version control

Master Sheet

• Keep private (not shared)
• Share only with script owner
• Audit permissions regularly
• Monitor logs for suspicious activity

Permissions

• Minimum necessary access
• Separate tokens per purpose
• Restrict tabs appropriately
• Review unused tokens

Development

# Build
npm install && npm run build

# Test locally
cp -r dist/* ~/.n8n/custom/ && n8n start

# Lint
npm run lint && npm run lintfix

Technical Details

• Language: TypeScript (strict mode)
• Lines: 557 (main node)
• Parameters: 13 (conditional display)
• Operations: 10 (4 read, 6 write)
• Helper Functions: 5

Testing Checklist

• GAS service deployed
• Master Sheet configured
• Test token added
• Node appears in n8n
• Get/append operations work
• Named operations work
• Error handling works
• Logs written correctly

Compatibility

• n8n 1.0.0+
• GAS_HTTP_Service_v2.js
• Node.js 18+
• TypeScript 5.3+

Resources

• n8n Documentation
• Community Nodes
• Google Apps Script

Package Information

• Name: n8n-nodes-google-sheets-gas-http-service
• Version: 1.0.0
• Category: Data & Storage
• License: MIT

Future Enhancements

1. Dedicated credential type for tokens
2. Dynamic tab/sheet selection
3. Pre-validation of permissions
4. Bulk operations support
5. Mapping table caching

Support

1. Check documentation and troubleshooting
2. Review GAS logs tab
3. Check n8n console errors
4. Open GitHub issue
5. Contact via n8n community

Version History

1.0.0 (2026-01-19)

• All 10 GAS operations
• Smart conditional UI
• Full error handling
• TypeScript implementation
• Complete documentation

---

Status: ✅ Ready for deployment
Setup Time: ~5 minutes
Ready to use! 🚀

Publishing to npm

For Package Maintainers

This package is ready to publish to npm. See PUBLISHING.md for detailed instructions.

Quick Publish

# First time setup
npm login

# Verify everything is ready
npm run verify

# Test what will be published
npm run publish:dry

# Publish (first release)
npm publish

# Or for subsequent releases
npm run publish:patch   # 1.0.0 → 1.0.1 (bug fixes)
npm run publish:minor   # 1.0.0 → 1.1.0 (new features)
npm run publish:major   # 1.0.0 → 2.0.0 (breaking changes)

Before Publishing

1. Update your information in package.json:

   • homepage: Your GitHub repo URL
   • author.name: Your name
   • author.email: Your email
   • repository.url: Your GitHub repo URL
   • bugs.url: Your GitHub issues URL

2. Initialize git repository (optional but recommended):

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/n8n-nodes-google-sheets-gas-http-service.git
git push -u origin main

3. Run verification:

npm run verify

See PUBLISHING.md for complete publishing guide.