Module: JSS::Criteriable

Included in:

AdvancedSearch, Group

Defined in:

lib/jss.rb,
lib/jss/api_object/criteriable.rb,
lib/jss/api_object/criteriable/criteria.rb,
lib/jss/api_object/criteriable/criterion.rb

Overview

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 Criteria instance is a container for one or more Criterion instances and provides methods for dealing with them easily.

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

The including subclass also gains some instance methods:

• #parse_critera - sets up the :criteria attribute during initialization

• #criteria= - allows the wholesale replacement of the criteria

• #need_to_update - allows the Criteria instance to inform the subclass instance that it has changed and needs an #update

Classes mixing in this module must

• If they are Updatable or Creatable, they must insert self.criteria.rest_xml into their own xml output.

Examples:

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 = JSS::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 = JSS::Criteriable::Criterion.new(
  and_or: :and,
  paren: :opening,
  name: 'Application Title',
  search_type: 'has',
  value: 'Microsoft Excel.app'
)

crtn_2 = JSS::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 = JSS::Criteriable::Criteria.new [crtn_0, crtn_1, crtn_2]

# create a new Advanced Search
srch = JSS::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 JSS::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, JSS::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 Also:

• Criteria
• Criterion

Defined Under Namespace

Classes: Criteria, Criterion

Constant Summary

CRITERIABLE =

Constants

true

Instance Attribute Summary

• #criteria ⇒ JSS::Criteriable::Criteria

  The criteria for the instance into which we're mixed.

Instance Method Summary

• #parse_criteria ⇒ void

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

• #should_update ⇒ void private

  Allow our Criteria to tell us when there's been a change that needs to be updated.

Instance Attribute Details

#criteria ⇒ JSS::Criteriable::Criteria

Returns the criteria for the instance into which we're mixed.

Returns:

• (JSS::Criteriable::Criteria) —

  the criteria for the instance into which we're mixed.

# File 'lib/jss/api_object/criteriable.rb', line 141

def criteria
  @criteria
end

Instance Method Details

#parse_criteria ⇒ void

This method returns an undefined value.

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

Classes mixing in this module must call this in #initialize

# File 'lib/jss/api_object/criteriable.rb', line 154

def parse_criteria
  @criteria = JSS::Criteriable::Criteria.new
  @criteria.criteria = @init_data[:criteria].map { |c| JSS::Criteriable::Criterion.new c } if @init_data[:criteria]

  @criteria.container = self
end

#should_update ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Allow our Criteria to tell us when there's been a change that needs to be updated.

# File 'lib/jss/api_object/criteriable.rb', line 186

def should_update
  @need_to_update = true if @in_jss
end