-
Notifications
You must be signed in to change notification settings - Fork 35
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
96c2d5e
commit f6baefa
Showing
5 changed files
with
329 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
141 changes: 141 additions & 0 deletions
141
docs/demonstration-add-new-orders-to-goole-sheet/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| # Demonstration: Add new orders to a Google Sheet | ||
|
|
||
| Tags: Demonstration, Files, Google Sheets, Orders, Spreadsheets | ||
|
|
||
| # Order Tracking with Google Sheets (Demonstration) | ||
|
|
||
| * View in the task library: [tasks.mechanic.dev/demonstration-add-new-orders-to-goole-sheet](https://tasks.mechanic.dev/demonstration-add-new-orders-to-goole-sheet) | ||
| * Task JSON, for direct import: [task.json](../../tasks/demonstration-add-new-orders-to-goole-sheet.json) | ||
| * Preview task code: [script.liquid](./script.liquid) | ||
|
|
||
| ## Default options | ||
|
|
||
| ```json | ||
| { | ||
| "google_account__required": "matt@lightward.com", | ||
| "spreadsheet_title__required": "Better order tracking spreadsheet", | ||
| "spreadsheet_id": "", | ||
| "email_address_for_export__email": "matt@lightward.com", | ||
| "file_format_for_export": "pdf", | ||
| "create_sheet_mode__boolean": true, | ||
| "export_sheet_mode__boolean": false | ||
| } | ||
| ``` | ||
|
|
||
| [Learn about task options in Mechanic](https://learn.mechanic.dev/core/tasks/options) | ||
|
|
||
| ## Subscriptions | ||
|
|
||
| ```liquid | ||
| mechanic/user/trigger | ||
| shopify/orders/create | ||
| mechanic/actions/perform | ||
| ``` | ||
|
|
||
| [Learn about event subscriptions in Mechanic](https://learn.mechanic.dev/core/tasks/subscriptions) | ||
|
|
||
| ## Documentation | ||
|
|
||
| # Order Tracking with Google Sheets (Demonstration) | ||
|
|
||
| This demonstration task shows you how to use Mechanic's Google Sheets action to track orders. Use this as a learning tool and template for building your own Google Sheets automations! | ||
|
|
||
| ## What This Demo Shows | ||
|
|
||
| Learn how to: | ||
| - Create spreadsheets via the Google Sheets API | ||
| - Append data automatically | ||
| - Export spreadsheets in different formats | ||
| - Handle multiple operation modes | ||
| - Deliver files via email | ||
|
|
||
| ## Features | ||
|
|
||
| - 📊 Creates a spreadsheet with essential order columns | ||
| - ⚡ Automatically logs new orders as they come in | ||
| - 📥 Export options: XLSX, CSV, or PDF | ||
| - 📧 Email delivery of exports | ||
|
|
||
| ## What Gets Tracked | ||
|
|
||
| Each order entry includes: | ||
| - Order number | ||
| - Date and time | ||
| - Customer name | ||
| - Order total | ||
| - Line items (with quantities) | ||
| - Order status | ||
|
|
||
| ## Setup Guide | ||
|
|
||
| 1. **Connect Google Account** | ||
| - Go to Settings → Authentication | ||
| - Connect your Google account | ||
|
|
||
| 2. **Configure Options** | ||
| - Google account email | ||
| - Spreadsheet title | ||
| - Export email address (for downloads) | ||
| - File format preference (XLSX/CSV/PDF) | ||
|
|
||
| 3. **Create Your Spreadsheet** | ||
| - Enable "Create sheet mode" | ||
| - Run the task once | ||
| - Copy the `spreadsheet_id` from the results | ||
| - Paste it into the task options | ||
| - Save the task | ||
|
|
||
| 4. **Start Tracking** | ||
| - Disable "Create sheet mode" | ||
| - The task will now automatically track new orders | ||
|
|
||
| ## Exporting Data | ||
|
|
||
| Need a copy of your data? | ||
|
|
||
| 1. Enable "Export sheet mode" | ||
| 2. Choose your preferred format | ||
| 3. Verify your email address is set | ||
| 4. Run the task | ||
| 5. Check your email for the attachment | ||
|
|
||
| ## Requirements | ||
|
|
||
| - Google account connected to Mechanic | ||
| - Valid spreadsheet ID (after initial creation) | ||
|
|
||
| ## Common Issues | ||
|
|
||
| - **"Spreadsheet ID required"**: Run in create mode first | ||
| - **"Mode conflict"**: Only enable one mode at a time | ||
| - **"Cannot export"**: Make sure spreadsheet ID is configured | ||
| - **"Missing email"**: Add email address for exports | ||
|
|
||
| ## Tips | ||
|
|
||
| - Create a fresh spreadsheet? Re-enable create mode (delete old ID first) | ||
| - Need regular exports? Set up recurring task runs | ||
|
|
||
| ## Learning Points | ||
|
|
||
| This demonstration shows several key Google Sheets action features: | ||
| - Creating new spreadsheets with headers | ||
| - Appending rows of data | ||
| - Exporting in multiple formats | ||
| - Error handling | ||
| - Email delivery | ||
|
|
||
| Use this task as a reference when building your own Google Sheets automations. | ||
|
|
||
| ## Installing this task | ||
|
|
||
| Find this task [in the library at tasks.mechanic.dev](https://tasks.mechanic.dev/demonstration-add-new-orders-to-goole-sheet), and use the "Try this task" button. Or, import [this task's JSON export](../../tasks/demonstration-add-new-orders-to-goole-sheet.json) – see [Importing and exporting tasks](https://learn.mechanic.dev/core/tasks/import-and-export) to learn how imports work. | ||
|
|
||
| ## Contributions | ||
|
|
||
| Found a bug? Got an improvement to add? Start here: [../../CONTRIBUTING.md](../../CONTRIBUTING.md). | ||
|
|
||
| ## Task requests | ||
|
|
||
| Submit your [task requests](https://mechanic.canny.io/task-requests) for consideration by the Mechanic community, and they may be chosen for development and inclusion in the [task library](https://tasks.mechanic.dev/)! |
143 changes: 143 additions & 0 deletions
143
docs/demonstration-add-new-orders-to-goole-sheet/script.liquid
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| {% comment %} | ||
| Order Tracking with Google Sheets Integration | ||
| Features: | ||
| - Creates a spreadsheet with order tracking columns | ||
| - Automatically logs new orders | ||
| - Exports to XLSX, CSV, or PDF formats | ||
| - Email delivery | ||
| Setup: | ||
| 1. Connect Google account in Settings > Authentication | ||
| 2. Configure spreadsheet title | ||
| 3. Run task to create initial spreadsheet | ||
| 4. Copy spreadsheet_id from results | ||
| 5. Add spreadsheet_id to options | ||
| 6. Toggle between create mode and export mode as needed | ||
| Preferred option order: | ||
| {{ options.google_account__required }} | ||
| {{ options.spreadsheet_title__required }} | ||
| {{ options.spreadsheet_id }} | ||
| {{ options.email_address_for_export__email }} | ||
| {{ options.file_format_for_export }} | ||
| {{ options.create_sheet_mode__boolean }} | ||
| {{ options.export_sheet_mode__boolean }} | ||
| {% endcomment %} | ||
|
|
||
| {% assign order_headers = array %} | ||
| {% assign order_headers[0] = "Order Number" %} | ||
| {% assign order_headers[1] = "Date" %} | ||
| {% assign order_headers[2] = "Customer" %} | ||
| {% assign order_headers[3] = "Total" %} | ||
| {% assign order_headers[4] = "Items" %} | ||
| {% assign order_headers[5] = "Status" %} | ||
|
|
||
| {% if event.topic == "mechanic/user/trigger" %} | ||
| {% if options.create_sheet_mode__boolean and options.export_sheet_mode__boolean %} | ||
| {% error "Please enable only one mode: either 'Create sheet mode' or 'Export sheet mode', but not both." %} | ||
| {% elsif options.create_sheet_mode__boolean %} | ||
| {% if options.spreadsheet_id != blank %} | ||
| {% error "A spreadsheet ID is already configured. To proceed, either: 1) Uncheck 'Create sheet mode' to just track orders, or 2) Uncheck 'Create sheet mode' and enable 'Export sheet mode' to export the existing spreadsheet." %} | ||
| {% else %} | ||
| {% action "google_sheets" %} | ||
| { | ||
| "account": {{ options.google_account__required | json }}, | ||
| "operation": "create_spreadsheet", | ||
| "title": {{ options.spreadsheet_title__required | json }}, | ||
| "rows": [ | ||
| {{ order_headers | json }} | ||
| ] | ||
| } | ||
| {% endaction %} | ||
| {% endif %} | ||
| {% elsif options.export_sheet_mode__boolean %} | ||
| {% if options.spreadsheet_id == blank %} | ||
| {% error "Please configure the spreadsheet ID before exporting. First create a spreadsheet using 'Create sheet mode', then copy the spreadsheet ID to the task options." %} | ||
| {% elsif options.email_address_for_export__email == blank %} | ||
| {% error "Please provide an email address for export in the task options when using 'Export sheet mode'." %} | ||
| {% else %} | ||
| {% assign file_type = "xlsx" %} | ||
| {% assign export_format = options.file_format_for_export | default: "xlsx" | downcase %} | ||
| {% if export_format == "csv" %} | ||
| {% assign file_type = "csv" %} | ||
| {% elsif export_format == "pdf" %} | ||
| {% assign file_type = "pdf" %} | ||
| {% endif %} | ||
|
|
||
| {% action "google_sheets" %} | ||
| { | ||
| "account": {{ options.google_account__required | json }}, | ||
| "operation": "export_spreadsheet", | ||
| "spreadsheet_id": {{ options.spreadsheet_id | json }}, | ||
| "file_type": {{ file_type | json }} | ||
| } | ||
| {% endaction %} | ||
| {% endif %} | ||
| {% else %} | ||
| {% if options.spreadsheet_id != blank %} | ||
| {% assign message = "✓ Task is configured and actively tracking orders. To export the spreadsheet: 1) Enable 'Export sheet mode', 2) Save the task, then 3) Run the task manually." %} | ||
| {% assign url = "https://docs.google.com/spreadsheets/d/" | append: options.spreadsheet_id %} | ||
| {% log message: message, spreadsheet_url: url %} | ||
| {% else %} | ||
| {% log message: "Please select an action mode in task options: Enable 'Create sheet mode' to create a new spreadsheet, or enable 'Export sheet mode' to export an existing spreadsheet. After creating a spreadsheet, copy its ID to the 'Spreadsheet ID' option." %} | ||
| {% endif %} | ||
| {% endif %} | ||
| {% endif %} | ||
|
|
||
| {% if event.topic == "mechanic/actions/perform" %} | ||
| {% if action.type == "google_sheets" and action.run.ok and action.run.result.data_base64 != blank %} | ||
| {% assign file_extension = ".xlsx" %} | ||
| {% assign export_format = options.file_format_for_export | default: "xlsx" | downcase %} | ||
| {% if export_format == "csv" %} | ||
| {% assign file_extension = ".csv" %} | ||
| {% elsif export_format == "pdf" %} | ||
| {% assign file_extension = ".pdf" %} | ||
| {% endif %} | ||
|
|
||
| {% action "email" %} | ||
| { | ||
| "to": {{ options.email_address_for_export__email | json }}, | ||
| "subject": "Order Tracking Spreadsheet Export", | ||
| "body": "Please find attached the requested order tracking data.", | ||
| "attachments": { | ||
| {{ action.run.result.name | append: file_extension | json }}: { | ||
| "base64": {{ action.run.result.data_base64 | json }} | ||
| } | ||
| } | ||
| } | ||
| {% endaction %} | ||
| {% endif %} | ||
| {% endif %} | ||
|
|
||
| {% if event.topic == "shopify/orders/create" %} | ||
| {% if options.spreadsheet_id == blank %} | ||
| {% error "Please run this task manually first to create a spreadsheet, then add the spreadsheet_id to the task options." %} | ||
| {% endif %} | ||
|
|
||
| {% comment %}Format order data for spreadsheet{% endcomment %} | ||
| {% assign order_items = array %} | ||
| {% for item in order.line_items %} | ||
| {% assign item_str = item.quantity | append: "x " | append: item.title %} | ||
| {% assign order_items = order_items | push: item_str %} | ||
| {% endfor %} | ||
|
|
||
| {% assign order_row = array %} | ||
| {% assign order_row[0] = order.order_number %} | ||
| {% assign order_row[1] = order.created_at | date: "%Y-%m-%d %H:%M:%S" %} | ||
| {% assign order_row[2] = order.customer.first_name | append: " " | append: order.customer.last_name %} | ||
| {% assign order_row[3] = order.total_price %} | ||
| {% assign order_row[4] = order_items | join: ", " %} | ||
| {% assign order_row[5] = order.financial_status %} | ||
|
|
||
| {% action "google_sheets" %} | ||
| { | ||
| "account": {{ options.google_account__required | json }}, | ||
| "operation": "append_rows", | ||
| "spreadsheet_id": {{ options.spreadsheet_id | json }}, | ||
| "rows": [ | ||
| {{ order_row | json }} | ||
| ] | ||
| } | ||
| {% endaction %} | ||
| {% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -117,6 +117,7 @@ | |
| "Slack", | ||
| "Sort", | ||
| "Spend", | ||
| "Spreadsheets", | ||
| "Staff", | ||
| "Status", | ||
| "Storefront", | ||
|
|
||
Oops, something went wrong.