Microsoft Excel 365 ExecModule

Overview

MicrosoftExcelModule connects ValkyrAI workflows to Excel workbooks stored in the authenticated user's OneDrive through the fixed Microsoft Graph v1.0 API. Its 15 operations cover workbook discovery, workbook sessions, worksheet lifecycle, range reads and writes, table lifecycle, and table rows. The connector uses ValkyrAI's native map I/O ExecModule ABI and keeps the delegated OAuth access token inside one READY IntegrationAccount.

The module accepts only drive-item IDs and bounded Excel identifiers; callers cannot choose a host or inject credentials. Requests are capped at 1 MiB, responses at 5 MiB, cell matrices at 10,000 scalar cells, and list pages at 1,000 items. Only GET operations retry transient failures. Session, worksheet, range, table, and row writes are single-attempt because a timeout can leave the workbook changed even when no response reaches ValkyrAI.

The official n8n Microsoft Excel 365 connector informed the functional surface: workbook listing, worksheet append/update/clear, table creation and row operations. ValkyrAI adds fixed routing, encrypted IntegrationAccount credentials, matrix and response bounds, explicit delete confirmation, session isolation, safe retry rules, and normalized errors.

Usage

1. Register or select a Microsoft Entra application for delegated Microsoft Graph access.
2. Grant the least-privilege Files.Read or Files.ReadWrite delegated scope needed by the workflow.
3. Put the current OAuth bearer token in the encrypted apiKey or password field of an IntegrationAccount and set the account to READY.
4. Bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use list_workbooks to discover .xlsx drive items, then pass a returned id as workbookId.
6. For repeated calls, create a persistent workbook session and pass its id as sessionId; close it after the bounded unit of work.
7. When a list result sets hasMore, pass nextCursor unchanged to the next execution.

Microsoft Graph Excel APIs operate on Office Open XML .xlsx workbooks stored in OneDrive or a Graph-accessible drive. The initial module deliberately fixes routing to /me/drive; SharePoint site drives, group drives, arbitrary raw Graph requests, and application-only access are deferred.

Inputs

Name	Type	Required	Description	Constraints
operation	string	Yes	One of the 15 operations below.	Exact allowlist.
workbookId	string	Except list_workbooks	OneDrive drive-item ID for the .xlsx workbook.	1–2,048 characters; no control characters.
worksheetId	string	Worksheet/range/table operations	Worksheet ID or name.	1–2,048 characters; no control characters.
tableId	string	Table row/delete operations	Table ID or name.	1–2,048 characters; no control characters.
rangeAddress	string	Range operations and add_table	A1 range such as A1:D20.	1–512 characters; external-workbook brackets and control characters rejected.
worksheetName	string	add_worksheet	New worksheet name.	1–128 characters.
values	array	add_table_rows; default update_range payload	Two-dimensional scalar matrix.	Rectangular, non-empty, at most 10,000 cells; strings at most 32,767 characters.
payload	object	Optional update_range form	Range fields to patch.	Up to five allowlisted fields: values, formulas, formulasLocal, formulasR1C1, numberFormat.
sessionId	string	close_session; optional otherwise	Graph workbook session.	1–4,096 characters; sent only as Workbook-Session-Id.
persistChanges	boolean	No	Whether create_session changes persist.	Default true.
hasHeaders	boolean	No	Whether add_table source includes header cells.	Default true.
rowIndex	integer	No	Table-row insertion index.	-1 appends; otherwise 0–1,000,000.
clearApplyTo	enum	No	Range portions cleared by clear_range.	All, Formats, or Contents; default Contents.
searchQuery	string	No	OneDrive search text for list_workbooks.	1–256 characters; default .xlsx; results are still filtered to Excel workbooks.
cursor	string	No	Module-issued continuation.	token: or skip: form returned as nextCursor.
limit	integer	No	Provider page size.	1–1,000; default 100.
confirmDelete	boolean	Delete operations	Destructive acknowledgement.	Must be true for delete_worksheet and delete_table.

