Module: Jamf::Searchable

Defined in:
lib/jamf/api/mixins/searchable.rb

Overview

Code for CollectionResources that have a …/searchObjects resource. These resources provide for basic searching as will as sorting and paging of the found set.

NOTE: This module provides class methods, not instance methods, and therefore must be mixed in with `extend` and not `include`

Classes extended with this module must define:

SEARCH_RSRC [String] the resource to which the search is POSTed.

Classes including this module may define:

SEARCH_FIELDS [Hash{Symbol: Symbol}]

The hash keys are the names of searchable fields, e.g. 'name', or 'udid' and the values are the class expected for the field, one of: :string, :integer, or :boolean

Without defining search fields, every search returns all objects, but the sorting and paging options are honored.

If search fields are provided, then they can be specified when performing a search. If more than one is specified, they are AND'ed together.

To Search:

1) Set result sort order

If you want sorted results, first set the sort order with a combination of `MyClass.search_result_order = field, dir` where field is the name of the sort fiend and dir is :asc or :desc

If you want a multi-level sort, set the first sort field as above, then use `MyClass.search_result_order_append field, dir` to add subsequent sort fields

To clear them out and start over, call `MyClass.clear_search_result_order`

2) Set page size

If you want paged results then call `MyClass.search_result_page_size = X`
before starting your seacch

3) Do the search:

MyClass.search

Defined Under Namespace

Classes: OrderBy, SeachParams

Constant Summary collapse

SORT_DIRECTIONS = 
{
  asc: 'ASC',
  desc: 'DESC'
}.freeze

Instance Method Summary collapse

Instance Method Details

#clear_search_result_order ⇒ Object 



106
107
108
 
# File 'lib/jamf/api/mixins/searchable.rb', line 106

def clear_search_result_order
  @search_result_order = []
end

#search(pageNumber: 0, cnx: Jamf.cnx, load_all: true, **terms) ⇒ Object

TODO: occasional excludedIds array



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/jamf/api/mixins/searchable.rb', line 111

def search(pageNumber: 0, cnx: Jamf.cnx, load_all: true, **terms)
  raise "#{self} is not searchable in the API" unless defined? self::SEARCH_RSRC

  search_body = {
    pageNumber: pageNumber,
    pageSize: @search_result_page_size,
    isLoadToEnd: load_all,
    orderBy: @search_result_order
  }

  if defined? self::SEARCH_FIELDS
    terms.each do |fld, val|
      next unless self::SEARCH_FIELDS.key? fld

      case self::SEARCH_FIELDS[fld]
      when :integer
        val = Jamf::Validate.integer val, "Search value for #{fld} must be an Integer"
      when :string
        val = Jamf::Validate.string val, "Search value for #{fld} must be a String"
      when :boolean
        val = Jamf::Validate.boolean val, "Search value for #{fld} must be a boolean"
      end # case

      search_body[fld] = val
    end # terms.each
  end # if defined? self::SEARCH_FIELDS

  cnx.post self::SEARCH_RSRC, search_body

end

#search_result_order ⇒ Object 



92
93
94
 
# File 'lib/jamf/api/mixins/searchable.rb', line 92

def search_result_order
  @search_result_order ||= []
end

#search_result_order=(fieldname, dir = :asc) ⇒ Object 



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

def search_result_order=(fieldname, dir = :asc)
  raise 'direction must be either :asc, or :desc' unless SORT_DIRECTIONS.key? dir
  @search_result_order = [{ field: fieldname, direction: SORT_DIRECTIONS[dir] }]
end

#search_result_order_append(fieldname, dir = :asc) ⇒ Object 



101
102
103
104
 
# File 'lib/jamf/api/mixins/searchable.rb', line 101

def search_result_order_append(fieldname, dir = :asc)
  raise 'direction must be either :asc, or :desc' unless SORT_DIRECTIONS.key? dir
  search_result_order << { field: fieldname, direction: SORT_DIRECTIONS[dir] }
end

#search_result_page_size ⇒ Object 



83
84
85
 
# File 'lib/jamf/api/mixins/searchable.rb', line 83

def search_result_page_size
  @search_result_page_size ||= 0
end

#search_result_page_size=(size) ⇒ Object 



87
88
89
90
 
# File 'lib/jamf/api/mixins/searchable.rb', line 87

def search_result_page_size=(size)
  raise 'Size must be a non-negative integer' unless size.is_a?(Integer) && size >= 0
  @search_result_page_size = size
end