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



206
207
208
209
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 206

def self.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx)
  devs = devices(instance, refresh: refresh, cnx: cnx)
  devs.select { |d| d.serialNumber.casecmp? 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



156
157
158
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 156

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) 


136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 136

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) 


184
185
186
187
188
189
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 184

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:



257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 257

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



170
171
172
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 170

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:



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 227

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 



313
314
315
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 313

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

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

Instance Methods



309
310
311
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 309

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 



321
322
323
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 321

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 



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

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) 


317
318
319
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 317

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 



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

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 



325
326
327
 
# File 'lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb', line 325

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: