Mosyle

Mosyle manages the Apple devices in many districts: each iPad's or Mac's model, OS version, the user and location Mosyle assigns it, its enrollment status and when it last checked in. Connecting it to schoolOS reads every device Mosyle reports into schoolAssets and keeps it current, so an iPad's record in schoolOS matches the one in Mosyle without anyone retyping it.

What the connection does:

• Brings Apple devices in. Every device Mosyle lists is matched to an asset you already have. One that matches nothing is counted and left alone (see matching).
• Keeps them current. A sync runs every night and reads everything; Sync now runs one on demand. Each Mosyle field lands in the schoolOS field you map it to.
• Feeds Device Health. Last check-in and OS version drive the Device Health checks for Mosyle devices.

schoolOS only reads from Mosyle. Mosyle publishes no verified way to update device records, and a write-back that quietly did nothing would be worse than none, so there's no two-way mode and no device commands. Do those in the Mosyle admin console.

Mosyle is also the device manager that publishes the least about its API, and the setup page says so where it matters: the field mapping lists only the fields schoolOS reads for certain, and the rest of what Mosyle reports still shows on each device's MDM section.

You need Manage integrations to connect it or change its settings.

Which product: Mosyle Manager or Mosyle Business?#

Mosyle sells two products on two separate hosts with separate accounts: Mosyle Manager, the education product, and Mosyle Business, the commercial one. A token from one can't sign in to the other, so the setup page asks which you use rather than guessing. Mosyle Manager also signs in as a Mosyle admin, so for it the page asks for that admin's email and password too. Almost every school district runs Mosyle Manager; choose Mosyle Business only if your district bought the commercial product, which its sign-in page and admin console will say. The connection badge confirms which one answered: Connected · Mosyle Manager (education) or Connected · Mosyle Business.

Connect#

1. In your Mosyle admin console, create a dedicated admin for schoolOS, with permission to read devices and nothing more. schoolOS signs in as this admin and can do whatever it can, so don't use a person's own account or a full administrator.
2. Turn on the API and copy its access token. In Mosyle Manager that's under My School › API Integration; Mosyle's own API documentation inside the console says where it is for your product.
3. Open Admin › Account › Integrations and select Mosyle.
4. Under Connection, choose the Mosyle product: Mosyle Manager or Mosyle Business.
5. Paste the token into Access token. For Mosyle Manager, also enter the dedicated admin's Admin email and Admin password. Select Connect.

schoolOS signs in to that product's API and lists your devices before it saves anything, so a token for the wrong product, a wrong password, or an admin without device access fails here rather than on the first sync. If Mosyle refuses, nothing is saved and the page shows what to check. Once connected, Device sync shows What schoolOS can see: which product it's connected to and how many devices are available to import.

The token and the admin's password are stored encrypted and never shown again. To replace either later, enter the new one and select Save and test connection; leave a box blank to keep what's saved. With Mosyle Manager, schoolOS signs in as the admin for a session that lasts a day and signs in again on its own when it ends, so changing that admin's password in Mosyle means entering the new one here. Mosyle Business tokens carry their own expiry, which Mosyle doesn't report to schoolOS, so an expired one shows up as a sync failure with a message that says to generate a new one.

For example, a district with 5,400 iPads in Mosyle Manager creates a "schoolOS integration" admin in Mosyle with device read access, turns on the API, and enters the token and that admin's email and password on the setup page under Mosyle Manager. What schoolOS can see reads "Connected to Mosyle Manager (education), with 5,400 devices available to import."

The setup page#

Once connected, the Connection and Field mapping sections fold closed and show their current setting. Each has its own save button.

• Device sync. Last sync with the last run's summary (how many devices were fetched, skipped as unchanged, matched, created, sent for review, unmatched, skipped and failed), and What schoolOS can see. Sync now at the top queues a sync in the background; refresh the page later to see its result.
• Connection. Above. Disconnect is here too.
• Field mapping. Where each Mosyle field lands in schoolOS. See Field mapping.

There's no matching or new-device section on this page: Mosyle devices are matched by their device ID and serial number (see below), and a device that matches nothing is left alone.

What syncs and when#

A sync runs on a schedule every night, and whenever you select Sync now. Mosyle is read whole every time, page by page from its device list (Mosyle Manager lists iOS and iPadOS, macOS, tvOS and visionOS devices separately, so each is read in turn), until Mosyle's count is reached or a page adds nothing new. A device whose Mosyle 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 the sync's summary says how many were skipped as unchanged. Changing a field mapping makes the next sync go over every device once.

For each device the sync:

1. Finds its asset, by its Mosyle device ID and then by serial number.
2. Links them. The asset's MDM section shows the Mosyle record, with Last check-in from Mosyle's last beat and Status from its enrollment status.
3. Writes the mapped fields onto the asset. If the asset has no asset tag, Mosyle's asset tag fills it in.
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 Mosyle 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 fields schoolOS reads for certain, in five groups: Identity, Hardware, Operating System, User & Location and Management. Search them, or filter by Group or by Sync (Pull into schoolOS, Off). Every row is read only on Mosyle'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). A row with a suggested target that isn't chosen shows Default: and the field, with Use default. Save field mapping saves.

