Class: Windoo::BaseClasses::CriteriaManager

Inherits:
ArrayManager show all
Defined in:
lib/windoo/base_classes/criteria_manager.rb

Overview

The common code for dealing with a group of criteria-based objects in Software Titles.

This class manages an array of instances of subclasses of Criterion

See also: ArrayManager for info about managed Arrays.

This class should be the superclass of classes representing the three ways Criteria are used in a SoftwareTitle.

  • SoftwareTitles have ‘requirements’

    • These are criteria defining which computers have any version of the title installed.

  • Patches within SoftwareTitles have ‘capabilities’

    • These are criteria defining which computers are capable of installing/running the patch.

  • A Patch’s ‘component’ has a set of ‘criteria’

    • These are criteria defining which comptuers have this version of the title installed.

Here’s how that looks for requirements:

- {Windoo::RequirementManager Windoo::RequirementManager} should be a subclass of this class, and must define<br/>
  the constant `MEMBER_CLASS = Windoo::Requirement` indicating that it should manage an array of...
- {Windoo::Requirement Windoo::Requirement} objects which is a subclass of {Windoo::BaseClasses::Criterion}
- {Windoo::SoftwareTitle#requirements} should return a single {Windoo::RequirementManager Windoo::RequirementManager} object

Here’s how to use a Windoo::RequirementManager:

title = Windoo::SoftwareTitle.fetch 'mytitle'
title.requirements.to_a
# => the readonly Array of Windoo::Requirement objects

title.requirements.add_criterion(options: here)
# => add a new Windoo::Requirement to the Array

title.requirements.replace_criterion(victim_id, options: here)
# => replace an existing Windoo::Requirement in the Array

title.requirements.delete_criterion(victim_id)
# => delete an existing Windoo::Requirement from the Array

The other CriteriaManagers work the same way, they are just located in their respective places:

# Patch Capabilities

patch = title.patches.first
# => a single patch

patch.capabilities.to_a
# => the readonly Array of Windoo::Capability objects

patch.capabilities.add_criterion(options: here)
# => add a new Windoo::Capability to the patch

patch.capabilities.replace_criterion(victim_id, options: here)
# => replace an existing Windoo::Capability in the patch

patch.capabilities.delete_criterion(victim_id)
# => delete an existing Windoo::Capability from the patch

# Patch Component Criteria

component = patch.component
# => the component of a patch

component.criteria.to_a
# => the readonly Array of Windoo::ComponentCriterion objects

component.criteria.add_criterion(options: here)
# => add a new Windoo::ComponentCriterion to the component

component.criteria.replace_criterion(victim_id, options: here)
# => replace an existing Windoo::ComponentCriterion in the component

component.criteria.delete_criterion(victim_id)
# => delete an existing Windoo::ComponentCriterion from the component

Subclasses MUST define the constant MEMBER_CLASS to indicate the class of the items we are managing

Constant Summary

Constants inherited from ArrayManager

ArrayManager::PP_OMITTED_INST_VARS

Instance Attribute Summary

Attributes inherited from ArrayManager

#container

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from ArrayManager

#[], #each, #empty?, #find, #find_by_attr, #first, #index, #initialize, #last, #pretty_print_instance_variables, #size, #to_a

Constructor Details

This class inherits a constructor from Windoo::BaseClasses::ArrayManager

Class Method Details

.available_names(cnx: Windoo.cnx) ⇒ Array<String>

Returns The names of all available recon criteria names.

Returns:

  • (Array<String>) —

    The names of all available recon criteria names



100
101
102
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 100

def self.available_names(cnx: Windoo.cnx)
  cnx.get 'valuelists/criteria/names'
end

.available_types(cnx: Windoo.cnx) ⇒ Array<String>

Returns The possible criteria types.

Returns:

  • (Array<String>) —

    The possible criteria types



106
107
108
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 106

def self.available_types(cnx: Windoo.cnx)
  cnx.get 'valuelists/criteria/types'
end

.operators_for(name, cnx: Windoo.cnx) ⇒ Array<String>

Find out the available critrion operators for a given criterion. e.g. for the criterion ‘Application Title’ the operators are:

["is", "is not", "has", "does not have"]

for the criterion ‘Application Bundle ID’ the operators are:

["is", "is not", "like", "not like", "matches regex", "does not match regex"]

for the criterion ‘Computer Group’ the operators are:

["member of", "not member of"]

…and so on.

Parameters:

  • name (String) —

    The criterion for which to get the operators

Returns:

  • (Array<String>) —

    The possible operators for a given criterion name



127
128
129
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 127

def self.operators_for(name, cnx: Windoo.cnx)
  cnx.post 'valuelists/criteria/operators', { name: name }
end

Instance Method Details

#add_criterion(name:, operator:, value:, type: 'recon', and_or: :and, absoluteOrderId: nil) ⇒ Integer

Add a criterion to the end of this array.

Parameters:

  • name (String) —

    The name of the criterion To ask the server for an Array of all possible criteria names, use

    Windoo::BaseClasses::CriteriaManager.available_names
  • operator (String) —

    The operator to use for comparing the value given here with the value for a computer. To ask the server for an Array of all operators available for some criterion, use

    Windoo::BaseClasses::CriteriaManager.operators_for criterion_name
  • value (String, integer) —

    The value that will be compared with that on a computer, using the operator.

  • type (String) (defaults to: 'recon') —

    how does Jamf Pro get this value for a computer? ‘recon’ means its a normal value gathered by a recon. ‘extensionAttribute’ means the value is generated by the extensionAttribute associated with this SoftwareTitle. Defaults to ‘recon’.

  • and_or (Symbol) (defaults to: :and) —

    :and or :or. Defines how this criterion is joined with the previous one in a chain of boolean logic. Default is :and

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

    The zero-based position of this criterion among all the others in the array. By default, this criterion will be added at ‘-1’, the end of the array

Returns:

  • (Integer) —

    The id of the new criterion



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 167

def add_criterion(name:, operator:, value:, type: 'recon', and_or: :and, absoluteOrderId: nil)
  absoluteOrderId ||= @managed_array.size

  new_criterion = self.class::MEMBER_CLASS.create(
    cnx: container.cnx,
    container: container,
    and_or: and_or,
    name: name,
    operator: operator,
    value: value,
    type: type.to_s,
    absoluteOrderId: absoluteOrderId
  )

  # call the method from our superclass to add it to the array
  add_member new_criterion, index: absoluteOrderId
  update_local_absoluteOrderIds
  new_criterion.primary_id
end

#delete_all_criteria ⇒ void

This method returns an undefined value.

Delete all the criteria



302
303
304
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 302

def delete_all_criteria
  delete_all_members
end

#delete_criterion(id) ⇒ Integer

Delete a criterion by its id

Parameters:

  • id (Integer) —

    The primary ID of the criterion to delete. So for an array of Windoo::Requirement, you would provide a ‘requirementId’

Returns:

  • (Integer) —

    The id of the deleted criterion



292
293
294
295
296
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 292

def delete_criterion(id)
  delid = delete_member(id).deleted_id
  update_local_absoluteOrderIds
  delid
end

#move_criterion(id, absoluteOrderId:) ⇒ Integer

Change the position of an existing criterion in the array

Parameters:

  • id (Integer) —

    The primary ID of the criterion to update. So for an array of Windoo::Requirement, you would provide a ‘requirementId’

  • absoluteOrderId (Integer) —

    The zero-based position to which you want to move the criterion. So if you want to make it the third criterion in the list, use 2.

Returns:

  • (Integer) —

    the new absoluteOrderId



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 266

def move_criterion(id, absoluteOrderId:)
  # Can't move it beyond the end of the array....
  max_idx = @managed_array.size - 1
  absoluteOrderId = max_idx if absoluteOrderId > max_idx

  # ... or before the beginning
  absoluteOrderId = 0 if absoluteOrderId.negative?

  # do it on the server first, to raise potential errs before
  # modifying the array
  criterion = update_member id, absoluteOrderId: absoluteOrderId

  # now modify the array
  move_member criterion, index: absoluteOrderId
  update_local_absoluteOrderIds

  absoluteOrderId
end

#replace_criterion(id, name:, operator:, value:, type: 'recon', and_or: :and) ⇒ Integer

Create a new criterion from the provided attributes and use it to replace the one with the given id.

Parameters:

  • id (Integer) —

    The primary ID of the criterion to update. So for an array of Windoo::Requirement, you would provide a ‘requirementId’

  • name (String) —

    The name of the criterion To get an Array of all possible criteria names, use Windoo::BaseClasses::CriteriaManager.available_names

  • operator (String) —

    The operator to use for comparing the value given here with the value for a computer. To get an Array of all operators available for some criterion, use Windoo::BaseClasses::CriteriaManager.operators_for criterion_name

  • value (String, integer) —

    The value that will be compared with that on a computer, using the operator.

  • type (String) (defaults to: 'recon') —

    how does Jamf Pro get this value for a computer? ‘recon’ means its a normal value gathered by a recon. ‘extensionAttribute’ means the value is generated by the extensionAttribute associated with this SoftwareTitle. Defaults to ‘recon’.

  • and_or (Symbol) (defaults to: :and) —

    :and or :or. Defines how this criterion is joined with the previous one in a chain of boolean logic. Default is :and

Returns:

  • (Integer) —

    The id of the new criterion



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/windoo/base_classes/criteria_manager.rb', line 218

def replace_criterion(id, name:, operator:, value:, type: 'recon', and_or: :and)
  victim = delete_member(id)

  add_criterion(
    and_or: and_or,
    name: name,
    operator: operator,
    value: value,
    type: type.to_s,
    absoluteOrderId: victim.absoluteOrderId
  )
# no need to run update_local_absoluteOrderIds, we haven't changed the order,
# and it was called by add_criterion

# Windoo::ConnectionError should only come from the Add operation,
# usually when one of the attributes given was a problem.
#
# The delete should give a Windoo::NoSuchItemError if the id doesn't
# exist on the server.
rescue Windoo::ConnectionError
  # make sure the victim was really removed from the array
  # It should have been by the delete_member call above,
  @managed_array.delete_if { |c| c.primary_id == victim.primary_id }

  # then re-add the victim in the same position
  add_criterion(
    and_or: victim.and_or,
    name: victim.name,
    operator: victim.operator,
    value: victim.value,
    type: victim.type.to_s,
    absoluteOrderId: victim.absoluteOrderId
  )
  # and re-raise the error
  raise
end