Module: JSS::Extendable

Included in:
Computer, MobileDevice, User
Defined in:
lib/jss-api/api_object/extendable.rb,
lib/jss-api.rb

Overview

A mix-in module for handling extension attribute data for objects in the JSS.

This module provides standardized ways to deal with Extension Attribute data in objects that gather that data (Computers, MobileDevices, and Users). For working with the Extension Attributes themselves, see ExtensionAttribute and its subclasses.

API objects that have Extension Attribute data return it in an Array of Hashes, one for each defined ExtensionAttribute for the class; i.e. a Computer‘s Array has one Hash for each ComputerExtensionAttribute defined in the JSS.

The Hash keys are:

  • :id => the ExtAttr id

  • :name => the ExtAttr name

  • :type => the data type of the ExtAttr value

  • :value => the value for the ExtAttr for this object as of the last report.

Classes including this module must define the constant EXT_ATTRIB_CLASS specifying which ExtensionAttribute subclass defines the relevant extension attributes. For Example, Computer sets this:

EXT_ATTRIB_CLASS = JSS::ComputerExtensionAttribute

During initialization those classes must call #parse_ext_attrs to populate the @extension_attributes attribute from @init_data.

Parsing also populates @ext_attrs which is a Hash of name => value for each EA.

When updating or creating, those classes must add the REXML output of #ext_attr_xml to their rest_xml output.

Constant Summary collapse

EXTENDABLE = 
true
NUMERIC_TYPES =

ExtensionAttributes refer to the numeric data type as “Integer” but the ext. attr values that come with extendable objects refer to that data type as “Number”. Here’s an array with both, so we can work with ether more easily.

["Number", "Integer"]

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#ext_attrs ⇒ Hash (readonly)

Returns A mapping of Ext Attrib names to their values.

Returns:

  • (Hash) —

    A mapping of Ext Attrib names to their values



99
100
101
 
# File 'lib/jss-api/api_object/extendable.rb', line 99

def ext_attrs
  @ext_attrs
end

#extension_attributes ⇒ Array<Hash> (readonly)

Returns The extension attribute values for the object.

Returns:

  • (Array<Hash>) —

    The extension attribute values for the object



96
97
98
 
# File 'lib/jss-api/api_object/extendable.rb', line 96

def extension_attributes
  @extension_attributes
end

Instance Method Details

#ext_attr_xml ⇒ REXML::Element

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns An <extension_attribute> element to be included in the rest_xml of objects that mix-in this module.

Returns:

  • (REXML::Element) —

    An <extension_attribute> element to be included in the rest_xml of objects that mix-in this module.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/jss-api/api_object/extendable.rb', line 198

def ext_attr_xml

  eaxml = REXML::Element.new('extension_attributes')

  @extension_attributes.each do |ea|
    ea_el = eaxml.add_element('extension_attribute')
    ea_el.add_element('name').text = ea[:name]

    if ea[:type] == "Date"
      begin
        ea_el.add_element('value').text = ea[:value].to_jss_date
      rescue
        ea_el.add_element('value').text = ea[:value].to_s
      end
    else
      ea_el.add_element('value').text = ea[:value]
    end # if
  end # each do ea

  return eaxml
end

#parse_ext_attrs ⇒ void

This method returns an undefined value.

Populate @extension_attributes (the Array of Hashes that comes from the API) and @ext_attr_names, which is a Hash mapping the EA names to their index in the @extension_attributes Array.

Classes including this module should call this in #initialize



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
141
142
143
 
# File 'lib/jss-api/api_object/extendable.rb', line 116

def parse_ext_attrs

  unless @init_data[:extension_attributes]
    @extension_attributes = []
    @ext_attrs = {}
    return
  end

  @extension_attributes = @init_data[:extension_attributes]
  @ext_attrs = {}

  @extension_attributes.each do |ea|
    case ea[:type]

      when "Date"
        begin # if there's random non-date data, the parse will fail
          ea[:value] = JSS.parse_datetime ea[:value]
        rescue
        end

      when *NUMERIC_TYPES
        ea[:value] = ea[:value].to_i unless ea[:value].to_s.empty?
    end # case

    @ext_attrs[ea[:name]] = ea[:value]

  end # each do ea
end

#set_ext_attr(name, value) ⇒ void

This method returns an undefined value.

Set the value of an extension attribute

If the extension attribute is defined as a popup menu, the value must be one of the defined popup choices.

If the ext. attrib. is defined with a data type of Integer, the value must be an Integer.

If the ext. attrib. is defined with a data type of Date, the value will be converted to a Time

Parameters:

  • name (String) —

    the name of the extension attribute to set

  • value (String, Time, Time, Integer) —

    the new value for the extension attribute for this user



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/jss-api/api_object/extendable.rb', line 161

def set_ext_attr(name, value)

  # this will raise an exception if the name doesn't exist
  ea_def = self.class::EXT_ATTRIB_CLASS.new :name => name

  unless JSS::ExtensionAttribute::EDITABLE_INPUT_TYPES.include? ea_def.input_type
    raise JSS::UnsupportedError, "The value for #{name} cannot be modified. It is gathered during inventory updates."
  end

  if ea_def.input_type == "Pop-up Menu" and (not ea_def.popup_choices.include? value.to_s)
    raise JSS::UnsupportedError, "The value for #{name} must be one of: '#{ea_def.popup_choices.join("' '")}'"
  end

  case ea_def.data_type
    when "Date"

      value = JSS.parse_datetime value

    when *NUMERIC_TYPES
      raise  JSS::InvalidDataError, "The value for #{name} must be an integer" unless value.kind_of? Integer

  end #case

  @extension_attributes.each do |ea|
    ea[:value] = value if ea[:name] == name
  end
  @ext_attrs[name] = value

  @need_to_update = true
end