Microsoft Intune

Microsoft Intune manages the Windows laptops in your district, and often the iPads, Android tablets and Macs enrolled beside them: each device's name, model, serial, OS, primary user, compliance state, storage, encryption and last check-in. Connecting it to schoolOS reads every managed device into schoolAssets and keeps it current, so a Windows laptop's record in schoolOS matches the one in the Intune admin center without anyone retyping it.

What the connection does:

• Brings devices in. Every device Intune manages is matched to an asset you already have. One that matches nothing is counted and left alone (see below).

• Keeps them current. A sync runs every night, and Sync now runs one on demand. Each field Intune reports lands in the schoolOS field you map it to.

• Feeds Device Health. Storage, encryption, battery health and last check-in drive the Device Health checks for Intune devices.

• Sends Intune actions, when you turn it on. With device management on, a device's MDM section offers the Intune actions its platform supports, and workflows can send them. It's off on every connection until an admin turns it on: until then schoolOS only reads from Intune.

You need Manage integrations to connect it or change its settings. Connecting with device management on, or turning it on, also needs Update assets (assets.update), the permission that sends device actions.

Connect#

The connection is organization-wide: a Global Administrator approves schoolOS once for your district's whole Microsoft organization, and from then on schoolOS reads Intune on its own. It doesn't run on anyone's sign-in, so it keeps syncing when the person who connected it leaves, changes their password or loses their admin role.

1. Open Admin › Account › Integrations and select Microsoft Intune.
2. Under Connection, select Connect Microsoft Intune and sign in with a Global Administrator or Privileged Role Administrator account. Signing in only tells schoolOS which Microsoft organization is yours.
3. Microsoft shows the permissions schoolOS asks for, for the whole organization. Accept them. Syncing needs one: Read Microsoft Intune devices (DeviceManagementManagedDevices.Read.All). The list shows more than that; see What Microsoft asks you to approve.
4. schoolOS reads one Intune device to make sure the approval works, then sends you back to the setup page, connected.

The person who selects the button has to be the one who finishes, still signed in to schoolOS: a sign-in link opened by someone else, or after the session expired, is refused with "The Microsoft sign-in expired, or started before the latest settings. Try connecting again."

Once connected, the Connection section shows:

• Sync Intune devices. On. Turn it off to pause the nightly sync and Sync now without disconnecting; your settings stay.
• Connected account, with Disconnect.

schoolOS keeps no one's password or sign-in for this connection: it asks Microsoft for a short-lived access token whenever it syncs or sends an action, stores it encrypted and never shows it. The field mapping only ever pulls: Intune's write surface is device actions, not inventory fields.

The Microsoft organization you connected also counts as yours for Microsoft sign-in: once it's connected, work and school Microsoft accounts from other organizations can't sign in to your district. See Microsoft organizations.

What Microsoft asks you to approve#

schoolOS has one Microsoft app, and an approval covers everything that app is registered for. So Microsoft's approval screen lists these for every district, including one that only syncs:

• Read Microsoft Intune devices (DeviceManagementManagedDevices.Read.All): what the sync reads.
• Perform user impacting remote actions on Microsoft Intune devices (DeviceManagementManagedDevices.PrivilegedOperations.All) and Read and write Microsoft Intune devices (DeviceManagementManagedDevices.ReadWrite.All): the Intune actions, such as retire and wipe.
• The permissions directory sync and calendar sync use.

Approving them doesn't turn anything on. schoolOS sends no Intune action until an admin turns on device management on the setup page, and it's off on every connection until then. Directory sync and calendar sync stay off until you set them up. If your district doesn't want device actions approved at all, remove the two device-action permissions from the schoolOS app under Enterprise applications in the Microsoft Entra admin center after connecting; syncing keeps working.

Connected before it was organization-wide?#

