Apple Business Manager Integration

OVERVIEW

 Watchman Monitoring's Apple Business Manager integration adds purchase, warranty, and MDM enrollment details from Apple to the Macs you already monitor. It connects directly to Apple Business Manager (or Apple School Manager) using Apple's API, and syncs every hour. Nothing is installed on the Macs.

 This integration enriches existing computers — it does not create them. Macs are matched to your existing records by serial number, so a Mac must already be running the Watchman Monitoring agent to receive Apple's data. Macs that are in Apple Business Manager but have no agent are listed separately, so you can see what you are not yet monitoring.

 WHAT GETS SYNCED

 AppleCare and Warranty Coverage

 - Coverage type (AppleCare or Limited Warranty), start and end dates
 - Apple's own coverage status, including plans Apple has cancelled before their end date
 - Agreement number and payment type
 - Coverage appears on the Mac's page and in the existing warranty expiration notices

 MDM Enrollment

 - Whether the Mac is assigned to an MDM server in Apple Business Manager
 - The name and type of the assigned MDM server
 - Macs assigned to Apple Configurator rather than a third-party MDM are identified as such
 - Macs present in Apple Business Manager but assigned to no MDM are flagged as Not enrolled

 Purchase Details

 - Order number and order date
 - Purchase source (Apple, or the reseller the Mac came from)
 - Part number
 - Date the Mac was added to your Apple Business Manager organization

 Hardware Configuration

 - Model name as Apple describes it (for example, "MacBook Pro (16-inch, 2023)")
 - Color and storage capacity
 - Product type

 Reports

 - Macs enriched by this connection — every Mac this connection matched
 - Purchase report — your Macs grouped by where they were bought, most common first
 - Macs in Apple Business Manager with no Watchman Monitoring agent — devices Apple knows about that you are not monitoring

 ABM fields are also available as columns in the Computers CSV export.

 HOW IT WORKS

 Each connection syncs automatically every hour. Watchman Monitoring requests your organization's device list from Apple, matches Mac serial numbers against the Macs already in your account, and writes Apple's data onto those records.

 The integration only ever adds Apple-sourced fields. It does not touch anything the Mac's agent owns — name, operating system, serial number, or check-in status — so an Apple Business Manager sync can never make a Mac look like it has reported in when it has not.

 AppleCare coverage is handled separately from the rest of the sync. Apple rate-limits coverage lookups heavily, and coverage dates change on the order of years, so each Mac's coverage is refreshed at most once every 24 hours, up to 100 Macs  per sync, least-recently-checked first. A fleet larger than that still works through itself over successive syncs. The hourly device sync is unaffected.

 This integration does not create plugin alerts. On-device MDM enrollment is already reported by the MDM Enrollment plugin, which sees the actual state of the Mac. What Apple Business Manager adds is the purchase and warranty record, and visibility of Macs that have no agent at all.

 CONFIGURATION GUIDE

 Prerequisites

 Before setting up the integration, you will need:

 - An Apple Business Manager or Apple School Manager account
 - The Organization Administrator role in Apple Business Manager — only that role can create an API account
 - Macs already reporting to Watchman Monitoring — this integration enriches existing computers rather than adding new ones

 Step 1: Create an API account in Apple Business Manager

 1. Sign in to Apple Business Manager at https://business.apple.com (or Apple School Manager at https://school.apple.com) as an Organization Administrator
 2. Go to Settings → API
 3. Select Add API Account, name it, and choose a role. Device Enrollment Manager is enough, and is the least access this integration can work with
 4. Choose Generate & Download to get the private key, a .pem file. Apple only offers this once — save it somewhere safe
 5. Select Edit on the API account to copy the Client ID (it looks like BUSINESSAPI.00000000-0000-0000-0000-000000000000) and the Key ID

 Step 2: Add the connection in Watchman Monitoring

 1. Sign in to your Watchman Monitoring dashboard
 2. Navigate to Integrations → Apple Business Manager
 3. Click Connect an Apple Business Manager
 4. Fill in the form:

    Connection Name: A label for you, so you can tell connections apart. Usually the client's name.

    Apple Service: Apple Business Manager, or Apple School Manager for schools.

    Client ID: From Step 1.

    Key ID: From Step 1. This is not inside the .pem file.

    Private Key (.pem): Upload the file you downloaded from Apple. If you cannot upload it, paste the contents into the field below instead. The key is encrypted when stored and is never displayed back.

    Enabled: Check this to start syncing.
 5. Click Connect

 Step 3: Verify

 1. Use Test Connection to confirm the credentials work
 2. Use Sync Now to run the first sync immediately rather than waiting for the hour
 3. Check Sync Information for the last sync time, device count, and status
 4. Review Macs enriched by this connection to confirm your Macs matched

 Refreshing a single Mac

 A Mac's page has a Refresh from Apple… action, which fetches that Mac's current warranty and enrollment details on demand. Only that computer is updated.

 MULTIPLE CONNECTIONS

 You can add more than one connection per company — typically one per client's Apple Business Manager organization. Each syncs independently and needs its own API account and key. Client IDs must be unique within a company.

 A connection is not tied to a group. One Apple Business Manager organization can enrich Macs across several groups, and an enriched Mac stays in whatever group it was already in.

 TROUBLESHOOTING

 Test Connection fails

 - Confirm the Client ID and Key ID were copied in full, with no extra spaces
 - Confirm the private key is the .pem file Apple issued for this API account. Apple issues an EC key; an RSA key or a mismatched key will be rejected
 - Confirm you chose the right service — an Apple School Manager account will not authenticate against Apple Business Manager

 No Macs matched

 - Matching is by serial number, so the Mac must already be reporting to Watchman Monitoring
 - Macs with no agent appear under Macs in Apple Business Manager with no Watchman Monitoring agent rather than being matched
 - iPhones, iPads, and other non-Mac devices are not matched, and appear in that same list

 Warranty information is missing or has not changed

 - Coverage is refreshed at most once every 24 hours per Mac, and up to 100 Macs per sync. On a large fleet the first pass takes several syncs to complete
 - Use Refresh from Apple… on the Mac's page to fetch that one Mac immediately
 - Not every Mac has coverage on record with Apple

 A warranty entry was not replaced

 - Manually overridden warranty entries are left alone by design
 - Warranty entries from other sources are never modified or removed. Only entries this integration created are updated

 The connection was disabled on its own

 - A credential or configuration problem disables the connection and sends an email. Correct the credentials and re-enable it
 - Temporary problems reaching Apple do not disable the connection. An email is sent after three consecutive failures, and periodically after that if the failures continue
 - The connection page shows the current sync status and the last error message

 FREQUENTLY ASKED QUESTIONS

 Q: Does this add computers to my account?
 A: No. It only adds information to Macs already reporting to Watchman Monitoring. Macs in Apple Business Manager without an agent are listed for your reference, but no computer record is created.

 Q: Do I need to install anything on the Macs?
 A: Nothing beyond the Watchman Monitoring agent they already need.

 Q: How often does it sync?
 A: Device, enrollment, and purchase data sync every hour. AppleCare coverage refreshes at most once every 24 hours per Mac, up to 100 Macs per sync. Sync Now runs a sync immediately.

 Q: Does this work with Apple School Manager?
 A: Yes. Choose Apple School Manager as the Apple Service when adding the connection.

 Q: Will this affect my existing warranty entries?
 A: No. The integration only updates warranty entries it created. Entries from other sources, and any entry you have manually overridden, are left alone.

 Q: Does it monitor iPhones and iPads?
 A: Not currently. Non-Mac devices in your Apple Business Manager organization appear in the list of devices with no agent, but are not matched or enriched.

 Q: Can an Apple Business Manager sync make a Mac look like it checked in?
 A: No. The sync never writes the fields the agent owns, including last report time and reporting status.

 Q: Does it raise alerts?
 A: It does not create plugin alerts. AppleCare expiration dates feed the warranty expiration notices you already receive. On-device MDM enrollment is reported separately by the MDM Enrollment plugin.

 Q: Will my Macs move groups?
 A: No. A connection is not tied to a group, and enriched Macs stay where they are.

 Q: Is my private key secure?
 A: The key is encrypted at rest and is never displayed back after it is saved. Communication with Apple is over HTTPS. If you generate a new key in Apple Business Manager, upload it to replace the stored one.

 Q: What if two Macs have the same serial number?
 A: Duplicate serial numbers happen with re-enrolled or rebuilt machines. Apple's data is applied to the most recently reporting of the matching records.