Microsoft SharePoint ExecModule

Overview

MicrosoftSharePointModule connects ValkyrAI workflows to SharePoint through Microsoft Graph v1.0 and the native map I/O ExecModule ABI. Workflow Studio discovers the module as MicrosoftSharePointModule.

The connector covers site discovery, list and list-item reads and writes, document-library discovery, drive-item reads, child listing, and folder creation. Production traffic is fixed to https://graph.microsoft.com/v1.0. OAuth credentials resolve only from encrypted fields on a bound IntegrationAccount.

The implementation uses the n8n Microsoft SharePoint integration as a functional reference while following ValkyrAI security, metadata, execution, retry, and output contracts.

Usage

1. Register an application in Microsoft Entra ID or select an approved tenant application.
2. Grant the minimum delegated Microsoft Graph scopes required by the workflow.
3. Complete tenant consent when the selected scopes require administrator approval.
4. Store the resulting access token in a READY Microsoft SharePoint IntegrationAccount.
5. Discover a site with search_sites, then select explicit site, list, item, drive, and folder IDs.
6. Use mutation operations only after validating the target resource and expected business fields.
7. Reconcile Microsoft Graph state by immutable ID before manually repeating an ambiguous write.

Use SharePoint list internal field names in fields. Display names can differ from internal names, especially for renamed or custom columns.

Inputs

Input	Type	Used by	Required	Notes
operation	string	All	Yes	One supported operation from the table below.
siteId	string	Site-list operations	Operation-specific	Microsoft Graph composite site ID; bounded to 2,048 safe characters.
listId	string	List-item operations	Operation-specific	SharePoint list ID.
itemId	string	Item get/update/delete	Operation-specific	SharePoint list-item ID.
driveId	string	Drive operations	Operation-specific	Document-library drive ID.
driveItemId	string	Drive-item/child operations	Operation-specific	Omit for the drive root in child-list or folder-create operations.
searchQuery	string	Site search	Yes	Bounded site-search text, at most 200 characters.
fields	object	Item create/update	Yes	Non-empty field-value object, at most 256 KiB and eight nesting levels.
folderName	string	Folder create	Yes	Folder name, at most 255 characters.
conflictBehavior	string	Folder create	No	fail by default, or rename.
cursor	string	List operations	No	An opaque cursor returned by this module; arbitrary URLs are rejected.
limit	integer	List operations	No	1 through 1,000; defaults to 100.
confirmDelete	boolean	Item delete	Yes	Must be true before permanent list-item deletion.

The module rejects credential-like keys such as authorization, API keys, passwords, secrets, and token fields anywhere in a request body.

Outputs

Output	Type	When present	Meaning
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
resource	string	After request construction	sites, lists, items, fields, drives, or driveItems.
httpStatus	integer	Provider responded	Microsoft Graph status code.
attempts	integer	Always	Number of HTTP attempts consumed. Writes are always one attempt.
data	object	Single-resource success	Provider resource or an empty object after successful deletion.
id	string	Provider returned one	Convenience immutable resource ID.
webUrl	string	Provider returned one	Convenience SharePoint browser URL.
items	array	List success	Bounded Microsoft Graph value array.
count	integer	List success	Number of items in this page.
hasMore	boolean	List success	Whether Graph returned a supported continuation.
nextCursor	string	More results exist	Validated skip token or numeric skip, never a provider URL.
requestId	string	Provider supplied one	Microsoft request correlation value.
error	object	Failure	Stable code, safe message, optional HTTP status, and retryable flag.

IntegrationAccount Requirements

Requirement	Contract
Provider	Microsoft Graph / Microsoft SharePoint
Status	READY
Credential	OAuth access token in encrypted apiKey; encrypted password is a compatibility fallback
Read scopes	Sites.Read.All; add Files.Read.All for document-library operations
Write scopes	Sites.ReadWrite.All; add Files.ReadWrite.All for folder creation
Tenant consent	Required according to the Entra application and selected permissions

Use the least-privilege delegated scopes available. For higher-assurance deployments, prefer Microsoft selected-site permissions and grant access only to required sites. Rotate or revoke the IntegrationAccount when access is no longer needed.

The module does not accept client IDs, client secrets, refresh tokens, tenant IDs, or raw bearer tokens in workflow input.

Configuration

Minimal site discovery:

{
  "operation": "search_sites",
  "searchQuery": "Release Operations",
  "limit": 25
}

Minimal list-item creation:

{
  "operation": "create_item",
  "siteId": "contoso.sharepoint.com,abc123,def456",
  "listId": "f75b0e5d-41f8-40ac-bcab-8d22ca8ebc65",
  "fields": {
    "Title": "Verify public launch evidence",
    "ReleaseState": "Ready for review"
  }
}

