Class: Jamf::Prestage

Inherits:
CollectionResource show all
Extended by:
BaseClass
Includes:
Lockable
Defined in:
lib/jamf/api/base_classes/prestage.rb

Overview

The parent class of ComputerPrestage, and MobileDevicePrestage holding common code.

Direct Known Subclasses

ComputerPrestage, MobileDevicePrestage

Constant Summary collapse

OBJECT_MODEL =

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

{

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

  # @!attribute displayName
  #   @return [String]
  displayName: {
    class: :string,
    identifier: true,
    validator: :non_empty_string,
    required: true,
    aliases: %i[name]
  },

  # @!attribute mandatory
  #   @return [Boolean]
  mandatory: {
    class: :boolean
  },

  # @!attribute mdmRemovable
  #   @return [Boolean]
  mdmRemovable: {
    class: :boolean
  },

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

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

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

  # @!attribute defaultPrestage
  #   @return [Boolean]
  defaultPrestage: {
    class: :boolean,
    aliases: [:default?]
  },

  # @!attribute enrollmentSiteId
  #   @return [Integer]
  enrollmentSiteId: {
    class: :j_id
  },

  # @!attribute keepExistingSiteMembership
  #   @return [Boolean]
  keepExistingSiteMembership: {
    class: :boolean
  },

  # @!attribute keepExistingLocationInformation
  #   @return [Boolean]
  keepExistingLocationInformation: {
    class: :boolean
  },

  # @!attribute requireAuthentication
  #   @return [Boolean]
  requireAuthentication: {
    class: :boolean
  },

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

  # @!attribute preventActivationLock
  #   @return [Boolean]
  preventActivationLock: {
    class: :boolean
  },

  # @!attribute enableDeviceBasedActivationLock
  #   @return [Boolean]
  enableDeviceBasedActivationLock: {
    class: :boolean
  },

  # @!attribute deviceEnrollmentProgramInstanceId
  #   @return [Integer]
  deviceEnrollmentProgramInstanceId: {
    class: :j_id
  },

  # @!attribute locationInformation
  #   @return [Jamf::ComputerPrestageSkipSetupItems]
  locationInformation: {
    class: Jamf::PrestageLocation,
    aliases: %i[location]
  },

  # @!attribute skipSetupItems
  #   @return [Jamf::ComputerPrestageSkipSetupItems]
  purchasingInformation: {
    class: Jamf::PrestagePurchasingData,
    aliases: %i[purchasing]
  },

  # @!attribute anchorCertificates
  #   @return [Array<String>]
  anchorCertificates: {
    class: :string,
    multi: true
  },

  # @!attribute enrollmentCustomizationId
  #   @return [Integer]
  enrollmentCustomizationId: {
    class: :j_id
  },

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

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

  # @!attribute autoAdvanceSetup
  #   @return [Boolean]
  autoAdvanceSetup: {
    class: :boolean
  },

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

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

}.freeze
SCOPE_RSRC = 
'scope'.freeze
SERIALS_KEY = 
:serialsByPrestageId
SYNC_RSRC = 
'sync'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#anchorCertificates ⇒ Array<String>

Returns:




# File 'lib/jamf/api/base_classes/prestage.rb', line 165

#authenticationPrompt ⇒ String

Returns:




# File 'lib/jamf/api/base_classes/prestage.rb', line 127

#autoAdvanceSetup ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 190

#deviceEnrollmentProgramInstanceId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 145

#enableDeviceBasedActivationLock ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 139

#enrollmentCustomizationId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 172

#enrollmentSiteId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 103

#keepExistingLocationInformation ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 115

#keepExistingSiteMembership ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 109

#language ⇒ String

Returns:




# File 'lib/jamf/api/base_classes/prestage.rb', line 178

#locationInformation ⇒ Jamf::ComputerPrestageSkipSetupItems

Returns:

  • (Jamf::ComputerPrestageSkipSetupItems) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 151

#preventActivationLock ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 133

#profileUUID ⇒ String

Returns:




# File 'lib/jamf/api/base_classes/prestage.rb', line 196

#region ⇒ String

Returns:




# File 'lib/jamf/api/base_classes/prestage.rb', line 184

#requireAuthentication ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 121

#siteId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 202

#skipSetupItems ⇒ Jamf::ComputerPrestageSkipSetupItems

Returns:

  • (Jamf::ComputerPrestageSkipSetupItems) 



# File 'lib/jamf/api/base_classes/prestage.rb', line 158

#versionLock ⇒ Object (readonly) Originally defined in module Lockable

Returns the value of attribute versionLock.

Class Method Details

.allocate(*args, &block) ⇒ Object Originally defined in module BaseClass

Can't allocate if base class

.assign(*sns_to_assign, to_prestage:, cnx: Jamf.cnx) ⇒ Jamf::PrestageScope

Assign one or more serialNumber to a prestage

Returns:

Raises:



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 342

