module Jamf::Criteriable

A mix-in module that allows objects to handle standardized search Criteria.

Some objects in the JSS, such as Advanced Searches and Smart Groups, include a set of Criteria. (i.e conditions which, when met, signify inclusion in a result set.)

A {Jamf::Criteriable::Criteria} instance is a container for one or more {Jamf::Criteriable::Criterion} instances and provides methods for dealing with them easily.

When a {Jamf::APIObject} subclass includes this module, that subclass will have a :criteria attribute, which holds a {Jamf::Criteriable::Criteria} object and can be used to manipulate the Criterion objects inside.

The including subclass also gains some instance methods:

Classes mixing in this module must

@example Working with the criteria of an advanced computer search

# create three Criterion instances (split over multiple lines for clarity)
#
# These find all of jeauxbleaux's computers that have either
# Excel or Word installed

crtn_0 = Jamf::Criteriable::Criterion.new(
  and_or: :and, # NOTE: the and_or value of the first criterion is ignored
  name: 'Username',
  search_type: 'is',
  value: 'jeauxbleaux'
)

crtn_1 = Jamf::Criteriable::Criterion.new(
  and_or: :and,
  paren: :opening,
  name: 'Application Title',
  search_type: 'has',
  value: 'Microsoft Excel.app'
)

crtn_2 = Jamf::Criteriable::Criterion.new(
  and_or: :or,
  name: 'Application Title',
  search_type: 'has',
  value: 'Microsoft Word.app',
  paren: :closing
)

# use them to create a Criteria instance
crta = Jamf::Criteriable::Criteria.new [crtn_0, crtn_1, crtn_2]

# create a new Advanced Search
srch = Jamf::AdvancedComputerSearch.make, :name => "my computer search"
srch.display_fields = ["Computer Name"]

# add our Criteria to it
srch.criteria = crta

# create it in the JSS
srch.create # srch.search_results now contains the matching computers

# append a new criterion to the criteria, limiting the search results farther
# to those computers that have done a recon in the past week
srch.criteria.append_criterion Jamf::Criteriable::Criterion.new(
  and_or: :or,
  name: "Last Inventory Update",
  search_type: "less than x days ago",
  value: 8
)

# save the change to the JSS
srch.save

# fetch the new results
srch.requery_search_results

# oops - that last one should have been :and, not :or
# so replace the last criterion with a correct one
srch.criteria.set_criterion 3, Jamf::Criteriable::Criterion.new(
  and_or: :and,
  name: "Last Inventory Update",
  search_type: "less than x days ago",
  value: 8
)

# save the change to the JSS
# providing a non-false parameter to #update will automatically
# perform the requery  after the update.
srch.update :requery

@see Jamf::Criteriable::Criteria @see Jamf::Criteriable::Criterion

Constants

CRITERIABLE

Constants

Attributes

criteria[R]

@return [Jamf::Criteriable::Criteria] the criteria for the instance into which we’re mixed.

Public Instance Methods

criteria=(new_criteria) click to toggle source

Change the criteria, it must be a Jamf::Criteriable::Criteria instance

@param new_criteria[Jamf::Criteriable::Criteria, nil] the new criteria. An

empty criteria object is used if nil is passed.

@return [void]

    # File lib/jamf/api/classic/api_objects/criteriable.rb
169 def criteria=(new_criteria)
170   new_criteria ||= Jamf::Criteriable::Criteria.new
171   raise Jamf::InvalidDataError, 'Jamf::Criteriable::Criteria instance required' unless new_criteria.is_a?(Jamf::Criteriable::Criteria)
172 
173   @criteria = new_criteria
174   @criteria.container = self unless new_criteria.nil?
175   @need_to_update = true
176 end
parse_criteria() click to toggle source

During initialization, convert the @init_data Hash into a Jamf::Criteriable::Criteria instance stored in @criteria

Classes mixing in this module must call this in initialize

@return [void]

    # File lib/jamf/api/classic/api_objects/criteriable.rb
154 def parse_criteria
155   @criteria = Jamf::Criteriable::Criteria.new
156   @criteria.criteria = @init_data[:criteria].map { |c| Jamf::Criteriable::Criterion.new(**c) } if @init_data[:criteria]
157 
158   @criteria.container = self
159 end
should_update() click to toggle source

@api private Allow our Criteria to tell us when there’s been a change that needs to be updated.

@return [void]

    # File lib/jamf/api/classic/api_objects/criteriable.rb
186 def should_update
187   @need_to_update = true if @in_jss
188 end