Microsoft OneDrive ExecModule

Overview

MicrosoftOneDriveModule connects ValkyrAI workflows to Microsoft OneDrive through the fixed Microsoft Graph v1.0 API. Its eight operations cover drive discovery, bounded folder listing, metadata reads, bounded downloads, small-file uploads, folder creation, metadata updates, and guarded trashing. The module follows ValkyrAI's native map I/O ExecModule ABI and keeps the OAuth token inside one READY IntegrationAccount.

The module builds only https://graph.microsoft.com/v1.0 production requests, treats drive and driveItem identifiers as opaque values, limits uploads and downloads to 5 MiB, exposes one provider page per execution, retries transient failures only for GET, and never automatically retries a write. It uses Microsoft Graph's ID and path addressing instead of accepting arbitrary URLs.

The official n8n Microsoft OneDrive node informed the high-value file and folder resource selection. This ValkyrAI implementation adds native IntegrationAccount handling, bounded bodies, a strict update allowlist, destructive confirmation, optional ETag concurrency, immutable-identity checks, and credential-safe failures.

Usage

1. Register or select a Microsoft Entra application for delegated or application access.
2. Grant only the OneDrive permissions needed by the selected operations.
3. Store the OAuth access token in the encrypted apiKey or password field of a ValkyrAI IntegrationAccount and set its status to READY.
4. Bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Use driveId: "me" for the signed-in user's default drive, or provide an opaque drive ID.
6. Choose one operation and provide only its conditional inputs.
7. When hasMore is true, pass nextCursor unchanged into the next execution.

Inputs

Name	Type	Required	Description	Constraints
operation	string	Yes	One of the eight operations below.	Exact allowlist.
driveId	string	No	Target drive.	me or an opaque ID; default me.
itemId	string	Conditional	Target driveItem ID.	Opaque, non-empty, no slashes/control characters, at most 2,048 characters.
parentId	string	No	Parent item for list/create/upload.	Opaque ID or root; default root.
name	string	Conditional	File or folder name.	1–255 characters; rejects Graph-invalid path characters.
contentBase64	string	Conditional	File bytes for upload_file.	Valid Base64; decoded content at most 5 MiB.
payload	object	Conditional	Metadata for update_item.	Non-empty; only name, description, parentReference, and fileSystemInfo; at most 64 KiB.
conflictBehavior	string	No	Naming conflict policy.	fail, rename, or replace; default fail.
confirmTrash	boolean	Conditional	Destructive guard.	Must be true for trash_item.
etag	string	No	Optimistic concurrency value.	Sent as If-Match for update/trash only.
select	string	No	Response projection for listing.	Up to 40 comma-separated Graph field names.
cursor	string	No	Module-issued continuation.	token: value returned as nextCursor; at most 4,096 characters.
limit	integer	No	Graph page size.	1–200; default 100.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
data	object	Metadata/write success	Bounded driveItem or trash receipt.
id	string	driveItem success	Provider-returned driveItem ID.
items	array	List success	One bounded page of driveItems.
count	integer	List success	Number of items returned.
hasMore	boolean	List success	Whether Graph returned a supported continuation.
nextCursor	string	When another page exists	Opaque continuation for the next call.
contentBase64	string	Download success	Bounded downloaded bytes encoded as Base64.
size	integer	Download success	Downloaded byte count.
httpStatus	integer	Provider success	Microsoft Graph status code.
attempts	integer	Provider call or error	HTTP attempts consumed.
error	object	Failure	Redacted code, message, and retryable.

Outputs are classified restricted. Tokens, provider bodies, file content, and driveItem names are never written into progress logs.

IntegrationAccount Requirements

Setting	Requirement
Provider	Microsoft Graph OneDrive API v1.0
Authentication	OAuth 2.0 bearer access token in encrypted apiKey or password
Status	Exactly READY
Relationship	ExecModuleConfig.authConfig.integrationAccount

Use Files.Read for read-only delegated workflows, Files.ReadWrite for delegated writes, and only the corresponding .All application permissions when tenant-wide access is intentionally required and administrator-approved. Token acquisition, refresh, tenant consent, and application access policies remain outside this module.

Configuration

Illustrative persisted configuration:

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:microsoft-onedrive-operations"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_children\",\"driveId\":\"me\",\"parentId\":\"root\",\"select\":\"id,name,size,lastModifiedDateTime\",\"limit\":100}"
  }
}

