Module: JSS::Categorizable

Included in:
ConfigurationProfile, MacApplication, MobileDeviceApplication, Package, PatchTitle, Policy, Printer, Script
Defined in:
lib/jss/api_object/categorizable.rb,
lib/jss.rb

Overview

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 or Hash (the class names) which indicate if the contents of the :category key is a String (The category name) or a Hash (containing :name and :id)

  • call #add_category_to_xml(xmldoc) from their #rest_xml method if they are Updatable or Creatable

Constant Summary collapse

CATEGORIZABLE =

Module Constants

true
NO_CATEGORY_NAME =

When no category has been assigned, this is the 'name'

'No category assigned'.freeze
NO_CATEGORY_ID =

When no category has been assigned, this is the id

-1
NON_CATEGORIES =

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

[
  nil,
  '',
  0,
  NO_CATEGORY_NAME,
  NO_CATEGORY_ID
].freeze

Instance Method Summary collapse

Instance Method Details

#category=(new_cat) ⇒ void

This method returns an undefined value.

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

Parameters:

  • new_cat (Integer, String) —

    The new category

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/jss/api_object/categorizable.rb', line 132

def category=(new_cat)
  return nil unless updatable? || creatable?

  # unset the category? Use nil or an empty string
  if NON_CATEGORIES.include? new_cat
    unset_category
    return
  end

  new_name, new_id = evaluate_new_category(new_cat)

  # no change, go home.
  return nil if new_name == @category_name

  raise JSS::NoSuchItemError, "Category '#{new_cat}' is not known to the JSS" unless JSS::Category.all_names(:ref, api: @api).include? new_name

  @category_name = new_name
  @category_id = new_id
  @need_to_update = true
end

#category_assigned? ⇒ Boolean Also known as: categorized?

Does this object have a category assigned?

Returns:

  • (Boolean) —

    Does this object have a category assigned?



119
120
121
 
# File 'lib/jss/api_object/categorizable.rb', line 119

def category_assigned?
  !@category_name.nil?
end

#category_id ⇒ Integer

The id of the category for this object.

Returns:

  • (Integer) —

    The id of the category for this object.



102
103
104
 
# File 'lib/jss/api_object/categorizable.rb', line 102

def category_id
  @category_id
end

#category_name ⇒ String Also known as: category

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

Returns:

  • (String) —

    The name of the category for this object.



93
94
95
 
# File 'lib/jss/api_object/categorizable.rb', line 93

def category_name
  @category_name
end

#category_object ⇒ JSS::Category

The JSS::Category instance for this object's category

Returns:

  • (JSS::Category) —

    The JSS::Category instance for this object's category



110
111
112
113
 
# File 'lib/jss/api_object/categorizable.rb', line 110

def category_object
  return nil unless category_assigned?
  JSS::Category.fetch id: @category_id
end

#evaluate_new_category(new_cat) ⇒ Array<String, Integer>

Given a category name or id, return the name and id TODO: use APIObject.exist? and/or APIObject.valid_id

Parameters:

  • new_cat (String, Integer) —

    The name or id of a possible category

Returns:

  • (Array<String, Integer>) —

    The matching name and id, which may be nil.



159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/jss/api_object/categorizable.rb', line 159

def evaluate_new_category(new_cat)
  # if we were given anything but a string, assume it was an id.
  if new_cat.is_a? String
    new_name = new_cat
    new_id = JSS::Category.category_id_from_name new_cat, api: @api
  else
    new_id = new_cat
    new_name = JSS::Category.map_all_ids_to(:name, api: @api)[new_id]
  end
  [new_name, new_id]
end

#unset_category ⇒ void

This method returns an undefined value.

Set the category to nothing



175
176
177
178
179
180
181
 
# File 'lib/jss/api_object/categorizable.rb', line 175

def unset_category
  # no change, go home
  return nil if @category_name.nil?
  @category_name = nil
  @category_id = nil
  @need_to_update = true
end