Microsoft OneDrive integration

What it does

The Microsoft OneDrive integration puts a client's whole OneDrive inside your workflows. Upload and download files, convert documents to PDF, organise folders, share with exactly the right people, roll back to earlier versions, and start a workflow the moment a file lands in a folder. Connect a client's Microsoft account once, and the files, folders, drives and permissions each action needs are chosen from dropdowns rather than pasted as IDs.

It works with both kinds of Microsoft account:

• Personal OneDrive, the storage that comes with an Outlook.com or other Microsoft account.
• OneDrive for Business, the storage that comes with a Microsoft 365 work or school account.

A few actions only exist on one of the two. Each one says so in its description, and the full list is under Known limitations.

Connect a Microsoft OneDrive account

OneDrive connects through your agency's own Microsoft Entra app, so the consent screen shows your agency's name.

1. In the Microsoft Entra admin center, register an app under App registrations. Allow accounts in any organizational directory and personal Microsoft accounts, and add the web redirect URI TaskJuice shows you when you add the OAuth client.
2. Under API permissions, add the Microsoft Graph delegated permissions your workflows need:
   • Files.Read to read, download, search and list files, and to run the triggers.
   • Files.ReadWrite to upload, create, move, rename, share and delete files and folders.
   • Files.Read.All for Search Including Shared Items, Find Files with KQL, Get Drive by ID, List Followed Items and Get Sensitivity Labels, which reach files other people own.
   • Files.ReadWrite.All for Restore Deleted Item, Apply Retention Label, Lock or Unlock Record and Remove Retention Label. It also covers everything the three scopes above allow.
   • offline_access so TaskJuice can refresh access in the background.
3. Create a client secret, then add the app's client ID and secret in TaskJuice as an OAuth client for Microsoft OneDrive, ticking the same permissions.
4. In the workflow editor, add a OneDrive step and choose Connect in its connection field. Sign in with the Microsoft account whose files you want to manage on behalf of your client.

None of these delegated permissions needs a Microsoft 365 administrator to approve it by default, although a client's IT team can require approval for every app.

To revoke access, the client can remove TaskJuice from My Apps (work or school accounts) or from Apps and services on their Microsoft account (personal accounts).

Triggers

OneDrive triggers can pick up changes within moments, depending on your plan and your connection (see Known limitations). When you publish, TaskJuice subscribes to Microsoft's change notifications for the drive, and each notification starts an immediate check, never more often than your plan's minimum poll interval. Every trigger also checks on its own every hour by default, as a backstop for any notification Microsoft drops or delays. Each check starts one run, with everything new wrapped in an items array. Add a Loop node after the trigger (type array, path items) to handle each item on its own, or pass the array straight to a digest step. The first check after you publish only records a starting point. Files and folders that already exist never fire the New triggers; the New or Updated triggers fire for them once they change.

The first five watch the whole drive; the last two watch the direct contents of one folder you pick.

• microsoft-onedrive/drive-item-changed: Drive Item Changed. Fires for every file or folder added, changed, or deleted anywhere in the drive. Deleted items arrive with a deleted field.
• microsoft-onedrive/new-file: New File. Fires once for each file created after you publish. Edits, moves and deletions of older files do not fire it, and folders never do.
• microsoft-onedrive/new-folder: New Folder. Fires once for each folder created after you publish.
• microsoft-onedrive/new-or-updated-file: New or Updated File. Fires when a file is created, edited, renamed or moved. Folders and deletions never fire it.
• microsoft-onedrive/item-deleted: File or Folder Deleted. Fires when a file or folder is deleted. OneDrive sends only the item's ID and parent folder (work or school accounts also drop the name), so keep your own record of the IDs you need to recognise.
• microsoft-onedrive/new-file-in-folder: New File in Folder. Fires once for each file created directly inside the folder. Moving an older file into the folder does not fire it.
• microsoft-onedrive/new-or-updated-file-in-folder: New or Updated File in Folder. Fires when a file directly inside the folder is added, edited, renamed or moved in.

Actions

Files and folders

• microsoft-onedrive/list-root-children: List Root Children. Lists the items at the top level of the drive.
• microsoft-onedrive/list-folder-children: List Folder Contents. Lists the items directly inside a folder.
• microsoft-onedrive/get-drive-item: Get Item. Returns one file or folder's details.
• microsoft-onedrive/get-item-by-path: Get Item by Path. Finds a file or folder from its path, such as Clients/Acme/Brief.docx.
• microsoft-onedrive/create-folder: Create Folder. Creates a folder, and lets you choose what happens when the name is taken.
• microsoft-onedrive/copy-item: Copy Item. Copies a file or folder into another folder.
• microsoft-onedrive/move-item: Move Item. Moves a file or folder into another folder, optionally renaming it.
• microsoft-onedrive/rename-item: Rename Item. Renames a file or folder in place.
• microsoft-onedrive/update-item-description: Update Item Description. Sets the description on a file or folder (personal OneDrive).
• microsoft-onedrive/delete-drive-item: Delete Item. Moves a file or folder to the recycle bin.
• microsoft-onedrive/permanently-delete-item: Permanently Delete Item. Erases a file or folder for good, skipping the recycle bin.
• microsoft-onedrive/restore-deleted-item: Restore Deleted Item. Brings a deleted item back from the recycle bin (personal OneDrive).

Upload, download and convert

• microsoft-onedrive/upload-small-file: Upload File. Uploads a file from an earlier step into a folder, up to 250 MB.
• microsoft-onedrive/create-text-file: Create Text File. Saves text you type or map, such as notes, a CSV or a Markdown summary, as a file in a folder. A file with the same name is replaced unless you choose otherwise.
• microsoft-onedrive/replace-file-content: Replace File. Overwrites an existing file's content while keeping its link, sharing and history.
• microsoft-onedrive/download-file: Download File. Downloads a file so later steps can attach or re-upload it.
• microsoft-onedrive/convert-file: Convert File. Downloads a file converted to PDF, HTML or a JPG preview image.
• microsoft-onedrive/download-thumbnail: Download Thumbnail. Downloads a small, medium or large preview image of a file.
• microsoft-onedrive/list-thumbnails: List Thumbnails. Returns thumbnail image links for a file.

Search

• microsoft-onedrive/search-items: Search Items. Finds files and folders in the drive by name, details or content.
• microsoft-onedrive/search-including-shared: Search Including Shared Items. Also searches files other people have shared with the account.
• microsoft-onedrive/search-files-kql: Find Files with KQL. Runs a Microsoft Search query, including Keyword Query Language filters such as filetype:pdf (work or school accounts).
• microsoft-onedrive/get-changes: Get Changes. Reads the drive's change feed, from the start or from a saved token.

Sharing and permissions

• microsoft-onedrive/create-sharing-link: Create Sharing Link. Creates a view, edit or embed link to send to a client.
• microsoft-onedrive/send-sharing-invitation: Send Sharing Invitation. Gives one person access and emails them an invitation.
• microsoft-onedrive/list-item-permissions: List Item Permissions. Lists everyone who can access an item.
• microsoft-onedrive/get-permission: Get Permission. Returns one access grant.
• microsoft-onedrive/update-permission: Update Permission. Changes a grant between view and edit.
• microsoft-onedrive/delete-permission: Remove Item Permission. Revokes a grant or sharing link.
• microsoft-onedrive/get-shared-item: Get Shared Item. Opens a sharing link someone sent and returns the item behind it.
• microsoft-onedrive/download-shared-item: Download Shared File. Downloads the file behind a sharing link.
• microsoft-onedrive/get-sharing-link-permission: Get Sharing Link Details. Returns a sharing link's type, audience and access level.
• microsoft-onedrive/grant-sharing-link-access: Grant Access to Sharing Link. Adds a person to a specific-people link (work or school accounts).

Versions

• microsoft-onedrive/list-versions: List Versions. Lists a file's earlier versions, newest first.
• microsoft-onedrive/get-version: Get Version. Returns when a version was saved and by whom.
• microsoft-onedrive/download-version: Download Version. Downloads an earlier version of a file.
• microsoft-onedrive/restore-version: Restore Version. Makes an earlier version the current one, keeping the rest of the history.

Drives and special folders

• microsoft-onedrive/get-drive: Get My Drive. Returns the account's drive, including its storage quota.
• microsoft-onedrive/list-drives: List Drives. Lists the drives the account can use.
• microsoft-onedrive/get-drive-by-id: Get Drive by ID. Returns any drive the account can access.
• microsoft-onedrive/get-special-folder: Get Special Folder. Returns Documents, Photos, Camera Roll, Music, the app folder, or Recordings without knowing its ID.

Work and school collaboration

These actions work on OneDrive for Business only.

• microsoft-onedrive/preview-item: Get Preview Link. Returns a short-lived embeddable preview of a file.
• microsoft-onedrive/check-out-item: Check Out File. Locks a file so only you can change it.
• microsoft-onedrive/check-in-item: Check In File. Releases a checked-out file, with an optional comment.
• microsoft-onedrive/discard-checkout: Discard Checkout. Cancels a checkout and throws away its changes.
• microsoft-onedrive/follow-item: Follow Item. Adds a file or folder to the account's followed list.
• microsoft-onedrive/unfollow-item: Unfollow Item. Removes it from the followed list.
• microsoft-onedrive/list-followed-items: List Followed Items. Lists the items the account follows.
• microsoft-onedrive/get-item-analytics: Get Item Analytics. Returns how often a file was viewed, and by how many people.
• microsoft-onedrive/get-item-activity-stats: Get Item Activity Stats. Returns view, edit and delete counts per day, week or month.

Compliance labels

These actions work on OneDrive for Business with Microsoft Purview labels only.

• microsoft-onedrive/extract-sensitivity-labels: Get Sensitivity Labels. Reads the sensitivity labels on a file.
• microsoft-onedrive/apply-retention-label: Apply Retention Label. Applies a retention label by name.
• microsoft-onedrive/lock-or-unlock-record: Lock or Unlock Record. Locks or unlocks an item labelled as a record.
• microsoft-onedrive/remove-retention-label: Remove Retention Label. Removes the retention label from an item.

Albums and bundles

These actions work on personal OneDrive only.

• microsoft-onedrive/list-bundles: List Bundles. Lists the account's bundles and photo albums.
• microsoft-onedrive/create-bundle: Create Bundle. Groups files into a new bundle or photo album.
• microsoft-onedrive/add-item-to-bundle: Add Item to Bundle. Adds a file to a bundle or album.
• microsoft-onedrive/remove-item-from-bundle: Remove Item from Bundle. Takes a file out of a bundle without deleting it.

Known limitations

• Pickers list the top level of the drive. Folder dropdowns show only the folders at the top level of the drive, and file dropdowns show everything there. For anything deeper, switch the field to an expression and map the ID from Search Items, Get Item by Path, List Folder Contents, or a trigger. Create Folder, Upload File, Create Text File and List Folder Contents default to the top level itself.
• Copy finishes in the background. Copy Item returns straight away. The status link OneDrive gives back is on the step's meta.headers.location, and the copy appears in the destination folder once it finishes. On personal OneDrive a copy onto an existing name always fails, because the name-conflict option is a work and school feature.
• Uploads are limited to 250 MB per file. Upload File and Replace File send a file in one request, which OneDrive allows up to 250 MB. Larger files need OneDrive's chunked upload, which TaskJuice does not offer yet.
• Uploading straight from a web address is not available. Microsoft retired that feature before it left preview.
• Conversion formats are PDF, HTML and JPG. PDF works from Word, Excel, PowerPoint and many other document types, HTML from Loop and Whiteboard files, and JPG from almost any file. A JPG needs a width and a height.
• Personal versus work or school. Restore Deleted Item, Update Item Description, embed links, link passwords, and bundles work on personal OneDrive only. Get Preview Link, following, analytics, compliance labels, Grant Access to Sharing Link, Find Files with KQL, and the Recordings special folder work on OneDrive for Business only.
• Notifications wait for your plan's minimum poll interval. A change notification starts a check within moments, but never sooner than your plan's minimum poll interval after the previous check. On a plan whose minimum is one hour, changes still arrive at the next hourly check.
• Folder triggers watch direct contents only. The folder triggers watch only the folder's direct contents, not its subfolders. New File in Folder and New or Updated File in Folder each watch the first (Max Items Per Cycle x 10) entries of the folder listing, 1,000 by default.
• Triggers are started by change notifications. Each trigger reads changes from OneDrive itself (the drive's change feed, or the folder's contents for the two folder triggers), and Microsoft Graph change notifications tell it when to look. One notification subscription watches the whole drive, including every folder in it, so it starts the folder triggers too. When you publish, TaskJuice subscribes to notifications on the trigger's OneDrive connection, and each notification starts an immediate check of your OneDrive triggers, at most once per your plan's minimum poll interval. Each trigger also checks on its own at its poll interval (hourly by default, 60 seconds minimum), which catches any notification Graph drops or delays. Notifications come from one OneDrive connection per TaskJuice account. If your triggers use several OneDrive connections, a change in that connection's drive starts a check of all of them, but changes in the other connections' drives are picked up at their poll interval. Adding a second connection later keeps notifications on the one already in use. If the OneDrive triggers you first publish already use more than one connection, no connection receives notifications, and every trigger relies on its poll interval until you set all your OneDrive triggers to the same connection and republish. For work and school (OneDrive for Business) accounts, the connection must be authorized with Files.Read.All or Files.ReadWrite.All to receive notifications, and Microsoft only lets TaskJuice renew the monthly subscription with Files.ReadWrite (personal) or Files.ReadWrite.All (work and school). Add the permission to your Microsoft OAuth client in TaskJuice, then reconnect. Without these permissions, the triggers rely on their poll interval.
• List actions return one page unless you ask for more. OneDrive returns up to 200 items per page. Turn on Return All under Pagination to read every page (up to 10,000 items), or set Limit to stop after a number of items.
• Rate limits. Microsoft limits how fast an app can call OneDrive for each client tenant. When OneDrive asks TaskJuice to slow down, TaskJuice waits for as long as OneDrive says and then retries.
• The drive must exist. A brand-new Microsoft 365 user whose OneDrive has never been opened may need to open it once in the browser before the connection can reach it.