Class: Jamf::DeviceEnrollment

Inherits:
CollectionResource show all
Includes:
ChangeLog
Defined in:
lib/jamf/api/resources/collection_resources/device_enrollment.rb

Overview

A decvice enrollment defined in the Jamf Pro.

This is a connection to Apple’s 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

RSRC_VERSION =

Constants

'v1'.freeze
RSRC_PATH = 
'device-enrollments'.freeze
OBJECT_MODEL =

Object Model / Attributes See APIObject class documentation for details of how the OBJECT_MODEL hash works.

{

  # @!attribute id
  #   @return [String]
  id: {
    class: :j_id,
    identifier: :primary,
    readonly: true
  },

  # @!attribute name
  #   @return [String]
  name: {
    class: :string,
    identifier: true
  },

  # @!attribute supervisionIdentityId
  #   @return [String]
  supervisionIdentityId: {
    class: :j_id
  },

  # @!attribute siteId
  #   @return [String]
  siteId: {
    class: :j_id
  },

  # @!attribute serverName
  #   @return [String]
  serverName: {
    class: :string
  },

  # @!attribute serverUuid
  #   @return [String]
  serverUuid: {
    class: :string
  },

  # @!attribute adminId
  #   @return [String]
  adminId: {
    class: :string
  },

  # @!attribute orgName
  #   @return [String]
  orgName: {
    class: :string
  },

  # @!attribute orgEmail
  #   @return [String]
  orgEmail: {
    class: :string
  },

  # @!attribute orgPhone
  #   @return [String]
  orgPhone: {
    class: :string
  },

  # @!attribute orgAddress
  #   @return [String]
  orgAddress: {
    class: :string
  },

  # @!attribute tokenExpirationDate
  #   @return [Jamf::Timestamp]
  tokenExpirationDate: {
    class: Jamf::Timestamp
  }
}.freeze
DEVICES_RSRC = 
'devices'.freeze
SYNC_RSRC = 
'syncs'.freeze
LATEST_RSRC = 
'latest'.freeze
DISOWN_RSRC = 
'disown'.freeze
TYPES = 
%i[computers mobiledevices].freeze
COMPUTERS_RE = 
/mac/i.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from Jamf::JSONObject

Instance Attribute Details

#adminId ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 102

#id ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 63

#name ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 71

#orgAddress ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 126

#orgEmail ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 114

#orgName ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 108

#orgPhone ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 120

#serverName ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 90

#serverUuid ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 96

#siteId ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 84

#supervisionIdentityId ⇒ String 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 78

#tokenExpirationDate ⇒ Jamf::Timestamp 




# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 132

Class Method Details

.device(sn, instance_ident = 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.

Raises:



251
252
253
254
255
256
257
258
259
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 251

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

  searched = instance_ident ? "DeviceEnrollment instance #{instance_ident}" : 'any DeviceEnrollment instance'
  raise Jamf::NoSuchItemError, "No device with serialNumber '#{sn}' in #{searched}"
end

.device_sns(instance_ident = 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



200
201
202
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 200

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

.devices(instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::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



178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 178

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

  devs = fetch_devices(instance_ident, 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_ident = 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 DeviceEnrollmentDevice::PROFILE_STATUSES



228
229
230
231
232
233
234
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 228

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

  devices(instance_ident, 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

Raises:



305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 305

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_rsrc = "#{self.class::RSRC_VERSION}/#{self.class::RSRC_PATH}/#{instance_id}/#{DISOWN_RSRC}"

  cnx.post(disown_rsrc, data)[:devices]
end

.include?(sn, instance_ident = 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?



214
215
216
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 214

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

.sync_history(instance_ident = nil, latest = false, cnx: Jamf.cnx) ⇒ Jamf::DeviceEnrollmentSyncStatus+

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



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 277

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

    rsrc = "#{RSRC_VERSION}/#{RSRC_PATH}/#{instance_id}/#{SYNC_RSRC}"
    rsrc += "/#{LATEST_RSRC}" if latest
  else
    rsrc = "#{RSRC_VERSION}/#{RSRC_PATH}/#{SYNC_RSRC}"
  end
  data = cnx.get rsrc

  return Jamf::DeviceEnrollmentSyncStatus.new data if data.is_a? Hash

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

Instance Method Details

#add_change_log_note(note, cnx: Jamf.cnx) ⇒ void Originally defined in module ChangeLog

This method returns an undefined value.

Add a note to this resource’s change log.

If the change history has been cached already, the cache is flushed after adding the note.

#change_log(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::ChangeLogEntry> Originally defined in module ChangeLog

The change and note history for this resource. This is a collection of objects as a sub-resource of some primary resource. As such, retriving the change log returns an array of objects, and can be paged, sorted and filtered.

This method is very similar to CollectionResource.all, see the docs for that method for more details

successive page.

#change_log_count(cnx: Jamf.cnx) ⇒ Integer Originally defined in module ChangeLog

how many change log entries are there? needed when using paged #change_log calls

#device_sns(type: nil) ⇒ Object 



358
359
360
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 358

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

#devices(type: nil) ⇒ Object

Instance Methods



354
355
356
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 354

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

#devices_with_status(status, type: nil) ⇒ Object 



366
367
368
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 366

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

#disown(*sns) ⇒ Object 



378
379
380
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 378

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

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



362
363
364
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 362

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

#latest_sync ⇒ Object 



374
375
376
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 374

def latest_sync
  sync_history :latest
end

#next_page_of_change_log ⇒ Array<Jamf::ChangeHistoryEntry> Originally defined in module ChangeLog

Fetch the next page of a paged #change_log request Returns an empty array if there’s been no paged request or if the last one has no more pages.

#sync_history(latest = false) ⇒ Object 



370
371
372
 
# File 'lib/jamf/api/resources/collection_resources/device_enrollment.rb', line 370

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