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

Returns:




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

#id ⇒ String

Returns:




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

#name ⇒ String

Returns:




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

#orgAddress ⇒ String

Returns:




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

#orgEmail ⇒ String

Returns:




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

#orgName ⇒ String

Returns:




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

#orgPhone ⇒ String

Returns:




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

#serverName ⇒ String

Returns:




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

#serverUuid ⇒ String

Returns:




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

#siteId ⇒ String

Returns:




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

#supervisionIdentityId ⇒ String

Returns:




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

#tokenExpirationDate ⇒ Jamf::Timestamp

Returns:




# 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.

Parameters:

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

    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:

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

Returns:

  • (Array<String>) —

    just the serial numbers for the 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

Parameters:

  • instance_ident (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:



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

Parameters:

  • status (String) —

    A member of DeviceEnrollmentDevice::PROFILE_STATUSES

Returns:



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

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:



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?

Parameters:

  • sn (String) —

    the serialNumber to look for

Returns:

  • (Boolean) —

    is the given SN in a given DeviceEnrollment instance



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.

Parameters:

  • instance_ident (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_ident is provided.

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

    The API connection to use

Returns:



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.

Parameters:

  • note (String) —

    The note to add. It cannot be empty.

#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.

Parameters:

  • sort (String, Array<String>) (defaults to: nil) —

    Server-side sorting criteria in the format: property:direction, where direction is 'asc' or 'desc'. Multiple properties are supported, either as separate strings in an Array, or a single string, comma separated.

  • filter (String) (defaults to: nil) —

    An RSQL filter string. Not all change_log resources currently support filters, and if they don't, this will be ignored.

  • paged (Boolean) (defaults to: nil) —

    Defaults to false. Returns only the first page of `page_size` log entries. Use #next_page_of_change_log to retrieve each

  • page_size (Integer) (defaults to: nil) —

    How many log entries are returned per page? Minimum is 1, maximum is 2000, default is 100. Ignored unless paged: is truthy. Note: the final page may contain fewer entries than the page_size

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

    re-fetch and re-cache the full list of all entries. Ignored if paged:, page_size:, sort:, or filter: are used.

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

    The API connection to use, default: Jamf.cnx. If this is an instance of a Collection Resource, this is always the connection from which it was fetched.

Returns:

#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

Parameters:

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

    The API connection to use, default: Jamf.cnx This is ignored for instances of Collection Resources, which always use the same connection from which they were fetched.

Returns:

  • (Integer) —

    How many changelog entries exist?

#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

Returns:

  • (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.

Returns:

  • (Array<Jamf::ChangeHistoryEntry>) —

    The next page of the change and note history for this resource

#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