Jamf Pro

Jamf Pro holds the inventory of every Apple device enrolled in it: a Mac's model, chip, storage, FileVault state and last inventory report; an iPad's model, OS, supervision and carrier; who each is assigned to in Jamf, its site, and the purchasing details Jamf keeps. Connecting it to schoolOS reads all of that into schoolAssets and keeps it current, and, if you choose two-way, sends what schoolOS owns (the asset tag, the assigned person, the room, the purchase order) back onto the Jamf record so nobody types it twice.

What the connection does:

• Brings Apple devices in. Every Mac, iPad, iPhone, Apple TV and Apple Watch in both Jamf inventories (computers and mobile devices) is matched to an asset you already have, or set aside when there's no match.
• Keeps them current. A sync runs every night and reads everything; Sync now runs one on demand. Each Jamf field lands in the schoolOS field you map it to.
• Sends details back, on a two-way connection. The rows you set to push are written onto the Jamf record at the end of each sync, and never blank anything there.
• Feeds Device Health. Disk space, FileVault, battery health, management status and last contact drive the Device Health checks for Jamf devices.
• Sends device commands. From a device's page: update inventory, lock, restart, shut down, Lost Mode, Recovery Lock and erase, within what Apple allows on that device.

Jamf is different from the other device managers in one way that shapes everything below: each district runs its own Jamf Pro server, so you give schoolOS the server's address and a sign-in you create in Jamf, and the privileges you grant that sign-in are the only limit on what schoolOS can do there.

You need Manage integrations to connect it or change its settings, and Update assets to send a device command.

The API role#

Jamf's recommended way to let another system in is an API client: a client ID and secret bound to an API role that holds only the privileges you list. It isn't tied to a person, so it survives staff changes and password policy. In Jamf Pro, under Settings › API Roles and Clients:

1. Create an API role and grant it exactly these privileges:
   • Read Computers
   • Read Mobile Devices
   • Read Computer Extension Attributes
   • Read Mobile Device Extension Attributes
   • Read Sites
   • For a two-way connection, also Update Computers and Update Mobile Devices.
   • For each device command you'll use, its own Send ... Command privilege, listed in the commands table on the setup page.
2. Create an API client assigned to that role, enable it, and generate its client secret. Jamf shows the secret once; keep it until you've connected.

The setup page lists the privileges for the access mode you pick, so you can check them off. Jamf has no consent screen: a privilege you forgot shows up only as a refusal partway through a sync (see Troubleshooting), so grant them before you connect. Read Sites is the one you can do without: devices still sync, just without their Jamf site.

A Jamf Pro username and password works too, as a fallback. The connection then inherits everything that user can do, and stops working the moment their password expires or the account is disabled.

Connect#

1. Open Admin › Account › Integrations and select Jamf Pro.
2. Under Connection, enter the Server URL, like https://yourdistrict.jamfcloud.com. It must be https. You can paste the address out of your browser: a path, a trailing slash or /api on the end are dropped.
3. Under Sign in with, choose API client (recommended) and enter the Client ID and Client secret, or Jamf Pro username and password and enter the Username and Password.
4. Under What schoolOS may do, choose Read only or Two-way. See Which should I choose.
5. Check Grant exactly these privileges in Jamf against your API role, then select Connect.

schoolOS signs in to your server and reads its Jamf Pro version before it saves anything. If Jamf refuses, nothing is saved and the page shows Jamf's own message. Once connected, the page's badge reads Connected · Jamf Pro and the version, and the Connection section folds to the server URL and the access mode.

The secret or password is stored encrypted and never shown again. To change the server URL or the access mode later, edit it and select Save and test connection; leave the secret box blank to keep the stored one. Jamf issues no refresh token, so schoolOS signs in again with the stored sign-in whenever its token lapses. Rotating the client secret in Jamf, or changing the user's password, stops the sync until you paste the new one here.

Which should I choose: read only or two-way?#

Read only pulls devices and their inventory into schoolOS. Nothing is ever written to Jamf. Choose it when Jamf stays the place your team edits device records, or when the API role is shared and you'd rather it couldn't write. Two-way also pushes the schoolOS asset tag, assigned person, room and purchasing details onto the Jamf record on each sync. Only fields schoolOS has a value for are sent, so it can add detail to Jamf but never blanks it. Choose it when schoolOS is where you keep those details and you want Jamf's smart groups and reports to see them. You can switch later under Connection; two-way needs the two Update privileges on the role.

For example, a district with 2,400 iPads keeps purchase orders and asset tags in schoolOS, from its purchasing import, and wants Jamf's PO number and asset tag filled in so its Jamf reports match. It connects two-way with an API role that has the five read privileges and the two update privileges. After the first sync, every iPad's Jamf record carries the schoolOS asset tag and PO number.

The setup page#

Once connected, each section folds closed and shows its current setting. Every section has its own save button.

• Device sync. Last sync with its status and the run's summary: how many devices were fetched, skipped as unchanged, matched, created, sent for review, unmatched, skipped and failed, and on a two-way connection how many were written back to Jamf. 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.
• Asset identifier matching. See How a Jamf device is matched.
• Devices Jamf has that schoolOS doesn't. See below.
• Field mapping. Every field Jamf reports and where it lands. See Field mapping.
• Device commands. The commands schoolOS can send, with what each needs and the Jamf privilege it takes. See Device commands.

What syncs and when#

A sync runs on a schedule every night, and whenever you select Sync now. Jamf is read whole every time: its computers (the /v4/computers-inventory endpoint, with the General, Hardware, Operating System, User and Location, Purchasing, Storage, Security, Disk Encryption, Extension Attributes and Group Memberships sections) and its mobile devices (/v2/mobile-devices/detail, with General, Hardware, User and Location, Purchasing, Security, Network, Extension Attributes and Groups). Applications, package receipts and certificates aren't read: they'd turn a sync into a software inventory download and say nothing about the device. The two inventories are read side by side, and each is allowed to fail on its own, so a role that covers computers but not mobile devices still syncs its Macs.

A device whose Jamf 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 or a matching setting makes the next sync go over every device once.

For each device the sync:

1. Finds its asset, by its Jamf record and then by serial number (see below).
2. Links them. The asset's MDM section shows the Jamf record, with Last check-in from the last time the device contacted Jamf (for a Mac, Jamf's last contact time, else its report date; for a mobile device, its last inventory update). The record's Status is managed or unmanaged, from Jamf's remote management flag.
3. Writes the mapped pull rows onto the asset. If the asset has no asset tag, Jamf's asset tag fills it in.
4. Runs the Device Health checks on it.
5. At the end of the run, on a two-way connection, pushes the mapped push rows back to Jamf (see Two-way).

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

Field mapping#

Everything Jamf 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 Jamf's fields in its groups: Identity, Hardware, Operating System, User & Location, Purchasing, Management & Enrollment, Network, Security and Groups & Extension Attributes. A field that exists in only one inventory is marked computer only or mobile only. Search them, or filter by Group or by Sync (Pull into schoolOS, Push to Jamf, Off).

For each row, tick it to sync it, 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), and the arrow says which way the value travels: Pull (Jamf updates schoolOS) or Push (schoolOS updates Jamf). Push is offered only on the fields Jamf accepts a write for; the rest are marked Read only. There's no "both": one side owns each field. Reset to defaults puts every row back; Save field mapping saves.

Two identity fields aren't rows at all, because they're how the records find each other: schoolOS Device Reference (computer: or mobile: and the Jamf ID, the stored link) and Serial Number (matched serial to serial before any mapping is read). They're listed under Always matched first in the matching section.

A new connection starts with these rows on:

| Jamf field | schoolOS field | Direction to start | | --- | --- | --- | | Device Name | Name | Pull | | Make | Manufacturer | Pull | | Model | Model | Pull | | OS Name, OS Version (raw), OS Build (Mac) | OS Name, OS Version, OS Build | Pull | | OS Type, OS Build (mobile) | OS Name, OS Build | Pull | | Site | Location | Pull | | Last Inventory Report | Last Inventory Date | Pull | | Last IP Address (Mac) | Last WAN IP | Pull | | MAC Address (Mac), Wi-Fi MAC Address (mobile) | MAC Address | Pull | | Asset Tag | Asset Tag | Push | | Username, Real Name, Email Address | Assigned To (Username), Assigned To (Name), Assigned To (Email) | Push | | Room | Room | Push | | PO Number, PO Date, Vendor, Warranty Expiration, Purchase Price | PO Number, Purchase Date, Vendor, Warranty Expiration, Purchase Price | Push |

Worth knowing:

• The push rows start as Push, which means they aren't pulled. Jamf is treated as the source of truth for what a device is (model, OS, serial); schoolOS for what it's for (who has it, where, what it cost). On a read-only connection a Push row does nothing, so with the defaults, Jamf's asset tag, assigned user, room and purchasing aren't read into schoolOS. If Jamf is where your team records who has an iPad, switch the User & Location rows to Pull. See Which should I choose.
• Building and Department are read only here: writing them needs a Jamf building or department ID, which schoolOS location IDs aren't.
• Last IP Address is the public address the Jamf server last saw the device from; Last Reported IP is the device's own local address.
• Extension Attributes are your district's own Jamf fields. Map one by its full path, like extensionAttributes.0.values.0, to a custom field.
• Manufacturer, Model, Location, Room and Status 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: pull or push the person fields?#

| Where you assign devices | Set Username, Real Name, Email Address and Room to | Result | | --- | --- | --- | | In schoolOS (check-out, imports, a workflow) | Push, on a two-way connection | Jamf's User and Location fields follow schoolOS, so Jamf's smart groups can use them. | | In Jamf (at enrollment, or by your Jamf admin) | Pull | schoolOS's assignee follows Jamf. The asset's Assigned To fields are filled; the asset isn't checked out to a person. | | Nowhere consistent yet | Off | Nothing moves until you decide; everything Jamf reports still shows on the MDM section. |

How a Jamf device is matched#

The Jamf record is what tells devices apart: its reference is computer: or mobile: and the record's Jamf ID, and 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.

Asset identifier matching adds one more comparison for a device that still has no match: the schoolOS identifier (Serial Number to start with, or Asset Tag) against the Jamf field to match (Serial Number to start with; Asset Tag, UDID, schoolOS Device Reference, Barcode 1 or Barcode 2). It's the fallback when neither the reference nor the serial matched. A district that scans its asset tag into Jamf's Asset Tag or Barcode 1 field at enrollment sets Asset Tag ↔ Asset Tag or Asset Tag ↔ Barcode 1, so an iPad whose serial was mistyped on the purchase spreadsheet still finds its asset.

A re-enrolled device (a Mac wiped and enrolled again gets a new Jamf ID) takes over its asset's link only after a sync that read both inventories in full and didn't find the old ID. A sync where one inventory couldn't be read, or that stopped at the page cap (500 pages of 200), leaves the device in review instead.

Devices Jamf has that schoolOS doesn't#

What a sync does with a Jamf device that matches no asset. A device that matches is always updated.

• Create the asset. A Jamf device with no matching asset becomes a new schoolOS asset automatically.
• Queue it for review instead. Nothing is created until someone approves it. Turning on Create the asset turns this off.
• With both off, unmatched devices are counted in the sync's summary and skipped.

The page shows Queue it for review instead on when you first open it, but a new connection skips unmatched devices until you save this section. Select Save changes once to make your choice take effect.

Assets are never deleted when a device leaves Jamf. A device drops out of Jamf for reasons that have nothing to do with ownership: unenrolled for a repair, moved between sites, a filter changed. Deleting the asset would take its ticket history and purchase record with it. To retire assets, change their status in a workflow instead.

For example, a district receives 600 iPads, imports them from Apple School Manager the day they arrive, and enrolls them in Jamf the next week. Jamf matches each one by serial number and fills in its model, OS, site and last inventory, and on the two-way connection sends the PO number and asset tag back.

Two-way: what goes back to Jamf#

