Microsoft OneDrive

If your district runs on Microsoft 365, the documents people ask about are in OneDrive: the staff handbook in Word, the fee schedule in Excel, the new-hire orientation deck in PowerPoint. Connecting OneDrive brings the folders and files you pick into the knowledge base that schoolAgent and Otto answer from, and keeps them current as people edit them. See Knowledge for how it sits beside the other knowledge integrations.

Three things to know before you start:

• It's read only. schoolOS reads the documents you pick and nothing else. It never creates, edits, shares, moves or deletes anything in OneDrive. Microsoft's sign-in screen does list write access, for a reason explained in Why Microsoft asks about full access.
• Each person connects their own Microsoft account, and sees only their own OneDrive. Nobody browses anyone else's files, and connecting doesn't widen what anyone can see.
• You choose what comes in. Nothing syncs until you tick a folder or a file, and only what you tick is read.

You need Manage integrations to connect OneDrive and choose what syncs, and Manage knowledge to open the Knowledge tab and remove documents. Your plan needs schoolAgent.

Connect#

Connect from either place:

• The Knowledge tab of Admin › Agent › Configuration: select Add knowledge source, choose OneDrive, then Connect OneDrive. This is the quickest way, because choosing what comes in happens on the same screen.
• The OneDrive page: open Admin › Account › Integrations, select Microsoft OneDrive, and select Connect OneDrive under Connection.

Either way, Microsoft asks you to sign in and approve access for schoolOS. Sign in with the Microsoft 365 account whose OneDrive holds the documents; any staff member can connect their own, and no Microsoft 365 admin rights are needed. Microsoft shows what schoolOS asks for:

• Read all files that you have access to. This is what lets schoolOS list your folders and read the files you pick.
• Have full access to all files you have access to. Needed only to open shared and SharePoint links. schoolOS never uses it to write: see below.
• Sign you in and read your profile. Only so the connection can be labeled with your name and address.
• Maintain access to data you have given it access to. So the scheduled check can run without you signing in again.

The sign-in tokens are stored encrypted and never shown again. Only the person who started the sign-in can finish it, and only for the district it was started in.

Once connected, the OneDrive page shows Connected at the top and Connected as your email under Connection, with Add documents in Knowledge beside it. Your account also appears under OneDrive connections with a You badge, and the Knowledge tab's OneDrive source shows Connected to your email.

Why Microsoft asks about full access#

Microsoft lets an app open a sharing link, like a link to a SharePoint library or to a file a colleague shared with you, only when the app holds the permission Microsoft calls Files.ReadWrite.All ("Have full access to all files you have access to"). Read access alone isn't enough for those links. So schoolOS asks for it, and uses it only to look up what a link points to and read it.

schoolOS never writes with it: no code in schoolOS creates, edits, shares, moves or deletes anything in OneDrive or SharePoint. It reaches only what the signed-in account can already open.

Connected before this permission was asked for? The OneDrive page says Reconnect to read shared and SharePoint links. Your connection keeps syncing what it syncs today; it just can't open shared or SharePoint links. Select Reconnect and sign in with the same Microsoft account. Your folders, schedule and documents stay as they are.

Choose what comes in#

Open the Knowledge tab of Admin › Agent › Configuration, select Add knowledge source and choose OneDrive, or select Add documents in Knowledge on the OneDrive page, which takes you there. Under Browse and select folders or documents, the tree is your OneDrive, starting at its top level. Open a folder to see what's inside; each level is read from Microsoft as you open it.

• Tick a folder to bring in every supported document inside it, including sub-folders. The folder is remembered, so documents added to it later come in on the next sync, and the folder shows a Syncing badge, with its document count, from then on.
• Tick a file to bring in just that one.
• A folder that's partly ticked shows a half-filled box, so you can see something inside it is syncing without the whole folder being chosen.

Select Next. On Audience, choose Who can see answers from this (see Who sees it) and How often (see What syncs, and when). Select Next again: Review repeats what's coming in, how often it syncs and who can see it ("Keeps in sync weekly", "Staff"), so nobody imports a handbook without noticing who can read it. Select Add knowledge.

The import runs in the background. The Knowledge tab shows what it's doing: "Looking through folders — 40 documents so far", then "Reading 12 of 40", then "Adding to the knowledge base…", and finally "Added 38 documents to knowledge", with a list of any documents it couldn't read and why. You can leave the page; the documents appear in the Sources list as the folders finish.

A folder or a file?#

Tick the folder when the documents change or grow: a "Procedures" folder your IT team adds to, or a "Board" folder that gains an agenda every month. The folder is re-checked on your schedule, new files come in, and edited files are re-read.

Tick a single file when it's a one-off that isn't going to change, like a signed policy or a map. A single file is imported once and isn't re-checked: to pick up an edit, remove it from the Sources list and add it again.

Stop syncing a folder or remove a file#

In the Sources list on the Knowledge tab, a synced folder is one row, with its sub-folders and documents underneath. Open its ⋯ menu and select Stop syncing and delete. The folder is forgotten and every document it brought in is deleted from the knowledge base; the files in OneDrive are untouched. Select Keep syncing to back out.

To remove single documents, untick them in the OneDrive picker and select Remove, or open the document's ⋯ menu in the Sources list and select Delete. Either way you confirm first, and the file in OneDrive stays as it is.

What you can't browse#

The tree is the OneDrive of the account you signed in with. SharePoint document libraries, Teams files and OneDrive's Shared with me list don't appear. To bring in a document from a SharePoint site, have someone copy it into a OneDrive folder they sync, or connect the account that owns it.

What syncs, and when#

Every connection has a How often: bring the documents in Once, or Keep in sync hourly, daily, weekly or monthly. Set it in the OneDrive picker when you add a folder, in a document's Edit dialog on the Knowledge tab (it applies to every document from that connection, not just the one you're editing), on the connection's row under OneDrive connections, or on Microsoft OneDrive in the Knowledge tab of Admin › Account › Import Data. It's the same setting in every place, and it saves as soon as you pick it.

Once, or keep in sync?#

| Option | What it does | Choose it when | | --- | --- | --- | | Once — I'll sync again when I want | A one-time import: nothing runs on its own. Sync now re-reads your folders when you ask. | The documents are finished and won't change, or you want to control exactly when the agent's answers change, like the day a new handbook is approved. | | Keep in sync: hourly | Checks for changes once an hour. | A folder people edit during the day, like an IT status document or a snow-day plan that's rewritten the morning of. | | Keep in sync: daily | Checks once a day. | Procedures and FAQs your teams edit now and then. A good default for an IT or Facilities folder. | | Keep in sync: weekly | Checks once a week. New connections start here. | Handbooks and policies that change a few times a year. | | Keep in sync: monthly | Checks once a month. | Reference material that's reviewed yearly, like a facilities map or a board policy manual. |

A frequent schedule is cheap. Each check first asks Microsoft one question, "has anything in this OneDrive changed since last time?", and when the answer is no and the last run was clean, the check ends there with "No changes since the last sync": nothing is downloaded. When something has changed, every synced folder is walked, and documents whose text hasn't changed are skipped before anything else is done. Only edited and new documents are read again.

Sync now, on each connection's row under OneDrive connections, skips that question and walks the folders right away. Use it after an edit you don't want to wait for.

What happens to a document at the source:

• Edited. It's read again on the next check and replaces the old text. Until then, answers come from the old version.
• Added to a synced folder, or moved into one. It comes in on the next check.
• Renamed. The new name is used on the next check.
• Deleted, moved out of a synced folder, or no longer shared with you. It leaves the knowledge base on the next sync (scheduled or Sync now), and schoolAgent stops answering from it. The sync result says how many were removed. A document you imported on its own, rather than through a folder, isn't removed this way: delete it from the Sources list (Delete in its ⋯ menu) when it shouldn't be used any more.
• A synced folder deleted in OneDrive, or one you can no longer open. It's skipped, and the run is marked as partial with the folder named, like "1 folder could not be listed (HR)". While any folder can't be listed, nothing is removed, so what it brought in earlier stays until you stop syncing it.

Each walk runs in the background, so a folder of three hundred documents takes as long as it takes. There's no cap on how many files a folder can hold. Scanned PDFs, which have no text to read, are sent to text recognition in a separate pass of up to 100 per run; any left over say so in the sync result and are picked up on the next run. A run that couldn't read some documents, or couldn't list a folder, is marked as partial, and the next scheduled check walks the folders again even if nothing changed, so a file that failed to download gets another chance. schoolOS only moves its "changed since" bookmark forward after a walk that finished, so an edit made during a run that stopped partway is still picked up next time. If Microsoft expires that bookmark (it does after a long gap), the next check walks the folders and starts a fresh one.

The OneDrive page's Connection section shows when the connection last synced and the result ("Imported 38 document(s), 2 could not be read"), or "Not synced yet." Each row under OneDrive connections shows how many folders it syncs, how many files have arrived, and when it last synced. A connection with folders but no files is the one to look at: see Troubleshooting.

For example, a district's HR office keeps "Staff Handbook 2026-27.docx" and the benefits guide in a OneDrive folder called "Staff Resources". The HR director connects her Microsoft account, ticks the folder for Staff and sets Keep in sync: daily. When she updates the leave policy on a Tuesday, Wednesday's check re-reads that one document, and a teacher asking schoolAgent "How many personal days do I get?" gets the new number.

File types and limits#

| In OneDrive | What schoolOS reads | | --- | --- | | Word (.docx) | The text | | Excel (.xlsx) | Every sheet under its own heading, so numbers and names stay searchable | | PowerPoint (.pptx) | Every slide's text under its own heading | | PDF | The text layer. A scanned PDF with no text layer is sent to text recognition | | Plain text, Markdown, CSV, HTML, JSON | As is |

Everything else is skipped: images, video, audio, OneNote notebooks, Visio, Publisher and zip files. A skipped file is listed in the sync result as "No readable text" and doesn't stop the rest of the folder.

• Only the first 50,000 characters of each document are kept, about 20 pages of text. A longer document is cut off at that point. Split a very long handbook into chapters if the end of it matters.
• A document with fewer than 20 characters of text counts as unreadable.
• Folders are followed 10 levels deep.
• Older Office formats (.doc, .xls, .ppt) are attempted as their modern equivalents and often fail. Re-save them as .docx, .xlsx or .pptx.

Who sees it#

OneDrive's sharing settings don't carry over. A file only you can open in OneDrive becomes readable, through schoolAgent, by whichever audience you choose when you import it. So the audience is the decision that matters.

Who can see answers from this, on the Audience step, lists the audiences. Ticking a broader group ticks everything it covers.

Which audience should I choose?#

| Option | Who gets answers from it | Choose it when | | --- | --- | --- | | Public (all) | Everyone, including guests on your website who aren't signed in | The document is already public: the student handbook, bell schedules, board policies, the school calendar. | | Everyone signed in | Anyone with a schoolOS account: staff, students and guardians, but not website visitors | Information for your community that you'd rather not publish to the open internet, like a bus route list or a lunch menu with building details. | | Staff | Teachers, helpdesk staff and admins | Procedures, internal FAQs, the IT runbook, HR guidance. | | Students | Everyone whose school role is Student | A student tech guide, club lists, the library's borrowing rules. | | Guardians | Parents and guardians | Enrollment paperwork, pickup procedures, fee information. | | A school role, like Librarians or Bus Drivers | Only people with that school role | A procedure that one team follows, like the library's damaged-book process or the transportation radio protocol. |

The audience you pick applies to everything in that import. A folder keeps its audience on every later sync, so documents added to a staff folder next year still come in for staff. To give a folder a different audience, stop syncing it and add it again with the new one. You can change a single document's audience from its Edit dialog on the Knowledge tab; the change holds until that document is edited in OneDrive, when it's re-read with its folder's audience.

At answer time, schoolAgent only uses documents whose audience includes the person asking. Someone signed in as a guardian never gets an answer from a Staff document, and a guest on your website only gets answers from Public (all) documents.

For example, a middle school tech assigned to one building keeps "Chromebook Repair Steps.docx" and a spreadsheet of loaner serial numbers in his OneDrive. He ticks the procedure for Staff so teachers can ask schoolAgent how to file a repair, and leaves the spreadsheet unticked: it's his working list, not knowledge.

Connections#

The OneDrive page lists every connected account under OneDrive connections, whether or not you've connected your own. Each row shows Connected to and the person's email, a You badge on yours, how many folders it syncs and files have synced, when it last synced, a How often picker, Sync now and Disconnect.

Connections are per person for a reason: each one browses and reads OneDrive with its owner's access. So only the person who connected an account can change which of its folders sync; everyone else sees "Only name can change which folders sync." Anyone with Manage integrations can change a connection's schedule, remove its documents or disconnect it, because those are decisions about the knowledge base rather than about someone's Microsoft account.

A row marked Shared is a connection made before connections belonged to people. It has no owner, so anyone with Manage integrations can change its folders.

Disconnect#

Three places, with different reach:

• Disconnect on a row under OneDrive connections disconnects that one account. Its folders stop syncing.
• Disconnect under Connection on the OneDrive page, and Disconnect in the OneDrive picker on the Knowledge tab, disconnect every OneDrive connection in your account, not only yours.
• Disconnect from the ⋯ menu on the Microsoft OneDrive row of Admin › Account › Integrations does the same. See Disconnect an integration.

You confirm first. Disconnecting stops syncing and clears the saved sign-in. Documents already in the knowledge base stay, and schoolAgent keeps answering from them, until you remove them from the Sources list. Nothing changes in OneDrive. If the same person reconnects with the same Microsoft account, the folders they chose are remembered and syncing resumes.

Troubleshooting#

• "OneDrive not connected" or "OneDrive authorization expired — reconnect required." Microsoft no longer accepts the saved sign-in: the password changed, the account was disabled, or sign-in sessions were revoked by your Microsoft 365 admin. Connect again.
• "Only the person who connected this account can change which folders sync." You're trying to add folders to someone else's connection. Connect your own Microsoft account and pick from it.
• "OneDrive list failed" with a message from Microsoft. The message says what went wrong, most often an item that no longer exists or an account whose OneDrive hasn't been set up. Open OneDrive in a browser once to set it up, then try again.
• The sign-in comes back with an error in the address bar. access_denied means you or your admin declined; invalid_state means the sign-in was finished by a different person or browser than started it. Start again from schoolOS.
• A folder shows "No folders selected yet" or zero files synced. Nothing in it is a supported type, or the sync hasn't run. Select Sync now on the connection's row and read the result: it names every document it couldn't read and why.
• "No readable text." The file is an image, a scanned PDF waiting for text recognition, or an empty document. Scans are transcribed on the same run, up to 100 per run; the rest follow on the next.
• "N folders could not be listed." The folder was deleted, or your account lost access to it. The run is partial and nothing is removed until it can be read again; restore access, or stop syncing the folder.
• "Scanned PDF — over this run's OCR limit." More than 100 scans in one run. They're read on the next run; select Sync now to start it.
• "Sync didn't finish" or "Abandoned before it finished." The background run stopped partway, usually during a deploy. Select Sync now; documents already added stay, and unchanged ones are skipped.
• schoolAgent answers from an old version. The document was edited after the last check. Wait for the schedule or select Sync now. If the new wording is past the first 50,000 characters, it was never read.
• "This OneDrive connection can't open shared or SharePoint links yet." The connection was made before schoolOS asked for the permission Microsoft requires for links. Reconnect OneDrive (see Why Microsoft asks about full access), then try the link again.
• "The connected Microsoft account can't open this link." The connection has the permission, but the account itself has no access to what the link points to. Ask the owner to share it with that account, or copy it into that account's OneDrive.
• The folder is in SharePoint or Teams, not in the picker. Only the signed-in account's own OneDrive is browsed. Copy the documents into a OneDrive folder, or connect the account that owns them.
• "Syncing…" never ends. Refresh the page; a finished run keeps its last result on screen. If it's still running after an hour, select Sync now again: a run that has stopped moving is released and a new one starts.