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 theLIST_PATH
if they follow the standards:-
GET_PATH = “#{LIST_PATH}/id”
-
fetch an object from the collection
-
-
-
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
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
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
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
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 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
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
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
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
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
# 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
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
# 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
# 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
# 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
# File lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb 347 def latest_sync 348 sync_history latest: true 349 end
# 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