On a Two-way connection, the end of every sync writes the mapped push rows onto each linked Jamf record: the asset tag; the assigned person's username, real name, email, position and phone; the room; the PO number and date, vendor, warranty date, purchase price, AppleCare ID, life expectancy, purchasing account and contact, as you've mapped them. Only values schoolOS has are sent: a blank asset tag in schoolOS means "we don't know", never "erase what Jamf has". A device whose values haven't changed since schoolOS last pushed them is skipped, so the first run after you enable two-way is the big one; it writes up to 2,000 devices and leaves the rest for the next run, which the sync's summary reports as "queued for the next run". A write Jamf refuses is counted as failed and tried again next time; it never undoes the inbound half of the sync.

On a read-only connection nothing is written whatever a row says, and the field mapping section says so.

Workflows can write too: Set a Jamf field writes one of the same fields, copied from the asset or as a fixed value, on assets linked to a Jamf device on a two-way connection. On a read-only connection the Jamf Pro actions group is grayed out, and a rule saved earlier is skipped with the reason. See device actions in workflows.

Device commands#

The Device commands section lists what schoolOS can send to a Jamf-managed device, with what each applies to, what the device needs, and the Jamf privilege it takes. The same commands appear at the bottom of a device's MDM section on its page, in one row; each is explained when you hover it, and one the device can't take is disabled with the reason. Each opens a dialog that says what it does, sends it when you confirm, then reports whether Jamf queued it or refused it until you close it. Sending one needs Update assets.

| Command | What it does | Applies to | Needs | Jamf privilege | | --- | --- | --- | --- | --- | | Update Inventory | Asks the device to submit a fresh inventory report now. Harmless, and the first thing to try when schoolOS data looks stale. | Mac and mobile | Managed | Send Computer Remote Command to Update Inventory | | Lock Device | Locks it now. A Mac needs a six-digit PIN to unlock again; schoolOS shows the PIN once and saves it to the asset's timeline. | Mac and mobile | Managed | Send Computer Remote Lock Command | | Clear Passcode | Removes the passcode so the device can be handed to someone else. | Mobile | Managed | Send Mobile Device Remote Command to Clear Passcode | | Restart Device | Reboots it. | Mac and mobile | Managed, supervised | Send Computer Remote Command to Restart Device | | Shut Down Device | Powers it off. Nothing can wake it afterward; a later command waits until someone turns it on. | Mac and mobile | Managed, supervised | Send Computer Remote Command to Shut Down Device | | Enable Lost Mode | Locks a mislaid iPad or iPhone, shows a message and phone number, and starts location reporting. The dialog asks for the lock screen message (it starts with a standard "please return it to the school office" message) and an optional phone number; one of the two is required. | Mobile | Managed, supervised | Send Mobile Device Remote Command to Enable Lost Mode | | Disable Lost Mode | Returns it to normal use. | Mobile | Managed, supervised, in Lost Mode | Send Mobile Device Remote Command to Disable Lost Mode | | Play Lost Mode Sound | Sounds an alert to find it in a room. | Mobile | Managed, supervised, in Lost Mode | Send Mobile Device Remote Command to Play Lost Mode Sound | | Request Location | Asks a device in Lost Mode where it is. Apple allows locating a device only in Lost Mode. | Mobile | Managed, supervised, in Lost Mode | Send Mobile Device Remote Command to Request Device Location | | Set Recovery Lock | Sets the firmware recovery password on an Apple silicon Mac. schoolOS shows the password once and saves it to the timeline. Intel Macs use a firmware password, which this doesn't set. | Mac | Managed, Apple silicon | Send Computer Remote Command to Set Recovery Lock | | Erase Device | Wipes it to factory state. Everything on it is lost. If Activation Lock is on and the bypass code is unknown, the device may be unusable afterward. | Mac and mobile | Managed | Send Computer Remote Wipe Command |

Apple refuses several commands on unsupervised hardware, and Jamf accepts a refused command and then quietly drops it, so schoolOS judges each command against the device's last synced inventory before offering it: a condition it knows is unmet disables the command, a condition the device hasn't reported becomes a warning. Erase Device asks you to type ERASE and the asset tag first. Every command is queued with Jamf; a device that's off or offline gets it at its next check-in, so schoolOS reports commands as queued, not done, and the asset's timeline records it.