Cell matrices accept strings, numbers, booleans, and null. Nested arrays or objects in a cell, ragged rows, credential-like payload keys, and more than 10,000 cells are rejected before transport.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
resource	string	After validation	workbooks, sessions, worksheets, ranges, tables, or rows.
data	object	Single-resource or accepted no-content success	Bounded Graph response or {accepted:true}.
id	string	Graph supplies one	Workbook, session, worksheet, or table identifier.
values, rowCount	array, integer	Range response includes values	Returned matrix and top-level row count.
items	array	List success	One bounded Graph value page.
count	integer	List success	Returned items after .xlsx filtering for workbook discovery.
hasMore	boolean	List success	Whether a supported continuation exists.
nextCursor	string	Another page exists	Opaque token: or skip: continuation.
httpStatus	integer	Provider success	Graph response status.
attempts	integer	Provider call or error	HTTP attempts consumed.
error	object	Failure	Redacted code, message, and retryable.

Workbook outputs are classified restricted. Tokens, authorization headers, workbook contents, and provider response bodies are never copied into progress logs.

IntegrationAccount Requirements

Setting	Requirement
Provider	Microsoft Graph Excel API v1.0
Authentication	Delegated OAuth 2.0 bearer token in encrypted apiKey or password
Status	Exactly READY
Permission	Files.Read for reads; Files.ReadWrite for session and workbook mutations
Relationship	ExecModuleConfig.authConfig.integrationAccount

Microsoft documents delegated Files.ReadWrite as the least-privilege permission for Excel range and table changes. Several Excel endpoints do not support application permissions, so this release intentionally uses the authenticated user's /me/drive. Token acquisition, refresh, conditional-access policy, tenant consent, and OneDrive sharing remain integration-layer responsibilities.

Configuration

Illustrative persisted configuration:

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:microsoft-excel-revenue-ops"
  },
  "executionConfig": {
    "timeoutMs": 30000
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_table_rows\",\"workbookId\":\"01ABC...\",\"worksheetId\":\"Pipeline\",\"tableId\":\"Revenue\",\"limit\":100}"
  }
}

The relationship is symbolic. The generated IntegrationAccount owns the encrypted bearer token; never persist a token in payload, values, workbook cells, WorkflowState, or logs.

Operations

Operation	Graph route	Behavior
list_workbooks	GET /me/drive/root/search(q='{query}')	Searches recursively and returns only .xlsx drive items.
get_workbook	GET /me/drive/items/{workbookId}	Reads one drive item and verifies the returned ID.
create_session	POST /me/drive/items/{workbookId}/workbook/createSession	Creates a persistent or non-persistent workbook session.
close_session	POST /me/drive/items/{workbookId}/workbook/closeSession	Closes the supplied session; no automatic retry.
list_worksheets	GET .../workbook/worksheets	Lists one bounded worksheet page.
add_worksheet	POST .../workbook/worksheets/add	Adds one named worksheet.
delete_worksheet	DELETE .../workbook/worksheets/{worksheetId}	Permanently deletes one worksheet after confirmation.
get_range	GET .../worksheets/{worksheetId}/range(address='{A1}')	Reads one bounded range response.
update_range	PATCH .../worksheets/{worksheetId}/range(address='{A1}')	Updates allowlisted values, formulas, or number format once.
clear_range	POST .../worksheets/{worksheetId}/range(address='{A1}')/clear	Clears contents, formats, or all range state once.
list_tables	GET .../worksheets/{worksheetId}/tables	Lists worksheet tables.
add_table	POST .../worksheets/{worksheetId}/tables/add	Converts a bounded source range into a table.
delete_table	DELETE .../worksheets/{worksheetId}/tables/{tableId}	Deletes the table definition and requires confirmation.
list_table_rows	GET .../worksheets/{worksheetId}/tables/{tableId}/rows	Lists one bounded row page.
add_table_rows	POST .../worksheets/{worksheetId}/tables/{tableId}/rows/add	Appends or inserts a bounded matrix once.

All workbook routes after workbookId may receive Workbook-Session-Id when sessionId is supplied. Callers should reuse a persistent session for a short coherent batch and close it explicitly.

Errors and Failure Modes

