Jamf Connector

Overview

Reads Apple device inventory from Jamf Pro into Xurrent using the Jamf Pro API. Macs and mobile devices are separate resources in Jamf with different schemas, so this connector exposes them as two independent actions plus a small lookup for site names.

Prerequisites

• A Jamf Pro tenant, either Jamf Cloud (https://your-tenant.jamfcloud.com) or an on-premises Jamf Pro host.
• An API Role and an API Client. In Jamf Pro go to Settings > System > API Roles and Clients. Create the API role first, then create the API client and assign that role to it.
• The API role needs these privileges: Read Computers, Read Mobile Devices and Read Sites.
• From the API client, take the Client ID shown on the client, and use the separate Generate client secret button for the secret. The secret is displayed once and cannot be retrieved later.

Authentication

Fill in three fields when you create the connection.

The connection test calls Jamf and reports the Jamf Pro version it reached, so a wrong URL or a bad secret is visible before any runbook runs.

Triggers

None. This connector is outbound only.

Actions

Fetch Computer Inventory

Returns Mac inventory records from GET /api/v4/computers-inventory, one page per invocation. Re-invoke while has_next_page is true.

Use case: the extract step of a CMDB synchronization for Macs. Pair it with Fetch Mobile Device Inventory to cover the whole Apple fleet.

Permissions required: Read Computers

Input Parameters

Output

Operational notes

• Jamf returns -1 in numeric hardware fields to mean "unknown", not zero. On a sample tenant hardware.coreCount was -1 on 110 of 111 computers. Guard nrOfCores, nrOfProcessors and ramAmount in the runbook before writing them.
• purchasing.lifeExpectancy uses 0 for unknown rather than -1, and purchasing.purchasePrice is a decimal string such as "2899.00", not a number.
• general.site is {"id": "-1", "name": "None"} when no site is assigned. Treat id == "-1" as unassigned rather than resolving it.
• general.lastContact can be null on every computer in a tenant while general.reportDate is populated. Fall back to reportDate for both status and last-seen.
• hardware.serialNumber is frequently empty. Use general.managementId as the stable identifier.

Fetch Mobile Device Inventory

Returns iPhone, iPad, Apple TV, Apple Watch and Vision Pro inventory from GET /api/v2/mobile-devices/detail, one page per invocation.

Use case: the extract step of a CMDB synchronization for mobile devices.

Permissions required: Read Mobile Devices

Input Parameters

Output

Same envelope as Fetch Computer Inventory. results carries the union of all device-type shapes.

Operational notes

• device_type tells you which shape a record has. Jamf documents iOS, tvOS, watchOS and visionOS, and also returns Unknown for devices it cannot classify. Branch on it.
• Sections that do not apply to a device type are either null or absent from the record. Apple TVs carry no security or network, Apple Watches carry no purchasing. Read every section defensively.
• hardware.model and hardware.modelIdentifier can be empty strings rather than null. An empty string is truthy in Ruby, so use .presence when falling back to a default.
• general.siteId is an id with no name attached. Use Fetch Sites to resolve it. userAndLocation.departmentId and buildingId use "-1" for unassigned.
• deviceOwnershipType has no Personal value. The BYOD enrollment types are UserEnrollment and AccountDrivenUserEnrollment, and the field cannot be filtered server-side, so exclude BYOD devices in the runbook.
• Mobile devices expose no RAM and no processor fields at all.

Fetch Sites

Returns every Jamf site from GET /api/v1/sites in a single call.

Use case: build an id to name lookup so mobile device records, which carry general.siteId and no site name, can be given a location.

Permissions required: Read Sites

Input Parameters

None.

Output

Operational notes

• This endpoint takes no paging parameters, so it always returns every site in one response, however many the tenant has. The count is logged.
• An empty list is a normal answer and means no sites are configured. Treat it as "no location available", not as an error.

Rate Limiting and Error Handling

Jamf does not publish rate limit numbers, and Jamf Cloud throttles at the load balancer. On 429 or 503 the connector waits for the interval in the Retry-After header, or 60 seconds when the header is absent, then retries. On 401 or 403 the job fails immediately, because a credential or privilege problem does not improve on retry. 500, 502 and 504 also fail immediately, since a Jamf-side error is not fixed by asking again.

Best Practices

• Always pass sections explicitly, or accept the default. Jamf returns only the GENERAL section when the parameter is missing, which is the most common way a Jamf integration silently loses data.
• Keep updated_since and sections identical for every page of one run. Changing them mid-run changes the underlying result set, and the connector fails the job rather than page into a different list.
• Pair incremental runs with a periodic full run. Jamf's filtering excludes records whose filter field is null, so a device that has never reported never matches an incremental query.
• Leave exception_handling on LENIENT for scheduled syncs. Switch to STRICT only when you are diagnosing a specific device, because it stops the whole page.
• Call Fetch Sites once per run and cache the result. Site names change rarely.

Common Use Cases

• Nightly full synchronization of Macs and mobile devices into the Xurrent CMDB as discovered configuration items.
• Hourly incremental synchronization using updated_since to pick up only devices that reported since the previous run.
• Reporting on OS versions, disk encryption state, or warranty expiry across an Apple fleet.
• Finding devices that have stopped checking in, by comparing general.reportDate against the current time.

References

• Jamf Pro API overview explains authentication, paging, sorting and filtering across the whole API.
• Obtain an access token using an API Client documents the client credentials exchange this connector uses.
• API Roles and Clients walks through creating the role and client in the Jamf Pro interface.
• Filtering with RSQL covers the filter grammar behind updated_since, including which fields each endpoint allows.
• Return paginated Computer Inventory records and Return paginated Mobile Device Inventory records are the reference pages for the two inventory actions.
• Your own tenant serves its exact API contract at https://your-tenant.jamfcloud.com/api/schema, which is the most reliable description of what your Jamf version returns.