Jamf doesn't tell schoolOS which privileges the API role holds, so a command whose Send ... Command privilege isn't granted is accepted here and refused by Jamf with a 403, which the timeline records. Grant the privileges for the commands you'll use before you rely on them. The setup page lists the commands as off on a read-only connection; switch to Two-way when you grant them, so the connection says what it can do.

Workflows can send every one of these, each its own action in the builder's Jamf Pro actions group: Turn on Lost Mode (with your message, phone number and footnote), Turn off Lost Mode, Play the Lost Mode sound, Request its location, Lock the device (with an optional message), Restart, Shut down, Update inventory, Clear the passcode, Set Recovery Lock and Erase the device. They need a Two-way connection. A lock's PIN and the Recovery Lock password are generated and kept on the asset's timeline, as when you send them here, and only people with Update assets see them. Erase the device can't be undone, so the workflow asks first: the person whose change starts it sees the workflow's steps and types ERASE and the asset tag (or, for several devices, their number) before it runs. See device actions in workflows.

For example, a high school's iPad cart comes back one short. The tech opens the missing iPad's page, selects Enable Lost Mode with the front office's number, and the next time the iPad is online it locks and reports its location, which Request Location reads back.

Device Health#

Jamf devices get these Device Health checks: Disk nearly full (each partition's percent used, on Macs), Not checking in (the last inventory report), Not enrolled (a device Jamf reports as unmanaged while schoolOS has it deployed), OS behind, Battery wearing out (Jamf's battery capacity percent), Disk not encrypted (FileVault off), and Warranty expiring and Support ending when the asset has those dates. Map Warranty Expiration to pull if you want Jamf's warranty date to feed the warranty check.

Disconnect#

Select Disconnect under Connection, or use the row's menu on Admin › Account › Integrations, and confirm. Syncing stops and the saved sign-in is cleared, along with this page's settings (matching, new-device handling 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. Nothing changes in Jamf. To revoke schoolOS's access for good, disable or delete the API client in Jamf. See Disconnect an integration.

Troubleshooting#

• "Jamf Pro server URL must use https." Enter the address with https://, as Jamf Cloud requires.
• "Jamf API client authentication failed (HTTP 401)." The client ID or secret is wrong, the secret was rotated, or the API client is disabled in Jamf. Generate a new secret and paste it here.
• "Jamf authentication failed" on a username and password, especially with USER_EXPIRED_PASSWORD. The Jamf user's password expired or the account was disabled. Reset it, or move to an API client.
• The sync fails partway with HTTP 403. The API role is missing a privilege, usually Read Computer Extension Attributes or Read Mobile Device Extension Attributes. Jamf only reports it when the sync reaches that part. Add it to the role; no reconnect needed.
• Macs sync but iPads don't, or the reverse. One inventory's read privilege is missing. The sync keeps the inventory it could read and the log names the one that failed.
• Devices have no Location from their site. The role lacks Read Sites; mobile devices report only the site's ID, so without it there's no name to match.
• A command fails with a 403. "A 403 here is usually a missing 'Send ... Command' privilege on the Jamf API account." Grant the privilege the commands table names.
• "Jamf Pro did not report a management id … the device may not be MDM-enrolled." The device is in Jamf's inventory but isn't enrolled in MDM, so it can't take commands.
• A command was queued and nothing happened. The device is off, offline, or unsupervised (Jamf accepts and drops commands Apple refuses). Check the warnings the dialog showed, and Update Inventory once it's online.
• Jamf's assignee or purchasing isn't appearing in schoolOS. Those rows start as Push. Switch them to Pull under Field mapping.
• Nothing goes back to Jamf. The connection is read only, or the row is set to Pull, or schoolOS has no value for the field. The sync's summary says how many were written back.
• "Queued for the next run" in the sync summary. More than 2,000 devices had changed values to push; the rest go next time.