class Jamf::DeviceEnrollment

A decvice enrollment defined in the Jamf Pro.

This is a connection to Apple’s Automated Device Enrollment Program. A single Jamf server may have many of them, and they can belong to different sites.

These objects can be used to find the details of all the devices connected to them, including the device serial numbers. To see how or if those devices are assigned to prestages, see Jamf::Prestage and its subclasses ComputerPrestage and MobileDevicePrestage

Constants

COMPUTERS_RE
DEVICES_PATH_SUFFIX
DISOWN_PATH_SUFFIX
LATEST_PATH_SUFFIX
LIST_PATH

The path for GETting the list of all objects in the collection, possibly filtered, sorted, and/or paged REQUIRED for all collection resources

GET_PATH, POST_PATH, PUT_PATH, PATCH_PATH, and DELETE_PATH are automatically assumed from the LIST_PATH if they follow the standards:

  • GET_PATH = “#{LIST_PATH}/id”

    • fetch an object from the collection

  • POST_PATH = LIST_PATH

    • create a new object in the collection

  • PUT_PATH = “#{LIST_PATH}/id”

    • update an object passing all its values back. Most objects use this or PATCH but not both

  • PATCH_PATH = “#{LIST_PATH}/id”

    • update an object passing some of its values back Most objects use this or PUT but not both

  • DELETE_PATH = “#{LIST_PATH}/id”

    • delete an object from the collection

If those paths differ from the standards, the constants must be defined here

NON_UNIQUE_IDENTIFIERS

Values which are useful as identifiers, but are not necessarily unique in the collection - e.g. more than one computer can have the same name WARNING When more than one item in the collection has the same value for one of these fields, which one is used, returned, selected, is undefined You Have Been Warned!

POST_OBJECT

The OAPI object class we send with a POST request to make a new member of the collection in Jamf. This is usually the same as the parent class.

POST_PATH
PUB_KEY_PATH_SUFFIX
PUT_OBJECT

The OAPI object class we send with a PUT request to change an object in Jamf by specifying all its values. Most updates happen this way, and this is usually the same as the parent class

SEARCH_RESULT_OBJECT

The OAPI object class we get back from a ‘list’ query to get the whole collection, or a subset of it. It contains a :results key which is an array of data for objects of the parent class.

SYNCS_PATH_SUFFIX
TYPES

Public Class Methods

device(sn, instance = nil, refresh: false, cnx: Jamf.cnx) click to toggle source

Fetch a single device from any defined DeviceEnrollment instance. The instance id containing the device is available in its .deviceEnrollmentProgramInstanceId attribute.

@pararm sn [String] the serial number of the device

@param instance_ident [String, Integer] the name or id of the instance in which to look for the sn. All instances are searched if omitted.

@param refresh [Boolean] re-read the data from the API?

@param cnx The API connection to use

@return [Jamf::DeviceEnrollmentDevice, nil] the device as known to DEP

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
224 def self.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx)
225   devs = devices(instance, refresh: refresh, cnx: cnx)
226   devs.select { |d| d.serialNumber.casecmp? sn }.first
227 end
device_sns(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) click to toggle source

The serial numbers assigned bu Apple to one, or all of your Device Enrollment instances

See .devices

