module Jamf::Categorizable

A mix-in module that centralizes the code for handling objects which can be assigned a ‘category’ in the JSS.

Objects in the JSS present category data in two different ways:

1) An ‘old’ style, where the top-level Hash of the API data contains a

:category key which contains a String, being the category name.

2) A ‘new’ style, where the :category key is a Hash with a :name and :id key.

This Hash is usually in the :general subset, but may be elsewhere.

Classes mixing in this module MUST:

Constants

CATEGORIZABLE

Module Constants

NON_CATEGORIES

Setting the category to any of these values will unset the category

NO_CATEGORY_ID

When no category has been assigned, this is the id

NO_CATEGORY_NAME

When no category has been assigned, this is the ‘name’

Public Instance Methods

categorized?()
Alias for: category_assigned?
category()
Alias for: category_name
category=(new_cat) click to toggle source

Change the category of this object. Any of the NON_CATEGORIES values will unset the category

@param new_cat[Integer, String] The new category

@return [void]

    # File lib/jamf/api/classic/api_objects/categorizable.rb
132 def category=(new_cat)
133   return nil unless updatable? || creatable?
134 
135   # unset the category? Use nil or an empty string
136   if NON_CATEGORIES.include? new_cat
137     unset_category
138     return
139   end
140 
141   new_name, new_id = evaluate_new_category(new_cat)
142 
143   # no change, go home.
144   return nil if new_name == @category_name
145 
146   raise Jamf::NoSuchItemError, "Category '#{new_cat}' is not known to the JSS" unless Jamf::Category.all_names(:ref, cnx: @cnx).include? new_name
147 
148   @category_name = new_name
149   @category_id = new_id
150   @need_to_update = true
151 end
category_assigned?() click to toggle source

Does this object have a category assigned?

@return [Boolean] Does this object have a category assigned?

    # File lib/jamf/api/classic/api_objects/categorizable.rb
119 def category_assigned?
120   !@category_name.nil?
121 end
Also aliased as: categorized?
category_id() click to toggle source

The id of the category for this object.

@return [Integer] The id of the category for this object.

    # File lib/jamf/api/classic/api_objects/categorizable.rb
102 def category_id
103   @category_id
104 end
category_name() click to toggle source

The name of the category for this object. For backward compatibility, this is aliased to just ‘category’

@return [String] The name of the category for this object.

   # File lib/jamf/api/classic/api_objects/categorizable.rb
93 def category_name
94   @category_name
95 end
Also aliased as: category
category_object() click to toggle source

The Jamf::Category instance for this object’s category

@return [Jamf::Category] The Jamf::Category instance for this object’s category

    # File lib/jamf/api/classic/api_objects/categorizable.rb
110 def category_object
111   return nil unless category_assigned?
112   Jamf::Category.fetch id: @category_id
113 end
evaluate_new_category(new_cat) click to toggle source

Given a category name or id, return the name and id TODO: use APIObject.exist? and/or APIObject.valid_id @param new_cat[String, Integer] The name or id of a possible category

@return [Array<String, Integer>] The matching name and id, which may be nil.

    # File lib/jamf/api/classic/api_objects/categorizable.rb
159 def evaluate_new_category(new_cat)
160   # if we were given anything but a string, assume it was an id.
161   if new_cat.is_a? String
162     new_name = new_cat
163     new_id = Jamf::Category.category_id_from_name new_cat, cnx: @cnx
164   else
165     new_id = new_cat
166     new_name = Jamf::Category.map_all_ids_to(:name, cnx: @cnx)[new_id]
167   end
168   [new_name, new_id]
169 end
unset_category() click to toggle source

Set the category to nothing

@return [void]

    # File lib/jamf/api/classic/api_objects/categorizable.rb
175 def unset_category
176   # no change, go home
177   return nil if @category_name.nil?
178   @category_name = nil
179   @category_id = nil
180   @need_to_update = true
181 end

Private Instance Methods

add_category_to_xml(xmldoc) click to toggle source

Add the category to the XML for POSTing or PUTting to the API.

@param xmldoc The in-construction XML document

@return [void]

    # File lib/jamf/api/classic/api_objects/categorizable.rb
221 def add_category_to_xml(xmldoc)
222   return if category_name.to_s.empty?
223   cat_elem = REXML::Element.new('category')
224 
225   if self.class::CATEGORY_DATA_TYPE == String
226     cat_elem.text = @category_name.to_s
227   elsif self.class::CATEGORY_DATA_TYPE == Hash
228     cat_elem.add_element('name').text = @category_name.to_s
229   else
230     raise Jamf::InvalidDataError, "Uknown CATEGORY_DATA_TYPE for class #{self.class}"
231   end
232 
233   root = xmldoc.root
234 
235   if self.class::CATEGORY_SUBSET == :top
236     root.add_element cat_elem
237     return
238   end
239 
240   parent = root.elements[self.class::CATEGORY_SUBSET.to_s]
241   parent ||= root.add_element self.class::CATEGORY_SUBSET.to_s
242   parent.add_element cat_elem
243 end
clean_raw_categories() click to toggle source

Set the category name and id to nil, if need be.

    # File lib/jamf/api/classic/api_objects/categorizable.rb
210 def clean_raw_categories
211   @category_name = nil if @category_name && @category_name.to_s.casecmp(NO_CATEGORY_NAME).zero?
212   @category_id = nil if @category_id == NO_CATEGORY_ID
213 end
parse_category() click to toggle source

Parse the category data from any incoming API data

@return [void] description_of_returned_object

    # File lib/jamf/api/classic/api_objects/categorizable.rb
191 def parse_category
192   cat =
193     if self.class::CATEGORY_SUBSET == :top
194       @init_data[:category]
195     else
196       @init_data[self.class::CATEGORY_SUBSET][:category]
197     end
198 
199   if cat.is_a? String
200     @category_name = cat
201     @category_id = Jamf::Category.category_id_from_name @category_name, cnx: @cnx
202   else
203     @category_name = cat[:name]
204     @category_id = cat[:id]
205   end
206   clean_raw_categories
207 end