Skip to main content
Inserts or upserts rows in an .xlsx workbook stored in the connected user’s OneDrive (or a SharePoint document library reachable from it). Display name “OneDrive Excel Update”. For uploading or replacing whole files, see export_to_onedrive; for reading files in, see import_from_onedrive.

​
Authentication and enablement

  • Connector: OneDrive OAuth. The tool is only registered when OneDrive/SharePoint OAuth credentials are configured; access_token is injected from the workspace’s OneDrive integration (x-variable-service: onedrive, first_active) and is never chosen by the model.
  • Default state: off. Off by default — enable it in the agent’s Tools panel.
  • Not supported by Microsoft: workbooks on consumer OneDrive, and the legacy .xls format. Office Open XML (.xlsx) on a business tenant only.

​
Inputs

​
Outputs

rows_inserted and rows_updated are verified counts — the number of rows confirmed present after the write, not the number requested. warnings carries non-fatal data problems (see duplicate keys below).

​
How rows are written (and why it matters)

Excel over Microsoft Graph has no atomic append for a plain worksheet range, no If-Match/ETag at the workbook object layer, and no idempotency key. Microsoft’s own guidance is that concurrent writes to one workbook should not be attempted at all: “for each workbook, only send the next request after receiving a successful response to the current request.” The tool therefore:
  1. Serializes writes per (workbook, worksheet) using a cross-process Postgres advisory lock. Two agents (or two steps of the same agent) writing the same worksheet queue rather than collide. A writer waits up to 60s; past that the step fails with another write to worksheet '…' is still in progress and is safe to retry.
  2. Appends through an Excel table (POST /workbook/tables/{t}/rows/add with index: null) so Graph — not this tool — picks the row. All rows go in one request.
  3. Creates a table on first use if the worksheet has none, covering the worksheet’s existing used range with hasHeaders: true. This is a visible change to the customer’s file: the data region becomes an Excel Table. Filter buttons and banded rows are explicitly switched back off, but the table itself remains. If the worksheet already has several tables (e.g. an unrelated lookup range), the write targets the one whose header row carries the given columns; it refuses to guess when that is ambiguous and falls back to the range path.
  4. Verifies the write. On an ambiguous failure (5xx or timeout, where the row may or may not have landed) the tool reads the table back and reconciles instead of re-sending, because a blind retry would duplicate the row.

​
Fallback

Worksheets that cannot be represented as a table — merged cells, an unusable range, or a columns entry mapping beyond the table’s last column — fall back to writing an absolute range (PATCH /range(address='A41:R41')). This path still computes the target row, so it is correct only because the lock is held. It is otherwise equivalent.

​
Limits and side effects

  • Creates an Excel Table in the target worksheet on first write (see above).
  • upsert matching is case-insensitive and whitespace-trimmed on the key column.
  • upsert replaces the whole matched row in one request, carrying over columns not named in columns.
  • Row width on the table path must match the table exactly; wider writes take the fallback path.
  • Throttling: Graph publishes only app-level Excel limits (5,000 req/10s per app, 1,500 per tenant) and treats per-workbook cost as resource-based. 429/Retry-After is honoured with backoff.

​
Expected errors

​
Audit

Outbound Microsoft Graph calls are audited (host only — paths and query strings are not logged).