Class: Jamf::DeviceEnrollment

Inherits:
OAPISchemas::DeviceEnrollmentInstance show all
Includes:
CollectionResource
Defined in:
lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb

Overview

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

Constant Summary collapse

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.

Jamf::OAPISchemas::DeviceEnrollmentInstanceSearchResults
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.

Jamf::OAPISchemas::DeviceEnrollmentToken
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

Jamf::OAPISchemas::DeviceEnrollmentInstance
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

'v1/device-enrollments'.freeze
POST_PATH = 
"#{LIST_PATH}/upload-token".freeze
PUB_KEY_PATH_SUFFIX = 
'public-key'.freeze
DEVICES_PATH_SUFFIX = 
'devices'.freeze
SYNCS_PATH_SUFFIX = 
'syncs'.freeze
LATEST_PATH_SUFFIX = 
'latest'.freeze
DISOWN_PATH_SUFFIX = 
'disown'.freeze
TYPES = 
%i[computers mobiledevices].freeze
COMPUTERS_RE = 
/mac/i.freeze
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!

%i[name].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#cnx ⇒ Jamf::Connection (readonly) Originally defined in module JPAPIResource

Returns the API connection thru which we deal with this resource.

Returns:

  • (Jamf::Connection) —

    the API connection thru which we deal with this resource.

#delete_path ⇒ String (readonly) Originally defined in module CollectionResource

Returns The path for deleting a this item from the collection in the JPAPI.

Returns:

  • (String) —

    The path for deleting a this item from the collection in the JPAPI

#get_path ⇒ String (readonly) Originally defined in module JPAPIResource

Returns The path for fetching this thing from the JPAPI

this gets set in the constructor in the CollectionResource or SingletonResource mixins.

Returns:

  • (String) —

    The path for fetching this thing from the JPAPI

    this gets set in the constructor in the CollectionResource or SingletonResource mixins

#post_path ⇒ String (readonly) Originally defined in module CollectionResource

Returns The path for creating a new item in the collection in the JPAPI.

Returns:

  • (String) —

    The path for creating a new item in the collection in the JPAPI

#update_path ⇒ String (readonly) Originally defined in module JPAPIResource

Returns The path for updating this thing from the JPAPI

this gets set in the constructor in the CollectionResource or SingletonResource mixins

We use ‘update_path’ because some items are updated via a PUT_PATH and others via a PATCH_PATH. When this gets set, it will contain the appropriate one.

Returns:

  • (String) —

    The path for updating this thing from the JPAPI

    this gets set in the constructor in the CollectionResource or SingletonResource mixins

    We use ‘update_path’ because some items are updated via a PUT_PATH and others via a PATCH_PATH. When this gets set, it will contain the appropriate one.

Class Method Details

.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx) ⇒ Jamf::DeviceEnrollmentDevice?

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

in which to look for the sn. All instances are searched if omitted.

Parameters:

  • instance_ident (String, Integer) —

    the name or id of the instance

  • refresh (Boolean) (defaults to: false) —

    re-read the data from the API?

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use

Returns:

  • (Jamf::DeviceEnrollmentDevice, nil) —

    the device as known to DEP



224
225
226
227
228
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 224

def self.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx)
  sn.upcase! # SNs from apple are always uppercase
  devs = devices(instance, refresh: refresh, cnx: cnx)
  devs.select { |d| d.serialNumber == sn }.first
end