The relationship is symbolic. The generated IntegrationAccount owns the encrypted token; never persist it in inputs, workflow state, examples, or logs.

Operations

Operation	Graph route	Behavior
get_drive	GET /me/drive or /drives/{driveId}	Reads default or selected drive metadata.
list_children	GET /.../root/children or /.../items/{parentId}/children	Returns one bounded page plus an opaque continuation.
get_item	GET /.../items/{itemId}	Reads one driveItem and verifies a returned ID when present.
download_file	GET /.../items/{itemId}/content	Follows Graph's content redirect through the HTTP client and returns at most 5 MiB as Base64.
upload_file	PUT /.../{parent}:/{name}:/content	Uploads at most 5 MiB once with an explicit conflict policy.
create_folder	POST /.../{parent}/children	Creates one folder once with an explicit conflict policy.
update_item	PATCH /.../items/{itemId}	Updates only allowlisted metadata, optionally using If-Match.
trash_item	DELETE /.../items/{itemId}	Moves one item to the recycle bin only when confirmTrash=true.

Errors and Failure Modes

Failure	Cause	Recovery
VALIDATION_ERROR	Missing/invalid identifier, unsafe name, invalid Base64, oversized body, unsupported payload field/cursor, mismatched identity, or absent trash confirmation.	Correct the request; local validation sends no provider call.
INTEGRATION_ACCOUNT_REQUIRED	No secure account is bound.	Bind the intended OneDrive account.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	Repair consent or token state before execution.
MICROSOFT_GRAPH_HTTP_400/404	Graph rejected a route, item, projection, or payload.	Correct the provider resource or request.
MICROSOFT_GRAPH_HTTP_401/403	Token expired, consent is missing, or permissions are insufficient.	Refresh the account and grant only the required permission.
MICROSOFT_GRAPH_HTTP_409/412	Naming conflict or stale ETag.	Read the parent/item and intentionally reconcile.
MICROSOFT_GRAPH_HTTP_429	Microsoft Graph throttled the call.	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 OneDrive state before manually retrying a write.
RESPONSE_TOO_LARGE	Response or download exceeded 5 MiB.	Narrow the listing or use an external large-file transfer workflow.

Provider error messages are limited to 500 characters, have the exact OAuth token removed, and pass through ValkyrAI's sensitive-data redactor. A timeout after a write is ambiguous; the module never assumes it failed.

Example

Create one governed customer folder:

{
  "operation": "create_folder",
  "driveId": "me",
  "parentId": "root",
  "name": "Customer Deliverables",
  "conflictBehavior": "rename"
}

Expected normalized result:

{
  "status": "success",
  "operation": "create_folder",
  "id": "opaque-drive-item-id",
  "httpStatus": 201,
  "attempts": 1
}

Notes

• Pagination: each execution returns one Graph page. Reuse nextCursor exactly; the module never follows arbitrary continuation URLs.
• Rate limits: GET requests can make up to three attempts for transient statuses. A numeric Retry-After is capped at five seconds per attempt.
• Idempotency: upload, folder creation, metadata updates, and trashing are single-attempt. Reconcile by driveItem ID or an explicit parent listing before any manual retry.
• Destructive behavior: Graph DELETE moves supported items to the recycle bin, but it still requires confirmTrash=true because retention and restore behavior depend on account policy.
• Bounds: list pages are capped at 200 items; update JSON at 64 KiB; uploads, downloads, and provider bodies at 5 MiB; names at 255 characters.
• Deferred operations: large resumable uploads, copy/move monitors, sharing permissions, versions, search, delta queries, previews, thumbnails, webhooks, restore/permanent delete, and automatic token refresh remain explicit future work.
• External verification: deterministic tests cover Graph routing, bearer authentication, opaque pagination, upload bytes, folder/update payloads, ETags, download bytes, safe-read retry, write non-retry, destructive confirmation, redaction, response identity, and metadata discovery. Live OneDrive execution is deferred until a separately authorized Microsoft account is supplied.

See Microsoft's driveItem resource reference, list children API, small-file upload API, create folder API, throttling guidance, and the official n8n Microsoft OneDrive node for upstream behavior and current provider limits.