Microsoft Excel Node (Syncaut)

The Excel Node lets you read, write, and manage Excel files stored in Microsoft OneDrive using Microsoft Graph.

It supports automation workflows like:

• Reading spreadsheet data

• Appending rows (e.g. orders, logs)

• Updating ranges

• Managing sheets and tables

Overview

FeatureDescriptionAuthMicrosoft OAuth (OneDrive access)Data SourceExcel files in OneDriveExecutionServer-side via Microsoft Graph APITemplatingHandlebars ({{variable}})OutputJSON ({{stepName.values}})

Authentication

To use the Excel node:

1. Click “Connect Microsoft”

2. Sign in via Microsoft OAuth

3. Grant access to OneDrive files

4. Refresh and reopen the dialog

Once connected, credentials are stored and reused.

Node Configuration

The Excel node is configured in 3 steps:

Connect

Fields

• Step name

  • Used to reference output later

  • Must be a valid variable name

  • Example:

    readOrders

• Microsoft Account

  • Select connected account

• Excel File

  • Browse OneDrive files

  • Select .xlsx file

• Sheet Name (optional)

  • Defaults to first sheet if empty

  • Supports variables:

    {{sheetName}}

Action

Choose what operation to perform.

📂 Range Actions

ActionDescriptionget_rangeRead a specific rangeget_used_rangeRead all used cellsupdate_rangeUpdate values in rangeclear_rangeClear values

Row Actions

ActionDescriptionappend_rowAdd new rowinsert_rowsInsert rows at positiondelete_rowsRemove rows

Table Actions

ActionDescriptionget_tablesList all tablesget_table_rowsFetch table dataadd_table_rowInsert rowupdate_table_rowUpdate rowdelete_table_rowDelete row

Sheet Actions

ActionDescriptionget_sheetsList sheetscreate_sheetCreate new sheetdelete_sheetDelete sheet

Parameters

Two modes:

🟢 Form Mode (Recommended)

• Structured UI inputs

• Auto-generates JSON payload

🔵 JSON Mode (Advanced)

• Direct control of request payload

• Supports dynamic expressions

Variables & Templating

Syncaut uses Handlebars for dynamic values.

Example

{
  "values": [
    ["{{orderId}}", "{{customerName}}", "{{total}}"]
  ]
}

Built-in Helper

{{json someObject}}

Payload Examples

Get Range

{
  "range": "Sheet1!A1:D10"
}

Update Range

{
  "range": "A1:C3",
  "values": [
    ["Name", "Price"],
    ["Product A", "9.99"]
  ]
}

Append Row

{
  "values": [
    ["{{orderId}}", "{{customerName}}", "{{total}}"]
  ]
}

Insert Rows

{
  "row": 5,
  "count": 2
}

Delete Rows

{
  "row": 3,
  "count": 1
}

Table Row

{
  "tableId": "Table1",
  "values": [
    ["{{productId}}", "{{quantity}}"]
  ]
}

Create Sheet

{
  "name": "{{sheetName}}"
}

Output

Each step outputs structured data:

{{stepName.values}}

Example

If step name = readSheet:

{{readSheet.values}}

Execution Flow (Under the Hood)

Your executor does:

1. Resolve Variables

• Handlebars renders payload

• HTML entities decoded

2. Secure Credentials

• Credentials decrypted before use

3. API Call

• Uses ky to call Microsoft Graph

• Routed via:

  excelChannel

4. Response Handling

• Returns normalized JSON

• Stored in workflow context

Security

• Credentials are encrypted at rest

• Decrypted only during execution

• OAuth tokens never exposed to client

Error Handling

Non-retriable errors

Thrown when:

• Invalid payload

• Missing required params

• Unauthorized access

throw new NonRetriableError("Invalid Excel payload");

Best Practices

✅ Use variables for dynamic workflows

["{{orderId}}", "{{total}}"]

✅ Prefer Form mode unless needed

• Safer

• Prevents malformed JSON

✅ Keep step names clean

good: readOrders
bad: read-orders!

✅ Use get_used_range when unsure

• Automatically detects data

Limitations

• Works only with OneDrive-hosted Excel files

• No support for:

  • Local uploads

  • Google Sheets (separate integration)

• Table operations require existing tables

Example Workflow

Use Case: Log new orders

1. Trigger → New order

2. Excel Node:

   • Action: append_row

   • Payload:

     {
       "values": [
         ["{{orderId}}", "{{customerName}}", "{{total}}"]
       ]
     }

3. Output stored for next steps

Developer Notes (Your System)

• UI builds payload via:

  buildPayload(action, fieldValues)

• Executor:

  • Parses payload

  • Applies Handlebars

  • Sends request via excelChannel

• Supports:

  • Smart number parsing

  • JSON auto-parsing

  • Variable interpolation inside arrays