.device_sns(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<String>

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

See .devices

Returns:

  • (Array<String>) —

    just the serial numbers for the devices



174
175
176
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 174

def self.device_sns(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
  devices(instance, type: type, refresh: refresh, cnx: cnx).map(&:serialNumber)
end

.devices(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::OAPISchemas::DeviceEnrollmentDevice>

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

Parameters:

  • instance (Integer, String) (defaults to: nil) —

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

  • type (Symbol) (defaults to: nil) —

    Either :computers or :mobiledevices, returns both if not specified.

  • refresh (Boolean) (defaults to: false) —

    re-read the data from the API?

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use

Returns:

Raises:

  • (ArgumentError) 


154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 154

def self.devices(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
  raise ArgumentError, "Type must be one of: :#{TYPES.join ', :'}" if type && !TYPES.include?(type)

  devs = fetch_devices(instance, refresh, cnx)
  return devs unless type

  if type == :computers
    devs.select { |d| d.model =~ COMPUTERS_RE }
  else
    devs.reject { |d| d.model =~ COMPUTERS_RE }
  end
end

.devices_with_status(status, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::DeviceEnrollmentDevice>

See .devices

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

Parameters:

  • status (String) —

    A member of Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS

Returns:

  • (Array<Jamf::DeviceEnrollmentDevice>) —

    The devices with the desired status, associated with the given, or all, instances

Raises:

  • (ArgumentError) 


202
203
204
205
206
207
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 202

def self.devices_with_status(status, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
  statuses = Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS
  raise ArgumentError, "profileStatus must be one of: '#{statuses.join "', '"}'" unless statuses.include? status

  devices(instance, type: type, refresh: refresh, cnx: cnx).select { |d| d.profileStatus == status }
end

.disown(*sns, from_instance:, cnx: Jamf.cnx) ⇒ Hash

disown one or more serial numbers from a given DeviceEnrollment instance

Parameters:

  • sns (String, Array<String>) —

    One or more serial numbers to disown

  • from_instance (Integer, String) —

    the id or name of the instance from which to disown the serial numbers

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use

Returns:

  • (Hash) —

    The SNs as keys and ‘SUCESS’ or ‘FAILED’ as values

Raises:



276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 276

def self.disown(*sns, from_instance:, cnx: Jamf.cnx)
  instance_id = valid_id from_instance, cnx: cnx
  raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id

  sns.flatten!
  sns.map!(&:to_s)
  data = { devices: sns }

  disown_path = "#{get_path}/#{instance_id}/#{DISOWN_PATH_SUFFIX}"
  resp = Jamf::OAPISchemas::DeviceEnrollmentDisownResponse.new cnx.jp_post(disown_path, data)

  resp.devices
end

.include?(sn, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx) ⇒ Boolean

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

See .devices

or in DEP at all?

Parameters:

  • sn (String) —

    the serialNumber to look for

Returns:

  • (Boolean) —

    is the given SN in a given DeviceEnrollment instance



188
189
190
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 188

def self.include?(sn, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
  device_sns(instance, type: type, refresh: refresh, cnx: cnx).j_ci_include? sn
end

.sync_history(instance = nil, latest: false, cnx: Jamf.cnx) ⇒ Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus, Array<JJamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus>

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

Parameters:

  • instance (Integer, String) (defaults to: nil) —

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

  • latest (Boolean) (defaults to: false) —

    show only the latest sync? Only valid when an instance is provided.

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use

Returns:



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 246

def self.sync_history(instance = nil, latest: false, cnx: Jamf.cnx)
  if instance
    instance_id = valid_id instance, cnx: cnx
    raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance

    path = "#{get_path}/#{instance_id}/#{SYNCS_PATH_SUFFIX}"
    path += "/#{LATEST_PATH_SUFFIX}" if latest
  else
    path = "#{get_path}/#{SYNCS_PATH_SUFFIX}"
    latest = false
  end

  data = cnx.jp_get path

  return Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new data if latest

  data.map! { |s| Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new s }
end

Instance Method Details

#delete ⇒ Object Originally defined in module CollectionResource

Raises:

#device_sns(type: nil, refresh: false) ⇒ Object 



332
333
334
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 332

def device_sns(type: nil, refresh: false)
  devices(type: type, refresh: refresh).map(&:serialNumber)
end

#devices(type: nil, refresh: false) ⇒ Object

Instance Methods



328
329
330
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 328

def devices(type: nil, refresh: false)
  self.class.devices @id, type: type, cnx: @cnx, refresh: refresh
end

#devices_with_status(status, type: nil, refresh: false) ⇒ Object 



340
341
342
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 340

def devices_with_status(status, type: nil, refresh: false)
  self.class.devices_with_status(status, @id, type: type, refresh: refresh, cnx: @cnx)
end

#disown(*sns) ⇒ Object 



352
353
354
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 352

def disown(*sns)
  self.class.disown sns, from_instance: @id, cnx: @cnx
end

#exist? ⇒ Boolean Originally defined in module CollectionResource

Returns:

  • (Boolean)

#include?(sn, type: nil, refresh: false) ⇒ Boolean

Returns:

  • (Boolean) 


336
337
338
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 336

def include?(sn, type: nil, refresh: false)
  device_sns(type: type, refresh: refresh).j_ci_include? sn
end

#initialize(**data) ⇒ Object Originally defined in module CollectionResource

Constructor

#latest_sync ⇒ Object 



348
349
350
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 348

def latest_sync
  sync_history latest: true
end

#pretty_print_instance_variables ⇒ Array Originally defined in module JPAPIResource

Remove large cached items from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables

#save ⇒ Object Originally defined in module JPAPIResource

TODO: error handling

Raises:

#sync_history(latest: false) ⇒ Object 



344
345
346
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 344

def sync_history(latest: false)
  self.class.sync_history(@id, latest: latest, cnx: @cnx)
end

#to_s ⇒ String Originally defined in module CollectionResource

A meaningful string representation of this object

Returns: