Module: JSS::Categorizable

Included in:
ConfigurationProfile, MobileDeviceApplication, Package, Policy, 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 which contains a String, being the category name.

2) A ‘new’ style, where the top-level :general Hash contains a :category key

which is a Hash with a :name and :id key.

This module can detect and handle either type.

Classes mixing in this module MUST:

  • 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’ and id used

'No category assigned'.freeze
NO_CATEGORY_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
OLD_STYLE_CATEGORY_CLASSES =

These classes use old-style categories in their data.

[
  JSS::Script,
  JSS::Package
].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:



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

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?



117
118
119
 
# File 'lib/jss/api_object/categorizable.rb', line 117

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.



100
101
102
 
# File 'lib/jss/api_object/categorizable.rb', line 100

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.



91
92
93
 
# File 'lib/jss/api_object/categorizable.rb', line 91

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



108
109
110
111
 
# File 'lib/jss/api_object/categorizable.rb', line 108

def category_object
  return nil unless category_assigned?
  JSS::Category.new 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.



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

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



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

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