Class: Jamf::Prestage

Inherits:
CollectionResource show all
Extended by:
Abstract, UnCreatable
Includes:
Lockable
Defined in:
lib/jamf/api/abstract_classes/prestage.rb

Overview

A building defined in the JSS

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 [Integer]
  id: {
    class: :integer,
    identifier: :primary,
    readonly: true
  },

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  # @!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: :integer
  },

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

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

}.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/abstract_classes/prestage.rb', line 162

#authenticationPrompt ⇒ String

Returns:




# File 'lib/jamf/api/abstract_classes/prestage.rb', line 130

#deviceEnrollmentProgramInstanceId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 142

#enrollmentCustomizationId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 169

#enrollmentSiteId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 106

#isEnableDeviceBasedActivationLock ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 136

#isKeepExistingLocationInformation ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 118

#isKeepExistingSiteMembership ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 112

#isRequireAuthentication ⇒ Boolean

Returns:

  • (Boolean) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 124

#locationInformation ⇒ Jamf::ComputerPrestageSkipSetupItems

Returns:




# File 'lib/jamf/api/abstract_classes/prestage.rb', line 148

#profileUUID ⇒ String

Returns:




# File 'lib/jamf/api/abstract_classes/prestage.rb', line 175

#siteId ⇒ Integer

Returns:

  • (Integer) 



# File 'lib/jamf/api/abstract_classes/prestage.rb', line 181

#skipSetupItems ⇒ Jamf::ComputerPrestageSkipSetupItems

Returns:




# File 'lib/jamf/api/abstract_classes/prestage.rb', line 155

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

Returns the value of attribute versionLock.

Class Method Details

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

Assign one or more serialNumber to a prestage

Returns:

Raises:



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 317

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?



281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 281

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



258
259
260
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 258

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

.creatable? ⇒ Boolean Originally defined in module UnCreatable

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:



203
204
205
206
207
208
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 203

def self.default
  id = all.select { |ps| ps[:isDefaultPrestage] }.first.dig :id
  return nil unless id

  fetch id: id
end

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

when any extended class or subclass of an extended class is instntiated check that it isn’t in the abstract list.

Raises:

.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



219
220
221
222
223
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 219

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:



236
237
238
239
240
241
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 236

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 '#{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



310
311
312
313
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 310

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

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

Unassign one or more serialNumber from a prestage

Returns:

Raises:



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 349

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



303
304
305
306
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 303

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



424
425
426
427
428
429
430
431
432
433
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 424

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) 


418
419
420
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 418

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



408
409
410
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 408

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

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

#save ⇒ Object 



446
447
448
449
450
451
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 446

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:



395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 395

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 



436
437
438
439
440
441
442
443
 
# File 'lib/jamf/api/abstract_classes/prestage.rb', line 436

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