@return [Array<String>] just the serial numbers for the devices

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
174 def self.device_sns(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
175   devices(instance, type: type, refresh: refresh, cnx: cnx).map(&:serialNumber)
176 end
devices(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) click to toggle source

All devices associated by Apple with a given DeviceEnrollment instance or all defined DeviceEnrollment instances.

This data is cached the first time it is read from the API, similarly to how CollectionResources are cached. To refresh the cache, pass a truthy value to the refresh: parameter, or use the Connection’s .flushcache method

@param instance[Integer, String] the id or name of the

DeviceEnrollment instance for which to list the devices. If omitted,
the devices for all instances will be returned.

@param type [Symbol] Either :computers or :mobiledevices, returns both if

not specified.

@param refresh [Boolean] re-read the data from the API?

@param cnx [Jamf::Connection] The API connection to use

@return [Array<Jamf::OAPISchemas::DeviceEnrollmentDevice>] The devices associated with

the given DeviceEnrollment instance, or all instances
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
154 def self.devices(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
155   raise ArgumentError, "Type must be one of: :#{TYPES.join ', :'}" if type && !TYPES.include?(type)
156 
157   devs = fetch_devices(instance, refresh, cnx)
158   return devs unless type
159 
160   if type == :computers
161     devs.select { |d| d.model =~ COMPUTERS_RE }
162   else
163     devs.reject { |d| d.model =~ COMPUTERS_RE }
164   end
165 end
devices_with_status(status, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) click to toggle source

See .devices

Returns just those devices with the desired profileStatus, which must be an item in Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS

@param status A member of Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS

@return [Array<Jamf::DeviceEnrollmentDevice>] The devices with the desired

status, associated with the given, or all,  instances
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
202 def self.devices_with_status(status, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
203   statuses = Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS
204   raise ArgumentError, "profileStatus must be one of: '#{statuses.join "', '"}'" unless statuses.include? status
205 
206   devices(instance, type: type, refresh: refresh, cnx: cnx).select { |d| d.profileStatus == status }
207 end
disown(*sns, from_instance:, cnx: Jamf.cnx) click to toggle source

disown one or more serial numbers from a given DeviceEnrollment instance

@param sns[String, Array<String>] One or more serial numbers to disown

@param from_instance [Integer, String] the id or name of the instance

from which to disown the serial numbers

@param cnx The API connection to use

@return [Hash] The SNs as keys and ‘SUCESS’ or ‘FAILED’ as values

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
275 def self.disown(*sns, from_instance:, cnx: Jamf.cnx)
276   instance_id = valid_id from_instance, cnx: cnx
277   raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id
278 
279   sns.flatten!
280   sns.map!(&:to_s)
281   data = { devices: sns }
282 
283   disown_path = "#{get_path}/#{instance_id}/#{DISOWN_PATH_SUFFIX}"
284   resp = Jamf::OAPISchemas::DeviceEnrollmentDisownResponse.new cnx.jp_post(disown_path, data)
285 
286   resp.devices
287 end
include?(sn, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) click to toggle source

Is the given serial number in one, or any, or your Device Enrollment instances?

See .devices

@param sn [String] the serialNumber to look for

@return [Boolean] is the given SN in a given DeviceEnrollment instance or in DEP at all?

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
188 def self.include?(sn, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
189   device_sns(instance, type: type, refresh: refresh, cnx: cnx).j_ci_include? sn
190 end
sync_history(instance = nil, latest: false, cnx: Jamf.cnx) click to toggle source

The history of sync operations between Apple and a given DeviceEnrollment instanace, or all instances.

@param instance [Integer, String] the id or name of the

DeviceEnrollment instance for which to get the history. If omitted,
the history for all instances will be returned.

@param latest [Boolean] show only the latest sync? Only valid when an

instance is provided.

@param cnx The API connection to use

@return [Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus] When latest = true, the latest

sync status.

@return [Array<JJamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus>] The known sync statuses.

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
245 def self.sync_history(instance = nil, latest: false, cnx: Jamf.cnx)
246   if instance
247     instance_id = valid_id instance, cnx: cnx
248     raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance
249 
250     path = "#{get_path}/#{instance_id}/#{SYNCS_PATH_SUFFIX}"
251     path += "/#{LATEST_PATH_SUFFIX}" if latest
252   else
253     path = "#{get_path}/#{SYNCS_PATH_SUFFIX}"
254     latest = false
255   end
256 
257   data = cnx.jp_get path
258 
259   return Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new data if latest
260 
261   data.map! { |s| Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new s }
262 end

Private Class Methods

devices_for_instance_id(instance_id, refresh, cnx) click to toggle source

Private, used by the .fetch_devices class method

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
310 def self.devices_for_instance_id(instance_id, refresh, cnx)
311   @device_cache ||= {}
312   @device_cache[cnx] ||= {}
313   @device_cache[cnx][instance_id] = nil if refresh
314   return @device_cache[cnx][instance_id] if @device_cache[cnx][instance_id]
315 
316   data =
317     Jamf::OAPISchemas::DeviceEnrollmentDeviceSearchResults.new(
318       cnx.jp_get("#{LIST_PATH}/#{instance_id}/#{DEVICES_PATH_SUFFIX}")
319     ).results
320   @device_cache[cnx][instance_id] = data
321 end
fetch_devices(instance = nil, refresh, cnx) click to toggle source

Private, used by the .devices instance method

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
293 def self.fetch_devices(instance = nil, refresh, cnx)
294   if instance
295     instance_id = valid_id instance, cnx: cnx
296     raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id
297 
298     devs = devices_for_instance_id instance_id, refresh, cnx
299   else
300     devs = []
301     all_ids.each do |id|
302       devs += devices_for_instance_id id, refresh, cnx
303     end
304   end
305   devs
306 end

Public Instance Methods

device_sns(type: nil, refresh: false) click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
331 def device_sns(type: nil, refresh: false)
332   devices(type: type, refresh: refresh).map(&:serialNumber)
333 end
devices(type: nil, refresh: false) click to toggle source

Instance Methods

    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
327 def devices(type: nil, refresh: false)
328   self.class.devices @id, type: type, cnx: @cnx, refresh: refresh
329 end
devices_with_status(status, type: nil, refresh: false) click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
339 def devices_with_status(status, type: nil, refresh: false)
340   self.class.devices_with_status(status, @id, type: type, refresh: refresh, cnx: @cnx)
341 end
disown(*sns) click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
351 def disown(*sns)
352   self.class.disown sns, from_instance: @id, cnx: @cnx
353 end
include?(sn, type: nil, refresh: false) click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
335 def include?(sn, type: nil, refresh: false)
336   device_sns(type: type, refresh: refresh).j_ci_include? sn
337 end
latest_sync() click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
347 def latest_sync
348   sync_history latest: true
349 end
sync_history(latest: false) click to toggle source
    # File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb
343 def sync_history(latest: false)
344   self.class.sync_history(@id, latest: latest, cnx: @cnx)
345 end