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> 




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

#authenticationPrompt ⇒ String 




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

#autoAdvanceSetup ⇒ Boolean 




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

#deviceEnrollmentProgramInstanceId ⇒ Integer 




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

#enableDeviceBasedActivationLock ⇒ Boolean 




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

#enrollmentCustomizationId ⇒ Integer 




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

#enrollmentSiteId ⇒ Integer 




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

#keepExistingLocationInformation ⇒ Boolean 




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

#keepExistingSiteMembership ⇒ Boolean 




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

#language ⇒ String 




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

#locationInformation ⇒ Jamf::ComputerPrestageSkipSetupItems 




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

#preventActivationLock ⇒ Boolean 




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

#profileUUID ⇒ String 




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

#region ⇒ String 




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

#requireAuthentication ⇒ Boolean 




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

#siteId ⇒ Integer 




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

#skipSetupItems ⇒ 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

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?



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?



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

.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



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.



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

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> 



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

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.



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?



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> 



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



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