Excel Workflow

Excel Workflow

Complete workflow for Excel file management with local processing, Google Drive backup, formula preservation, and SQLite tracking.

Features

• ✅ Formula Preservation — Update cells without losing formulas (powered by openpyxl)
• ✅ Google Drive Sync — Automatic backup to Google Drive using rclone
• ✅ SQLite Tracking — Track all files, formulas, and metadata in local database
• ✅ Multi-file Support — Work with multiple Excel files simultaneously
• ✅ Data Analysis — Query data, read formulas, and analyze structure
• ✅ Mass Operations — Create formulas for entire columns at once

Quick Start

1. Upload Excel File

Simply drop an .xlsx file into the chat. The workflow automatically:

1. Analyzes file structure (sheets, formulas)
2. Uploads to Google Drive (gdrive:Excel/)
3. Saves metadata to SQLite tracker

# Manual processing
~/.openclaw/tools/openclaw-excel/excel-workflow process /path/to/file.xlsx

2. Query Data

# Ask questions about your data
~/.openclaw/tools/openclaw-excel/excel-workflow query "what is total revenue?" --file sales.xlsx

3. Update Cells (Formulas Preserved!)

# Update values - formulas stay intact
~/.openclaw/tools/openclaw-excel/excel-workflow update '{"C2": 100}' --file sales.xlsx

# Update formulas
~/.openclaw/tools/openclaw-excel/excel-workflow update '{"D2": "=B2*C2*1.5"}' --file sales.xlsx

Installation

Prerequisites

1. Python 3.8+ with openpyxl
2. rclone for Google Drive integration
3. Google Drive account

Step 1: Install Dependencies

# Install rclone (macOS)
brew install rclone

# Python packages (installed in venv automatically)
pip install openpyxl

Step 2: Setup Google Drive

# Configure rclone with Google Drive
rclone config

Follow prompts:

• Name: gdrive
• Storage: drive (Google Drive)
• Scope: 1 (Full access)
• Auto config: y (opens browser for OAuth)

Verify:

rclone lsd gdrive:

Step 3: Create Excel Folder

rclone mkdir gdrive:Excel/

Step 4: Install Skill Files

The skill consists of 3 components:

1. Excel CLI (~/.openclaw/tools/openclaw-excel/excel)

   • Commands: info, read, update, show-formulas, get-cell

2. Tracker CLI (~/.openclaw/tools/openclaw-excel/excel-tracker)

   • SQLite database at ~/.openclaw/excel_tracker.db
   • Commands: add, get-latest, search, list, stats

3. Workflow Orchestrator (~/.openclaw/tools/openclaw-excel/excel-workflow)

   • Commands: process, query, update, list, stats

See Installation Guide for detailed setup.

Commands

Process Command

Analyze file, upload to Drive, and save to tracker:

excel-workflow process /path/to/file.xlsx [--telegram-id ID]

Output:

{
  "status": "success",
  "filename": "sales.xlsx",
  "file_id": 1,
  "drive_url": "gdrive:Excel/sales.xlsx",
  "analysis": {
    "sheets": 2,
    "formulas": 15,
    "sheet_names": ["Sales", "Summary"]
  },
  "message": "✅ File processed successfully!"
}

Query Command

Read data and answer questions:

excel-workflow query "show me the data" [--file filename.xlsx]

Output:

{
  "filename": "sales.xlsx",
  "file_id": 1,
  "sheets": ["Sales", "Summary"],
  "data": [
    [
      {"address": "A1", "value": "Product", "type": "str"},
      {"address": "B1", "value": "Price", "type": "int"}
    ]
  ],
  "formulas": [
    {"cell": "D2", "formula": "=B2*C2"}
  ],
  "question": "show me the data",
  "context": {
    "sheet_count": 2,
    "formula_count": 15,
    "uploaded_at": "2026-02-20 10:30:00"
  }
}

Update Command

Update cells (values or formulas):

# Update values
excel-workflow update '{"C2": 100, "C3": 200}' [--file filename.xlsx]

# Update formulas
excel-workflow update '{"D2": "=B2*C2*1.5"}' --file sales.xlsx

# Mass update - create formulas for entire column
excel-workflow update '{"D2": "=B2*0.5", "D3": "=B3*0.5", ...}' --file data.xlsx

Output:

{
  "status": "success",
  "filename": "sales.xlsx",
  "updated": 2,
  "changes": [
    {"cell": "C2", "old_value": 50, "new_value": 100},
    {"cell": "C3", "old_value": 75, "new_value": 200}
  ],
  "message": "✅ Updated and re-uploaded to Google Drive"
}

List Command

Show tracked files:

excel-workflow list [--limit 10]

Output:

[
  {
    "id": 2,
    "original_filename": "sales_2026.xlsx",
    "sheet_count": 2,
    "formula_count": 15,
    "uploaded_at": "2026-02-20 14:20:00"
  },
  {
    "id": 1,
    "original_filename": "budget.xlsx",
    "sheet_count": 3,
    "formula_count": 42,
    "uploaded_at": "2026-02-19 09:15:30"
  }
]

Stats Command

Show statistics:

excel-workflow stats

Output:

{
  "total_files": 5,
  "files_on_drive": 5,
  "total_sheets": 12,
  "total_formulas": 87
}

Usage Patterns for AI Agents

Pattern 1: User Uploads Excel File

User action: Uploads sales.xlsx via Telegram

Agent workflow:

1. File saved to temporary location by Telegram handler
2. Detect .xlsx extension
3. Run: excel-workflow process /path/to/sales.xlsx --telegram-id <id>
4. Parse JSON result and respond:

Agent: "✅ I've received and processed sales.xlsx!

📊 Analysis:
- 2 sheets: Sales, Summary
- 15 formulas detected
- ☁️ Uploaded to Google Drive

What would you like to know about this file?"

Pattern 2: User Asks Question

User: "What's the total revenue in my sales file?"

Agent workflow:

1. Run: excel-workflow query "what is total revenue?" --file sales.xlsx
2. Receive data with all rows and formulas
3. Analyze the data to find revenue-related columns and totals
4. Respond with answer:

Agent: "Looking at your sales.xlsx file:

Total Revenue: 650,000 руб

Breakdown:
- iPhone: 150,000 (3 × 50,000)
- MacBook: 200,000 (2 × 100,000)
- iPad: 300,000 (5 × 60,000)

The file has a SUM formula in cell D5 that calculates this automatically."

Pattern 3: User Requests Update

User: "Change iPhone quantity to 20"

Agent workflow:

1. Query to understand structure: excel-workflow query "find iPhone row"
2. Identify that iPhone is in row 2, quantity in column C
3. Run: excel-workflow update '{"C2": 20}' --file sales.xlsx
4. Confirm update:

Agent: "✅ Updated sales.xlsx:

Changed C2 (iPhone quantity): 3 → 20

New revenue for iPhone: 1,000,000 руб (was 150,000)
Total revenue updated automatically thanks to formulas!

File has been re-uploaded to Google Drive."

Pattern 4: Mass Formula Creation

User: "Create a column that multiplies price by 0.5 for all products"

Agent workflow:

1. Read file to determine row count
2. Generate update JSON with formulas for each row
3. Run: excel-workflow update '{"D2": "=B2*0.5", "D3": "=B3*0.5", ...}' --file prices.xlsx
4. Confirm:

Agent: "✅ Created formulas for 50 rows!

Column D now contains =B*0.5 formula for all products.
File updated on Google Drive."

Technical Details

Components

1. Excel CLI — openpyxl-based tool for reading/writing Excel files

   • Preserves formulas using data_only=False
   • Commands: read, update, info, show-formulas, get-cell

2. Tracker — SQLite database for file metadata

   • Location: ~/.openclaw/excel_tracker.db
   • Tracks: filename, sheets, formulas, paths, timestamps

3. Workflow Orchestrator — Integrates Excel CLI, rclone, and tracker

   • Orchestrates: analyze → upload → track → update cycle
   • Progress messages to stderr, JSON results to stdout

File Locations

• Tracker database: ~/.openclaw/excel_tracker.db
• Google Drive folder: gdrive:Excel/
• Local files: User-specified paths (Telegram downloads to ~/.openclaw/media/)

Formula Preservation

How it works:

• openpyxl loads workbooks with data_only=False
• Formulas stored as text strings (e.g., "=B2*C2")
• When updating cell with formula string, openpyxl preserves it
• Excel recalculates formulas when file is opened

Example:

# This preserves formulas
ws['D2'] = '=B2*C2'  # Formula remains
ws['B2'] = 100       # Data changes, formula in D2 recalculates

What's Preserved vs Not Preserved

✅ Preserved:

• Formulas (=SUM, =IF, =B2*C2, etc.)
• Data (numbers, text, dates)
• Structure (sheets, tables)
• Formatting (colors, fonts, borders, bold)
• Charts (diagrams update automatically)

⚠️ May Not Work:

• Conditional formatting (complex rules)
• Macros (.xlsm files not supported)
• Pivot tables (may break)
• Slicers and advanced filters

Error Handling

Common errors:

1. File not found

   {"error": "File not found: /path/to/file.xlsx"}
   

2. Google Drive not configured

   {"error": "rclone remote 'gdrive' not configured"}
   

   Solution: Run rclone config

3. Formula syntax error

   {"error": "Invalid formula: =B2*"}
   

   Solution: Check formula syntax

4. Database locked

   {"error": "Database is locked"}
   

   Solution: Wait and retry

Examples

Example 1: Financial Data Analysis

# Upload stock data
excel-workflow process ~/Desktop/ARKK.xlsx

# Query
excel-workflow query "show last 10 rows" --file ARKK.xlsx

# Add calculated column (50% of price)
# First, find row count, then generate formulas
excel-workflow update '{"C2": "=B2*0.5", "C3": "=B3*0.5", ...}' --file ARKK.xlsx

Example 2: Price List Update

# Process price list
excel-workflow process prices.xlsx

# Update prices
excel-workflow update '{"B10": 99.99, "B11": 149.99}' --file prices.xlsx

# Add tax column
excel-workflow update '{"D2": "=B2*1.2"}' --file prices.xlsx

Example 3: Multiple Files

# Upload multiple files
excel-workflow process january.xlsx
excel-workflow process february.xlsx

# List all files
excel-workflow list

# Query specific file
excel-workflow query "total sales" --file january.xlsx

# Stats
excel-workflow stats

Troubleshooting

Issue: "rclone not found"

# Install rclone
brew install rclone  # macOS
sudo apt install rclone  # Linux

Issue: "openpyxl not installed"

# Install in virtual environment
cd ~/.openclaw/tools/openclaw-excel
python3 -m venv venv
./venv/bin/pip install openpyxl

Issue: "Google Drive permission denied"

# Reconfigure rclone
rclone config
# Delete old gdrive remote and create new one

Issue: "Formulas become values"

This should NOT happen! If it does:

1. Check that excel CLI uses data_only=False when loading workbook
2. Ensure formula strings start with =
3. Verify openpyxl version: pip show openpyxl (should be 3.1.0+)

Best Practices

For Users

1. Name files descriptively

   • Good: sales_2026_Q1.xlsx
   • Bad: Book1.xlsx

2. Ask specific questions

   • Good: "What's the total revenue in January?"
   • Bad: "Tell me about the file"

3. Keep file structure consistent

   • Makes it easier for AI to understand

For Developers

1. Always check file existence before processing
2. Use sessions for multiple operations on same file
3. Handle errors gracefully with try/except
4. Show progress in stderr, results in stdout
5. Validate formulas before updating cells

API Reference

See Excel CLI Documentation and Tracker Documentation for detailed API reference.

Resources

• openpyxl Documentation
• rclone Documentation
• Microsoft Excel File Format
• Google Drive with rclone

Support

• GitHub Issues: [your-repo/excel-workflow/issues]
• Documentation: [your-repo/excel-workflow/docs]
• Community: [OpenClaw Community]

License

MIT License - see LICENSE.txt

Changelog

Version 1.0.0 (2026-02-20)

• Initial release
• Formula preservation with openpyxl
• Google Drive sync via rclone
• SQLite tracking
• Multi-file support
• Mass formula operations
• AI agent integration patterns