Failure	Cause	Recovery
VALIDATION_ERROR	Missing/invalid ID, range, session, matrix, cursor, payload, enum, bound, or confirmation.	Correct the request; validation failures send no provider call.
UNSUPPORTED_OPERATION	Unknown operation.	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No secure account is bound.	Bind the intended Microsoft Excel account.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	Repair consent/token state before executing.
MICROSOFT_GRAPH_HTTP_400/404	Graph rejected an ID, workbook type, range, table, or session.	Read current workbook metadata and correct the resource.
MICROSOFT_GRAPH_HTTP_401/403	Token expired, consent is missing, or Files permission is insufficient.	Refresh the account and grant only the required delegated permission.
MICROSOFT_GRAPH_HTTP_409/423	Workbook conflict, lock, or concurrent edit.	Close stale sessions and intentionally reconcile workbook state.
MICROSOFT_GRAPH_HTTP_429	Graph or Excel service throttling.	Reads honor bounded Retry-After; writes remain single-attempt.
MICROSOFT_GRAPH_HTTP_5xx / NETWORK_ERROR	Provider or transport failure.	GET retries up to three attempts. Reconcile session/workbook state before repeating a write.
RESPONSE_TOO_LARGE	Response exceeded 5 MiB.	Narrow the range, lower limit, or split the operation.
Unsupported continuation	Graph next link lacks $skiptoken or numeric $skip.	Narrow the query and report provider compatibility evidence.

Provider error text is bounded to 500 characters, has the exact token removed, and passes through ValkyrAI's sensitive-data redactor. A timeout after a write is ambiguous; the connector never assumes the workbook was unchanged.

Example

Append one approved pipeline row to an existing Excel table:

{
  "operation": "add_table_rows",
  "workbookId": "01ABCDEF23456789",
  "worksheetId": "Pipeline",
  "tableId": "Revenue",
  "rowIndex": -1,
  "sessionId": "workbook-session-123",
  "values": [
    ["Acme Manufacturing", "Dana Rivera", "qualified", 42000, "2026-08-14"]
  ]
}

Expected normalized result:

{
  "status": "success",
  "operation": "add_table_rows",
  "resource": "rows",
  "data": {
    "index": 42,
    "values": [
      ["Acme Manufacturing", "Dana Rivera", "qualified", 42000, "2026-08-14"]
    ]
  },
  "httpStatus": 201,
  "attempts": 1
}

Notes

• Pagination: each execution returns one Graph page. Reuse nextCursor exactly; the module never follows an arbitrary URL or silently exhausts a drive.
• Rate limits: Graph and Excel throttle by tenant, user, workbook, and operation. Numeric Retry-After is bounded to five seconds per safe-read attempt; writes remain single-attempt.
• API limits: the module caps pages at 1,000 items, request JSON at 1 MiB, response JSON at 5 MiB, and matrices at 10,000 scalar cells. Microsoft can impose tighter workbook and request limits.
• Idempotency: only GET is automatically retried. Session create/close, worksheet add/delete, range update/clear, table add/delete, and row append can complete ambiguously. Re-read the workbook before repeating them.
• Sessions: persistent sessions improve performance and save changes. Non-persistent sessions isolate calculations but lose changes when the session expires. Close sessions after a bounded unit of work.
• Destructive behavior: worksheet deletion and table deletion require confirmDelete=true. clear_range is also destructive but remains directly selectable because its target range and clear mode are explicit.
• Formulas: Graph can evaluate formulas supplied through update_range. Treat untrusted formulas as active content, constrain workbook permissions, and sanitize later CSV/export consumers against formula injection.
• Workbook types: Microsoft Graph Excel APIs support Office Open XML workbooks. Legacy .xls, password-protected, unsupported, corrupt, or externally linked workbooks may fail at the provider.
• Security: delegated tokens stay in IntegrationAccount SecureFields. The connector fixes the origin to Microsoft Graph and rejects credential-like payload keys recursively.
• Privacy: spreadsheets often contain customer, workforce, and revenue data. Apply downstream minimization, ACL, retention, and audit rules.
• External verification: deterministic tests cover Graph routing, bearer authentication, sessions, worksheet/range/table/row payloads, bounds, pagination, read retry, write non-retry, destructive guards, redaction, identity checks, and metadata discovery. Live Microsoft 365 execution is deferred until a separately authorized account is supplied.
• Deferred operations: workbook creation/deletion, file upload/download, SharePoint and group drives, application permissions, charts, pivot tables, named items, comments, formatting beyond numberFormat, sort/filter, functions, calculated values, subscriptions, delta queries, password protection, and automatic token refresh.
• Functional reference: n8n's Microsoft Excel 365 node includes workbook discovery, sheet append/update/clear, and table creation and row workflows. This module carries those composable semantics into ValkyrAI's secure native ABI with stricter transport, credential, mutation, and output contracts.

See Microsoft's Excel Graph overview, worksheet range API, workbook session API, and the official n8n Microsoft Excel 365 integration for upstream behavior and current provider limits.