The persisted workflow binds a generated IntegrationAccount relationship. Never place credentials in this JSON.

Operations

Operation	Microsoft Graph behavior	Side effect
search_sites	GET sites with search query	None
get_site	GET one site	None
list_lists	GET lists for a site	None
get_list	GET one list	None
list_items	GET list items with expanded fields	None
get_item	GET one list item with expanded fields	None
create_item	POST an item with a fields envelope	Creates a list item
update_item	PATCH only the item fields resource	Updates list fields
delete_item	DELETE one list item	Permanently deletes after explicit confirmation
list_drives	GET document-library drives for a site	None
get_drive_item	GET one drive item	None
list_children	GET root or item children	None
create_folder	POST a folder to root or item children	Creates a document-library folder

Arbitrary OData filters, arbitrary Graph paths, file-byte upload/download, sharing links, permissions, columns, content types, pages, webhooks, and list creation are intentionally deferred from version 1.0.0.

Errors and Failure Modes

Code	Cause	Retryable	Recovery
INTEGRATION_ACCOUNT_REQUIRED	No bound account	No	Bind a Microsoft SharePoint IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account is not READY	No	Complete OAuth authorization and validation.
VALIDATION_ERROR	Invalid ID, unsafe fields, cursor, body, or token	No	Correct the named field.
MICROSOFT_GRAPH_HTTP_400	Graph rejected the request or field name	No	Check IDs, internal column names, and types.
MICROSOFT_GRAPH_HTTP_401	Token expired or is invalid	No	Refresh or replace the credential.
MICROSOFT_GRAPH_HTTP_403	Scope, consent, or site access is missing	No	Grant only the required permissions.
MICROSOFT_GRAPH_HTTP_404	Resource is absent or hidden	No	Re-run discovery with the same account.
MICROSOFT_GRAPH_HTTP_409	Folder conflict or concurrent state change	No	Re-read state and use rename only when acceptable.
MICROSOFT_GRAPH_HTTP_429 / 5xx	Rate limit or transient failure	Yes for GET only	Honor Retry-After; reconcile writes before manual retry.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure	Yes for GET only	Verify connectivity and reconcile writes.
RESPONSE_TOO_LARGE	Response exceeded 5 MiB	No	Reduce the limit or narrow the site/list.
EXECUTION_ERROR	Unexpected local/provider invariant	No	Inspect sanitized logs and request correlation.

Provider messages pass through ValkyrAI shared sensitive-data redaction and explicit OAuth-token replacement.

Example

Create one launch-tracking item:

{
  "operation": "create_item",
  "siteId": "contoso.sharepoint.com,abc123,def456",
  "listId": "f75b0e5d-41f8-40ac-bcab-8d22ca8ebc65",
  "fields": {
    "Title": "Verify public SharePoint ExecModule launch",
    "ReleaseState": "Ready for review",
    "EvidenceUrl": "https://valkyrlabs.com/v1/valkyrai/workflow-engine/execmodules/microsoft-sharepoint"
  }
}

Expected result:

{
  "status": "success",
  "operation": "create_item",
  "resource": "items",
  "httpStatus": 201,
  "attempts": 1,
  "id": "42",
  "data": {
    "id": "42",
    "fields": {
      "Title": "Verify public SharePoint ExecModule launch",
      "ReleaseState": "Ready for review"
    }
  }
}

After an ambiguous network failure, query the target list for the intended immutable business key before repeating the create.

Notes

• Pagination: list operations use OData top values up to 1,000 and convert Graph next links into bounded token or skip cursors. Provider URLs never become executable workflow input.
• Rate limits: GET operations honor Retry-After and apply bounded exponential delay for 408, 429, and selected 5xx responses. Mutations are single-attempt.
• API limits: response bodies are capped at 5 MiB; request bodies at 256 KiB, 1,000 array elements, and eight nesting levels.
• Idempotency: Microsoft Graph does not provide one universal idempotency key for these operations. Reconcile by immutable site/list/item/drive ID and business key before retrying a write.
• Destructive behavior: only item deletion is destructive and requires explicit confirmation. Item updates overwrite supplied fields. Folder rename conflict handling creates a new name rather than overwriting.
• Consistency: SharePoint search, list indexes, and permission propagation may be eventually consistent. A successful write does not guarantee immediate search visibility.
• External verification: deterministic tests cover auth, routing, OData continuation, payloads, mapping, redaction, retries, single-attempt writes, destructive confirmation, and metadata discovery. Live tenant execution requires separately authorized Microsoft credentials and is not exercised in repository tests.
• References: n8n Microsoft SharePoint integration, Microsoft Graph site resource, SharePoint list resource, and driveItem resource.