def self.assign(*sns_to_assign, to_prestage:, cnx: Jamf.cnx)
  prestage_id = valid_id to_prestage
  raise Jamf::NoSuchItemError, "No #{self} matching '#{to_prestage}'" unless prestage_id

  # all sns_to_assign must be in DEP
  not_in_dep = sns_to_assign - Jamf::DeviceEnrollment.device_sns
  raise Jamf::UnsupportedError, "These SNs are not in any Device Enrollment instance: #{not_in_dep.join ', '}" unless not_in_dep.empty?

  # all sns_to_assign must currently be unassigned.
  already_assigned = sns_to_assign - unassigned_sns
  raise Jamf::UnsupportedError, "These SNs are already assigned to a prestage: #{already_assigned.join ', '}" unless already_assigned.empty?

  # upcase all sns
  sns_to_assign.map!(&:to_s)
  sns_to_assign.map!(&:upcase)

  # get the prestage name
  prestage_name = map_all(:id, to: :displayName)[prestage_id]

  scope_rsrc = "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{prestage_id}/#{SCOPE_RSRC}"
  scope = Jamf::PrestageScope.new cnx.get(scope_rsrc)

  # add the new sns to the existing ones
  new_scope_sns = scope.assignments.map(&:serialNumber)
  new_scope_sns += sns_to_assign
  new_scope_sns.uniq!

  update_scope(prestage_name, scope_rsrc, new_scope_sns, scope.versionLock, cnx)
end

.assigned?(sn, prestage_ident = nil, refresh: false, cnx: Jamf.cnx) ⇒ Boolean

Is the given serialNumber assigned to any prestage, or to the given prestage if a prestage_ident is specified?

NOTE: If a serial number isn't assigned to any prestage, it may really be unassigned or it may not exist in your DEP. To see if a SN exists in one of your Device Enrollment instances, use Jamf::DeviceEnrollment.include?

Parameters:

  • sn (String) —

    the serial number to look for

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

    re-read the list from the API?

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

    the API connection to use

Returns:

  • (Boolean) —

    Is the sn assigned, at all or to the given prestage?



306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 306

def self.assigned?(sn, prestage_ident = nil, refresh: false, cnx: Jamf.cnx)
  assigned_id = assigned_prestage_id(sn, refresh, cnx: cnx)
  return false unless assigned_id

  if prestage_ident
    psid = valid_id prestage_ident, cnx: cnx
    raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless psid

    return psid == assigned_id
  end

  true
end

.assigned_prestage_id(sn, refresh = false, cnx: Jamf.cnx) ⇒ Integer?

The id of the prestage to which the given serialNumber is assigned. nil if not assigned or not in DEP.

NOTE: If a serial number isn't assigned to any prestage, it may really be unassigned or it may not exist in your DEP. To see if a SN exists in one of your Device Enrollment instances, use Jamf::DeviceEnrollment.include?

Parameters:

  • sn (String) —

    the serial number to look for

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

    re-read the list from the API?

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

    the API connection to use

Returns:

  • (Integer, nil) —

    The id of prestage to which the SN is assigned



283
284
285
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 283

def self.assigned_prestage_id(sn, refresh = false, cnx: Jamf.cnx)
  serials_by_prestage_id(refresh, cnx: cnx)[sn]
end

.base_class? ⇒ Boolean Originally defined in module BaseClass

Returns:

  • (Boolean)

.default ⇒ Jamf::Prestage?

Return the Prestage subclass that is marked as default, i.e. the one that new SNs are assigned to when first added. Nil if no default is defined

Returns:



224
225
226
227
228
229
230
231
232
233
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 224

def self.default
  # only one can be true at a time, so sort desc by that field,
  # and the true one will be at the top
  default_prestage_data = all(sort: 'defaultPrestage:desc', paged: true, page_size: 1).first

  # Just in case there was no true one, make sure defaultPrestage is true
  return unless default_prestage_data&.dig(:defaultPrestage)

  fetch id: default_prestage_data[:id]
end

.new(*args, &block) ⇒ Object Originally defined in module BaseClass

Can't instantiate if base_class

.serials_by_prestage_id(refresh = false, cnx: Jamf.cnx) ⇒ Hash {String => Integer}

Return all scoped serial numbers and the id of the prestage they are assigned to. Data is cached, use a truthy first param to refresh.

Parameters:

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

    re-read the list from the API?

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

    the API connection to use

Returns:

  • (Hash {String => Integer}) —

    The Serials and prestage IDs



244
245
246
247
248
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 244

def self.serials_by_prestage_id(refresh = false, cnx: Jamf.cnx)
  @serials_by_prestage_rsrc ||= "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{SCOPE_RSRC}"
  @serials_by_prestage_id = nil if refresh
  @serials_by_prestage_id ||= cnx.get(@serials_by_prestage_rsrc)[SERIALS_KEY].transform_keys!(&:to_s)
end

.serials_for_prestage(prestage_ident, refresh = false, cnx: Jamf.cnx) ⇒ Array<String>

Get the assigned serialnumbers for a given prestage

Parameters:

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

    re-read the list from the API?

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

    the API connection to use

Returns:

  • (Array<String>) —

    the SN's assigned to the prestage