Two identity fields aren't rows: Device UDID (the Apple UDID, or the serial number when Mosyle reports no UDID; the stored link between the records) and Serial Number (matched serial to serial before any mapping is read).

A new connection starts with these rows on:

| Mosyle field | schoolOS field | | --- | --- | | Device Name | Name | | Asset Tag (Mosyle's own, when your district records one there) | Asset Tag | | Model | Model | | Manufacturer (Apple, unless Mosyle says otherwise) | Manufacturer | | OS Version | OS Version | | Assigned User (Email) | Assigned To (Email) | | Assigned User (Name) | Assigned To (Name) | | Location | Location | | Last Check-in | Last Inventory Date |

Worth knowing:

• Status (Mosyle's enrollment status) isn't mapped to start with: it isn't a lifecycle status. It still shows on the MDM section.
• 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.
• Mosyle reports more than this (storage, battery level, supervision, enrollment type, Wi-Fi and Bluetooth addresses, IMEI, grade, classes). schoolOS reads those defensively and shows what it finds on the MDM section, but doesn't offer them in the mapping until their field names are confirmed against a live Mosyle account: a row that could never fill in would be worse than none. They'll appear here once confirmed.

Which should I choose: map Mosyle's Location or not?#

Mosyle's Location is the location name Mosyle assigns the device (its grouping, in some setups). Keep it mapped to Location when those names are your buildings and match your schoolOS locations. If Mosyle's locations are carts, grades or classes, map the row to a custom text field instead, so the value is filterable without replacing the building your technicians set, or turn it off.

For example, a K-8 district keeps its 1,800 iPads in Mosyle Manager with the student's email as the assigned user and the school as the location. With the defaults, each iPad's asset shows the student under Assigned To, the school as its location, and Last Inventory Date from its last beat, and the Not checking in check lists the ones nobody has opened since June.

How a Mosyle device is matched#

The Mosyle device ID is what tells devices apart: the Apple UDID, or the serial number when Mosyle reports no UDID. Once linked, a device stays linked to its asset whatever its serial says. A serial number only finds the asset a not-yet-linked device belongs to, and only when that answer doesn't need a guess. The full rules, including re-enrollment and duplicate serials, are in How a device is matched. Mosyle has no asset identifier matching section: the comparison is always the device's serial against the asset's Serial Number. A device Mosyle reports with neither a UDID nor a serial can't be told apart from anything and is dropped from the sync.

A Mosyle device that matches no asset is counted as unmatched in the sync's summary and left alone: nothing is added to inventory, and there's no setting on this page to add or review new devices. Mosyle fills in devices you already have. To get Apple devices into schoolOS, import them from Apple School Manager, which has every Apple device you bought with its serial, or from a CSV; the next sync links 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 Mosyle: a device drops out for a repair or a wipe, and deleting the asset would lose its history.

Device Health#

Mosyle devices get these Device Health checks: Not checking in (Mosyle's last beat), OS behind, and Warranty expiring and Support ending when the asset has those dates. Disk nearly full and Battery wearing out also read Mosyle records, but the fields they look for (a percent of disk used and a battery health percentage) are among the ones not yet confirmed against a live account, so a device may show Not checked for them. Not enrolled and Disk not encrypted don't apply to Mosyle devices.

Disconnect#

Select Disconnect under Connection, or use the row's menu on Admin › Account › Integrations, and confirm. Syncing stops and the saved access token and admin sign-in are cleared, along with the 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. Nothing changes in Mosyle. To revoke schoolOS's access for good, delete the token and the schoolOS admin in the Mosyle admin console. See Disconnect an integration.

Troubleshooting#

• "Mosyle rejected the sign-in. Check the access token from the Mosyle admin console and, for Mosyle Manager, the admin's email and password, then save them here again." The token expired, was deleted, or belongs to the other product, or the admin's password changed. Check the Mosyle product choice, then enter the current token (and, for Mosyle Manager, the admin's email and password) and select Save and test connection.
• "Mosyle Manager needs the email and password of the Mosyle admin schoolOS signs in as." Enter the dedicated admin's Admin email and Admin password.
• "That Mosyle account does not have permission for this operation." The admin schoolOS signs in as can't read devices. Give it device read access in Mosyle.
• "Mosyle is rate limiting this account. The sync will resume shortly." Mosyle slowed schoolOS down. The sync retries on its own; nothing to do.
• "Could not reach Mosyle." A network problem between schoolOS and Mosyle's API. The next sync tries again.
• "Mosyle rejected the request method. This is a schoolOS bug, not a configuration problem." Report it to schoolOS support with the sync's time from Admin › Account › Logs.
• What schoolOS can see shows the product but no device count. Mosyle didn't report a total on the first page. The sync still reads every page.
• "Mosyle answered" followed by a status. Mosyle refused the request and said why; the words after the status are Mosyle's. Report it to schoolOS support with the sync's time from Admin › Account › Logs if it isn't about your account.
• A device in Mosyle isn't in schoolOS. This connection doesn't create assets. Import the device, with its serial number, and the next sync links it.
• A field Mosyle shows on the MDM section isn't in the field mapping. Its name hasn't been confirmed yet, so it can't be mapped. It's still visible on each device.