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:
-
Define the constant CATEGORY_SUBSET as a symbol indicating where in the API data the :category key will be found. The symbol is either :top for the top-level of the API data, or the name of the subsection
Hash
containing :category, e.g. :general. -
Define the constant CATEGORY_DATA_TYPE as either
String
orHash
(the class names) which indicate if the contents of the :category key is aString
(The category name) or aHash
(containing :name and :id) -
call {#add_category_to_xml(xmldoc)} from their rest_xml method if they are {Updatable} or {Creatable}
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
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
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
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
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
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
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
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 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
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 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