Raises:



261
262
263
264
265
266
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 261

def self.serials_for_prestage(prestage_ident, refresh = false, cnx: Jamf.cnx)
  id = valid_id prestage_ident, cnx: cnx
  raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id

  serials_by_prestage_id(refresh, cnx: cnx).select { |_sn, psid| id == psid }.keys
end

.sns_not_in_device_enrollment ⇒ Array<String>

Returns The serial numbers of known hardware not in DEP at all.

Returns:

  • (Array<String>) —

    The serial numbers of known hardware not in DEP at all



335
336
337
338
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 335

def self.sns_not_in_device_enrollment
  # type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
  nil # TODO: this, once MobileDevice  & Computer classes are implemented
end

.stop_if_base_class(action = DEFAULT_ACTION) ⇒ Object Originally defined in module BaseClass

raise an exception if this class is a base class

.unassign(*sns_to_unassign, from_prestage:, cnx: Jamf.cnx) ⇒ Jamf::PrestageScope

Unassign one or more serialNumber from a prestage

Returns:

Raises:



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 374

def self.unassign(*sns_to_unassign, from_prestage:, cnx: Jamf.cnx)
  prestage_id = valid_id from_prestage
  raise Jamf::NoSuchItemError, "No #{self} matching '#{from_prestage}'" unless prestage_id

  # upcase all sns
  sns_to_unassign.map!(&:to_s)
  sns_to_unassign.map!(&:upcase)

  # get the prestage name
  prestage_name = map_all(:id, to: :displayName)[prestage_id]

  scope_rsrc = "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{prestage_id}/#{SCOPE_RSRC}"
  scope = Jamf::PrestageScope.new cnx.get(scope_rsrc)

  new_scope_sns = scope.assignments.map(&:serialNumber)
  new_scope_sns -= sns_to_unassign

  update_scope(prestage_name, scope_rsrc, new_scope_sns, scope.versionLock, cnx)
end

.unassigned_sns(cnx: Jamf.cnx) ⇒ Array<String>

We subtract the serials_by_prestage_id.keys from all known DEP SNs rather than just looking for Jamf::DeviceEnrollment.devices with status REMOVED, because of the delay in updating the status for Jamf::DeviceEnrollment::Devices, which must come from apple.

Returns:

  • (Array<String>) —

    The serial numbers of devices that are in DEP but not assigned to any prestage



328
329
330
331
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 328

def self.unassigned_sns(cnx: Jamf.cnx)
  type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
  Jamf::DeviceEnrollment.device_sns(type: type, cnx: cnx) - serials_by_prestage_id(:refresh, cnx: cnx).keys
end

Instance Method Details

#assign(*sns_to_assign) ⇒ Object Also known as: add

Assign



449
450
451
452
453
454
455
456
457
458
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 449

def assign(*sns_to_assign)
  @scope = self.class.assign(sns_to_assign, to_prestage: @id, cnx: @cnx)
  @versionLock = @scope.versionLock

  # sns_to_assign.map!(&:to_s)
  # new_scope_sns = assigned_sns
  # new_scope_sns += sns_to_assign
  # new_scope_sns.uniq!
  # update_scope(new_scope_sns)
end

#assigned?(sn) ⇒ Boolean Also known as: include?

Is this SN assigned to this prestage?

Parameters:

  • sn (String) —

    the sn to look for

Returns:

  • (Boolean) 


443
444
445
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 443

def assigned?(sn)
  assigned_sns.include? sn
end

#assigned_sns ⇒ Array<String>

Returns the serialnumbers assigned to this prestage.

Returns:

  • (Array<String>) —

    the serialnumbers assigned to this prestage



433
434
435
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 433

def assigned_sns
  scope.assignments.map(&:serialNumber)
end

#initialize(data, cnx: Jamf.cnx) ⇒ Object Originally defined in module Lockable

#save ⇒ Object 



471
472
473
474
475
476
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 471

def save
  super
  # the scope needs to be refreshed, since its versionLock will need to be
  # updated
  @scope = nil
end

#scope(refresh = false) ⇒ PrestageScope

The scope data for this prestage

Parameters:

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

    reload fromthe API?

Returns:



420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 420

def scope(refresh = false)
  @scope = nil if refresh
  return @scope if @scope

  @scope = Jamf::PrestageScope.new @cnx.get(scope_rsrc)
  unless @scope.versionLock == @versionLock
    raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again"
  end

  @scope
end

#to_jamf ⇒ Object Originally defined in module Lockable

#unassign(*sns_to_unassign) ⇒ Object Also known as: remove 



461
462
463
464
465
466
467
468
 
# File 'lib/jamf/api/base_classes/prestage.rb', line 461

def unassign(*sns_to_unassign)
  @scope = self.class.unassign(sns_to_unassign, from_prestage: @id, cnx: @cnx)
  @versionLock = @scope.versionLock
  # sns_to_unassign.map!(&:to_s)
  # new_scope_sns = assigned_sns
  # new_scope_sns -= sns_to_unassign
  # update_scope(new_scope_sns)
end