A connection made before organization-wide connections existed runs on the sign-in of the person who connected it, and stops syncing if that account leaves, loses its Intune role or is signed out everywhere. Until it's reconnected it keeps working as it always has, and the Connection section shows Reconnect for an organization-wide connection. Select Reconnect, sign in as a Global Administrator and accept, as above. The old sign-in is replaced, and your matching, field mapping and Sync Intune devices setting stay as they were.

Device management#

Device management, below Connection, decides whether schoolOS may send Intune actions. It's off on every connection, new or old, and while it's off schoolOS only reads from Intune and the section says Read only.

To turn it on:

1. Under Device management, turn on Allow schoolOS to manage devices. It needs an organization-wide connection; one that still runs on a person's sign-in shows Reconnect before turning on device management first.
2. schoolOS reads which permissions your Microsoft organization has approved for it, from the connection's own access token. Usually they were approved when you connected (see What Microsoft asks you to approve) and device management is on straight away. If any are missing, for example on a connection approved before schoolOS had device actions, the section shows Approve device actions in Microsoft, listing each one:
   • Perform user impacting remote actions on Microsoft Intune devices (DeviceManagementManagedDevices.PrivilegedOperations.All): every action.
   • Read and write Microsoft Intune devices (DeviceManagementManagedDevices.ReadWrite.All): Rename only, which writes the device's record. Without it every other action works, and the section shows Approve renaming in Microsoft.
3. Select Approve in Microsoft and sign in with a Global Administrator or Privileged Role Administrator. Microsoft shows the permissions for your organization; accept them, and you're sent back here.
4. Microsoft can take a few minutes to apply an approval. The page checks again each time you open it, and shows Device management on once it has. Until then no action is offered.

Both are application permissions, granted to schoolOS for your whole organization, the same way as reading devices. To take them back, turn device management off here, and remove them from the schoolOS app under Enterprise applications in the Microsoft Entra admin center. Turning it off, or removing a permission, stops actions straight away, including ones a workflow queued earlier: they fail with the reason instead of being sent. Each change to device management is in the logs.

Intune actions#

With device management on, a device's MDM section in schoolAssets shows Microsoft Intune device actions, one button per action, for people who can update assets (Update assets). Each is judged against what the last sync reported about the device: an action its platform doesn't support is grayed out with the reason, and one that depends on something Intune didn't report (whether it's supervised, whether it's in Lost Mode) shows a note instead.

| Action | Windows | macOS | iOS/iPadOS | Android | What it does | | --- | --- | --- | --- | --- | --- | | Sync Device | Yes | Yes | Yes | Yes | Asks the device to check in with Intune now. | | Restart | Yes | Yes | Supervised | Corporate-owned | Restarts the device. | | Remote Lock | No | Yes | Yes | Yes | Locks the screen; the device's own passcode unlocks it. | | Rename | Corporate-owned | No | Supervised | No | A new name, up to 15 characters. Windows takes it at its next restart. | | Enable Lost Mode | No | No | Supervised | No | Locks the device to your message, phone number and an optional footnote. | | Disable Lost Mode | No | No | Supervised, in Lost Mode | No | Back to normal use. | | Locate Device | Yes | No | Supervised, in Lost Mode | No | The location shows in the Intune admin center. | | Play Lost Mode Sound | No | No | Supervised, in Lost Mode | No | Sounds an alert for a minute. | | Retire | Yes | Yes | Yes | Yes | Removes the device from Intune with the school's apps, data and settings. Can't be undone. | | Wipe | Yes | Yes | Yes | Yes | Factory reset. Can't be undone. |

Retire and Wipe can't be undone, so the dialog asks you to type ERASE and the asset tag (the one printed on the device), exactly as for a Jamf erase. Wipe has Keep enrollment state (a Windows device rejoins Intune by itself) and Keep user data, both off: a wipe erases everything unless you turn one on. Wiping a Mac needs a six-digit unlock PIN: schoolOS generates it, shows it once and keeps it on the device's timeline, where only people who can send device commands see it. On a personally owned device, Wipe warns you that it erases the owner's whole device, where Retire removes only the school's data.

Microsoft accepts an action before the device does anything, so the dialog says it's queued. The device acts at its next check-in, and the sync after that reads the device's own report and records confirmed (or what went wrong) on the device's timeline. A retired device stops syncing; its asset keeps what was last synced.

The same actions are in the workflow builder's Intune actions group, with templates for a lost iPad, a found one and a retired device. See Device actions.

The setup page#

Once connected, Connection stays open (fold it from its name) and each section after Device sync folds closed and shows its current setting. The page remembers what you left open. Every section has its own Save changes.

• Connection. Above.
• Device management. Off, or on and approved. See Device management.
• Device sync. Last sync with its status, and Devices synced: how many were updated, created and unmatched in the last run, whether it pulled everything or only what changed, how many unchanged devices it skipped, and anything about duplicate serials. Sync now at the top runs one right away in the background; the page watches it for up to 30 minutes and you can leave at any time.
• Asset identifier matching. Which schoolOS field is compared with which Intune field when a device isn't linked yet. See How an Intune device is matched.
• Field mapping. Where each Intune field lands in schoolOS, with a Graph reference link to Microsoft's description of the managed device record. See Field mapping.

What syncs and when#

A sync runs on a schedule every night, and whenever you select Sync now. The nightly sync keeps its own work small: it asks Microsoft Graph only for the devices whose last check-in is since the last successful run (reaching back a day further than it needs to, for clock differences). Everything is read again once a week, after a failed sync, on a connection's first sync, and every time you select Sync now, so a device retired or edited in the Intune admin center without checking in is still picked up within the week.

A device whose Intune record hasn't changed since the last sync is skipped: nothing is written to it or its asset, its modified date and timeline stay as they were, and Devices synced says how many were skipped as unchanged. Changing a field mapping or a matching setting makes the next sync go over every device once.

For each device the sync:

1. Finds its asset, by its Intune device ID and then by your matching setting (see below).
2. Links them. The asset's MDM section shows the Intune record, with Last check-in from Intune's last sync time and Status from the compliance state.
3. Writes the mapped fields onto the asset. If the asset has no asset tag, it gets the next schoolOS asset tag (Intune has no asset tag field; see matching).
4. Runs the Device Health checks on it.

Each run is summarized on the Integrations tab of Admin › Account › Logs, with its counts.

Field mapping#

Everything Intune reports shows on each device's MDM section whether or not it's mapped; mapping a field to a schoolOS field is what makes it filterable, reportable and usable in workflows. The table lists the managed device record's fields in its groups: Device Identity, User & Ownership, Enrollment & Azure AD, Compliance & Security, Operating System, Hardware & Storage, Management & Configuration, Exchange & Email and Sync & Activity. Search them, or filter by Group or by Sync (Pull into schoolOS, Off). Every row is read only on Intune's side, so the only direction is Pull.

For each row, tick it to sync it and choose the schoolOS field (your own custom asset fields are in the list; + New custom field… creates one on the spot, if you can manage asset fields). A row with a suggested target that isn't chosen shows Default: and the field, with Use default. Save changes saves.

A new connection starts with these rows on:

