Module: JSS::Criteriable

Included in:
AdvancedSearch, Group
Defined in:


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.


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 =
  and_or: :and, # NOTE: the and_or value of the first criterion is ignored
  name: 'Username',
  search_type: 'is',
  value: 'jeauxbleaux'

crtn_1 =
  and_or: :and,
  paren: :opening,
  name: 'Application Title',
  search_type: 'has',
  value: 'Microsoft'

crtn_2 =
  and_or: :or,
  name: 'Application Title',
  search_type: 'has',
  value: 'Microsoft',
  paren: :closing

# use them to create a Criteria instance
crta = [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
  and_or: :or,
  name: "Last Inventory Update",
  search_type: "less than x days ago",
  value: 8

# save the change to the JSS

# fetch the new 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,
  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:

Defined Under Namespace

Classes: Criteria, Criterion

Constant Summary collapse




Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details


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


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

def criteria

Instance Method Details


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 = ( @init_data[:criteria].map { |c| c } if @init_data[:criteria])
  @criteria.container = self if @criteria


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 181

def should_update
  @need_to_update = true if @in_jss