Module: Jamf::Prestage::ClassMethods

Defined in:
lib/jamf/api/jamf_pro/mixins/prestage.rb

Overview

Class Methods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(extender) ⇒ Object

when this module is included, also extend our Class Methods



67
68
69
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 67

def self.extended(extender)
  Jamf.load_msg "--> #{extender} is extending Jamf::Prestage::ClassMethods"
end

Instance Method Details

#assign(*sns_to_assign, to_prestage:, cnx: Jamf.cnx) ⇒ Jamf::OAPISchemas::PrestageScopeResponseV2

Assign one or more serialNumbers to a prestage

Returns:

Raises:



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 201

def 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 ADE
  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]
  spath = scope_path(prestage_id)
  scope = INSTANCE_SCOPE_OBJECT.new cnx.get(spath)

  # 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, spath, new_scope_sns, scope.versionLock, cnx)
end

#assigned?(sn, prestage: nil, cnx: Jamf.cnx, refresh: nil) ⇒ Boolean

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

This uses .serials_by_prestage_id, the class-level scope path which gets a hash of all assigned SNS => the id of the prestage they are assigned to. The instance#assigned? method uses a different path which returnds more data in an OAPI object.

NOTE: If a serial number isn’t assigned to any prestage, it may really be unassigned or it may not exist in your ADE. 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: nil) —

    re-read the list from the API?

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

    If provided, the id or name of an existing prestage in which to look for the sn. if omitted, all prestages are searched.

  • 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?

Raises:



163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 163

def assigned?(sn, prestage: nil, cnx: Jamf.cnx, refresh: nil)
  assigned_id = assigned_prestage_id(sn, cnx: cnx)
  # it isn't assigned at all
  return false unless assigned_id

  # we are looking to see if its assigned at all, which it is
  return true unless prestage

  # we are looking to see if its in a specific prestage
  psid = valid_id prestage, cnx: cnx
  raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage}'" unless psid

  psid == assigned_id
end

#assigned_prestage_id(sn, _refresh = nil, cnx: Jamf.cnx) ⇒ Integer?

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

NOTE: If a serial number isn’t assigned to any prestage, it may really be unassigned or it may not exist in your ADE. 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 #

  • 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



135
136
137
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 135

def assigned_prestage_id(sn, _refresh = nil, cnx: Jamf.cnx)
  serials_by_prestage_id(cnx: cnx)[sn]
end

#default ⇒ Jamf::Prestage?

Return the Prestage 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:



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 76

def 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.select { |d| d[:defaultPrestage] }.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

#serials_by_prestage_id(_refresh = nil, 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) —

    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



96
97
98
99
100
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 96

def serials_by_prestage_id(_refresh = nil, cnx: Jamf.cnx)
  scope_path ||= "#{self::LIST_PATH}/#{SCOPE_PATH}"
  api_reponse = ALL_SCOPES_OBJECT.new cnx.jp_get(scope_path)
  api_reponse.serialsByPrestageId.transform_keys!(&:to_s)
end

#serials_for_prestage(prestage_ident, _refresh = nil, cnx: Jamf.cnx) ⇒ Array<String>

Get the assigned serialnumbers for a given prestage, without having to instantiate it

Parameters:

  • refresh (Boolean) —

    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:



114
115
116
117
118
119
120
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 114

def serials_for_prestage(prestage_ident, _refresh = nil, cnx: Jamf.cnx)
  id = valid_id prestage_ident, cnx: cnx

  raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id

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

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

Unassign one or more serialNumber from a prestage

Returns:

  • (Jamf::PrestageScope) —

    the new scope for the prestage

Raises:



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 232

def 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]
  spath = scope_path(prestage_id)
  scope = INSTANCE_SCOPE_OBJECT.new cnx.get(spath)

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

  update_scope(prestage_name, spath, 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 ADE 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 ADE but not assigned to any prestage



186
187
188
189
 
# File 'lib/jamf/api/jamf_pro/mixins/prestage.rb', line 186

def 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