| Intune field | schoolOS field | | --- | --- | | Device Name | Name | | Model | Model | | Manufacturer | Manufacturer | | User Display Name | Assigned To (Name) | | Email Address | Assigned To (Email) | | Enrolled Date/Time | Deployed Date (only while it's empty) | | Operating System | OS Name | | OS Version | OS Version | | Last Sync Date/Time | Last Inventory Date |

Worth knowing:

• Email Address is Intune's own email address for the primary user, or the user principal name only when that is an email address. A UPN like [email protected] isn't an email, so Assigned To (Email) stays empty for that device. User Principal Name isn't mapped to start with for the same reason.
• Enrolled Date/Time fills Deployed Date only while it's empty. Re-enrolling a device moves Intune's date, and a deployment date a technician recorded shouldn't move with it.
• Compliance State isn't mapped to Status: compliant or non-compliant is a posture, not a lifecycle, and mapping it would overwrite Deployed and In Repair. It still shows on the MDM section, and the Device Health checks read what they need directly.
• Device Category is what schoolOS reads as the device's org unit. Map it to Location if your categories are buildings, or to a custom field if they're something else.
• Model, Manufacturer, Location and the other reference fields are matched to a record you have, by name (or a location's code or abbreviation). A value nothing matches is skipped and the sync's log says so. A value a typed field can't take, like text in a date, is skipped the same way.
• Two rows pointed at the same schoolOS field keep whichever the sync reads last. Map one.

Which should I choose: who is the assignee?#

Intune's primary user is usually the person who enrolled the device, which for a shared cart or an Autopilot-provisioned laptop may be a technician. Keep User Display Name and Email Address mapped when your laptops are 1:1 and the primary user is the student or teacher who has it; the asset's Assigned To fields follow Intune without checking the device out to anyone. Turn those rows off when devices are shared or assigned at check-out in schoolOS, so a technician's name doesn't land on 400 laptops.

For example, a district with 2,100 1:1 Windows laptops connects Intune and keeps the defaults. Every laptop's model, OS, primary user and last check-in fill in overnight, and the Not checking in check flags the 23 that haven't contacted Intune in a month, before the summer collection.

How an Intune device is matched#

The Intune device ID is what tells devices apart; a serial number or an asset tag only finds the asset a not-yet-linked device belongs to. The full rules, including re-enrollment, the same device in two device managers and duplicate serials, are in How a device is matched. What's specific to Intune:

• The device ID is Intune's managed device id. Once linked, a device stays linked to its asset whatever its serial says.
• The serial number is Intune's serialNumber, compared with the asset's Serial Number. Windows devices often report a placeholder serial from the firmware, like "To be filled by O.E.M." or "Default string"; those never match, never count as duplicates, and the device is keyed on its device ID instead. Its MDM section shows No real serial.
• Intune has no asset tag field, and a device name like DESKTOP-4F7K2Q isn't one, so schoolOS never reads the name as a tag on its own. A district that names devices by asset tag (a common Autopilot naming template) matches on it with Asset Tag ↔ Device Name below.
• Asset identifier matching adds one more comparison for a device that still has no match: the schoolOS identifier (Asset Tag or Serial Number) against the Intune field to match (Serial Number, Device ID or Device Name). The page offers Asset Tag ↔ Serial Number first; until you save this section, the sync matches on the serial number alone.

The same laptop in Intune and in Google Devices (a Windows device with the Google endpoint agent, say) is one asset with two links; each system fills in its own fields, and where both report the same kind of field, the one that reported most recently wins.

Which should I choose?#

| Setting | Choose it when | | --- | --- | | Serial Number ↔ Serial Number | Your asset list came from purchase records with reliable serials. The usual choice. | | Asset Tag ↔ Device Name | Your device names are your asset tags, so a laptop whose serial is a firmware placeholder, or was mistyped on the spreadsheet, still finds its asset. | | Asset Tag ↔ Device ID | Only if your asset tags are Intune device IDs, which is rare. |

Devices Intune has that schoolOS doesn't#

An Intune device that matches no asset is counted as unmatched in the sync's summary and left alone: nothing is added to inventory. This page has no setting to add new devices automatically or queue them for review, so Intune fills in devices you already have rather than being your list of record.

To get Windows laptops into schoolOS, import them first from your purchasing records with a CSV import, with their serial numbers, or name your devices by asset tag and import those. The next sync matches each one and fills in the rest. A device whose serial is on more than one asset waits as a Duplicate serial rather than being guessed; the sync's summary counts these.

Assets are never deleted when a device leaves Intune: a laptop drops out for a reimage or a retirement, and deleting the asset would lose its history.

Device Health#

Intune devices get these Device Health checks: Disk nearly full (total against free storage), Not checking in (Intune's last sync time), OS behind, Battery wearing out (for devices whose record carries a battery health percentage), Disk not encrypted (Intune's encryption flag: BitLocker on Windows, FileVault on a Mac), and Warranty expiring and Support ending when the asset has those dates. Intune has no warranty or support-end field, so those two come from an import or the asset page. Not enrolled doesn't apply to Intune devices.

Disconnect#

Select Disconnect under Connection, or use the row's menu on Admin › Account › Integrations, and confirm. Syncing stops and the stored Microsoft tokens are cleared, along with this page's settings (matching and field mapping), so reconnecting starts from the defaults. Your assets stay, with every detail already synced onto them, and each device's MDM section keeps its last record. Its organization stops counting for Microsoft sign-in, unless you've also added it under Microsoft organizations. Nothing changes in Intune. Disconnecting doesn't withdraw your organization's approval: to revoke schoolOS's access for good, also remove the schoolOS app, or its permissions, under Enterprise applications in the Microsoft Entra admin center. See Disconnect an integration.

Troubleshooting#

• "The Microsoft sign-in expired, or started before the latest settings. Try connecting again." The sign-in link was finished by someone other than the person who started it, after their schoolOS session ended, or after the setup page's settings changed. Start again from the setup page, signed in.
• "Microsoft Intune wasn't approved." The account declined, or can't approve permissions for the whole organization. Sign in with a Global Administrator or Privileged Role Administrator and accept.
• "The permissions weren't approved for your whole organization." Microsoft sent back an approval for one person rather than the organization. A Global Administrator needs to accept.
• "The approval came back for a different Microsoft organization than the one you signed in to." The sign-in and the approval were made in two different Microsoft organizations, often with two accounts open in one browser. Sign out of the other account and connect again.
• "Microsoft approved schoolOS, but it still can't read your Intune devices." Your organization has no Intune subscription, or the approval was later edited to drop reading managed devices. Check both in the Microsoft Entra admin center and connect again.
• The sync fails with "Microsoft no longer lets schoolOS read this district's Intune devices." An administrator removed the schoolOS app or its approval from your Microsoft organization. Reconnect.
• The sync fails with "The saved OAuth token was revoked or expired. Disconnect and reconnect this integration." Only a connection made before organization-wide connections: the connected account's password changed with sessions revoked, the account was disabled, or the consent was removed. Select Reconnect to switch to an organization-wide connection.
• "The connected account does not have the required device read permissions." The approval no longer covers reading Intune devices or, for a connection made before organization-wide connections, the account lost its Intune role. Reconnect with a Global Administrator.
• Approve device actions in Microsoft stays after approving. Microsoft can take a few minutes to apply it; open the page again later. If it stays for more than an hour, check the schoolOS app under Enterprise applications in the Microsoft Entra admin center: both permissions should show Granted for your organization.
• An Intune action fails with "Microsoft refused it: check that your organization approved device actions for schoolOS." The permission was removed in Microsoft after device management was turned on. Select Approve in Microsoft under Device management.
• An Intune action is grayed out on a device. Its platform doesn't support it, or Intune reported the device isn't supervised or is personally owned. The reason is beside the button.
• "Intune device actions need database migration 424." Your schoolOS hasn't finished an update. Ask schoolOS support.
• Assigned To (Email) is empty on a device that has a primary user. The user's principal name isn't an email address and Intune has no separate email for them. Map User Principal Name to a custom text field if you want it anyway.
• Deployed Date didn't change after a re-enrollment. By design: it fills only while empty. Clear it on the asset to let the next sync fill it again.
• A Windows laptop shows No real serial. Its firmware reports a placeholder. It's matched and tracked by its Intune device ID; nothing to fix unless you want to type the real serial on the asset.
• A device in Intune isn't in schoolOS. This connection doesn't create assets. Import the device, with its serial or its name as the asset tag, and the next sync links it.
• "A sync is already queued or running." One sync at a time per connection; Sync now waits for it instead of starting another.
• Sync now says it's still running after 30 minutes. The page stopped watching, not the sync. Refresh later; Last sync shows its result.