Module: Jamf::Extendable
- Included in:
- Computer, MobileDevice, User
- Defined in:
- lib/jamf/api/classic/api_objects/extendable.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 = Jamf::ComputerExtensionAttribute
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 =
Constants
true
- INVALID_DATE =
'-- INVALIDLY FORMATTED DATE --'.freeze
Instance Attribute Summary collapse
-
#extension_attributes ⇒ Array<Hash>
readonly
The extension attribute values for the object.
Instance Method Summary collapse
-
#ea_names ⇒ Array<String>
The names of all known EAs.
-
#ea_types ⇒ Hash{String => String}
EA names => data type (one of ‘String’, ‘Number’, or ‘Date’).
-
#ext_attr_xml ⇒ REXML::Element
private
TODO: make this (and all XML amending) method take the in-progress XML doc and add (or not) the EA xml to it.
-
#ext_attrs ⇒ Object
An easier-to-use hash of EA name to EA value.
-
#parse_ext_attrs ⇒ void
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 values.
-
#set_ext_attr(ea_name, value, validate_popup_choice: true, refresh: false) ⇒ void
Set the value of an extension attribute.
-
#unsaved_eas? ⇒ Boolean
are there any changes in the EAs needing to be saved?.
-
#validate_ea_value(ea_name, value, validate_popup_choice, refresh) ⇒ Object
is the value being passed to set_ext_attr valid? Converts values as needed (e.g. strings to integers or Times).
-
#validate_integer_ea_value(ea_name, value) ⇒ Object
raise error if the value isn’t an integer.
-
#validate_popup_value(ea_name, value, refresh) ⇒ Object
Raise an error if the named EA has a popup menu, but the provided value isn’t one of the menu items.
Instance Attribute Details
Instance Method Details
#ea_names ⇒ Array<String>
Returns the names of all known EAs.
96 97 98 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 96 def ea_names ea_types.keys end |
#ea_types ⇒ Hash{String => String}
Returns EA names => data type (one of ‘String’, ‘Number’, or ‘Date’).
102 103 104 105 106 107 108 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 102 def ea_types return @ea_types if @ea_types @ea_types = {} extension_attributes.each { |ea| @ea_types[ea[:name]] = ea[:type] } @ea_types end |
#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.
TODO: make this (and all XML amending) method take the in-progress XML doc and add (or not) the EA xml to it. See how Sitable#add_site_to_xml works, as called from Computer.rest_xml
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 218 def ext_attr_xml @changed_eas ||= [] eaxml = REXML::Element.new('extension_attributes') @extension_attributes.each do |ea| next unless @changed_eas.include? ea[:name] 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].to_s end # if end # each do ea eaxml end |
#ext_attrs ⇒ Object
An easier-to-use hash of EA name to EA value. This isn’t created until its needed, to speed up instantiation.
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 113 def ext_attrs return @ext_attrs if @ext_attrs @ext_attrs = {} @extension_attributes.each do |ea| @ext_attrs[ea[:name]] = case ea[:type] when 'Date' begin # if there's random non-date data, the parse will fail Jamf.parse_time ea[:value] rescue INVALID_DATE end when *Jamf::ExtensionAttribute::NUMERIC_TYPES ea[:value].to_i unless ea[:value].to_s.empty? else # String ea[:value] end # case end # each do ea @ext_attrs 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 values. This is called during initialization for all objects that mix in this module
85 86 87 88 89 90 91 92 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 85 def parse_ext_attrs @extension_attributes = @init_data[:extension_attributes] @extension_attributes ||= [] # remember changes as they happen so # we only send changes back to the server. @changed_eas = [] end |
#set_ext_attr(ea_name, value, validate_popup_choice: true, refresh: false) ⇒ void
This method returns an undefined value.
Set the value of an extension attribute
The new value is validated based on the data type of the Ext. Attrib:
-
If the ext. attrib. is defined with a data type of Integer/Number, the value must be an Integer.
-
If defined with a data type of Date, the value will be parsed as a timestamp, and parsing may raise an exception. Dates can’t be blank.
-
If defined wth data type of String, ‘to_s` will be called on the value.
By default, the full EA definition object is fetched to see if the EA’s input type is ‘popup menu’, and if so, the new value must be one of the defined popup choices, or blank.
The EA definitions used for popup validation are cached, so we don’t have to reach out to the server every time. If you expect the definition to have changed since it was cached, provide a truthy value to the refresh: parameter
To bypass popup validation complepletely, provide a falsey value to the validate_popup_choice: parameter. WARNING: beware that your value is the correct type and format, or you might get errors when saving back to the API.
Note that while the Jamf Pro Web interface does not allow editing the values of Extension Attributes populated by Scripts or LDAP, the API does allow it. Bear in mind however that those values will be reset again at the next recon.
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 182 def set_ext_attr(ea_name, value, validate_popup_choice: true, refresh: false) raise ArgumentError, "Unknown Extension Attribute Name: '#{ea_name}'" unless ea_types.key? ea_name value = validate_ea_value(ea_name, value, validate_popup_choice, refresh) # update this ea hash in the @extension_attributes array ea_hash = @extension_attributes.find { |ea| ea[:name] == ea_name } raise Jamf::NoSuchItemError, "#{self.class} '#{name}'(id #{id}) does not know about ExtAttr '#{ea_name}'. Please re-fetch and try again." unless ea_hash ea_hash[:value] = value # update the shortcut hash too @ext_attrs[ea_name] = value if @ext_attrs @changed_eas << ea_name @need_to_update = true end |
#unsaved_eas? ⇒ Boolean
are there any changes in the EAs needing to be saved?
204 205 206 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 204 def unsaved_eas? @need_to_update && @changed_eas && !@changed_eas.empty? end |
#validate_ea_value(ea_name, value, validate_popup_choice, refresh) ⇒ Object
is the value being passed to set_ext_attr valid? Converts values as needed (e.g. strings to integers or Times)
If the EA is defined to hold a string, any value is accepted and converted with #to_s
Note: All EAs can be blank
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 262 def validate_ea_value(ea_name, value, validate_popup_choice, refresh) return Jamf::BLANK if value.to_s == Jamf::BLANK value = case ea_types[ea_name] when Jamf::ExtensionAttribute::DATA_TYPE_DATE Jamf.parse_time(value).to_s when *Jamf::ExtensionAttribute::NUMERIC_TYPES validate_integer_ea_value ea_name, value else value.to_s end # case validate_popup_value(ea_name, value, refresh) if validate_popup_choice value end |
#validate_integer_ea_value(ea_name, value) ⇒ Object
raise error if the value isn’t an integer
281 282 283 284 285 286 287 288 289 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 281 def validate_integer_ea_value(ea_name, value) if value.is_a? Integer value elsif value.to_s.jss_integer? value.to_s.to_i else raise Jamf::InvalidDataError, "The value for #{ea_name} must be an integer" end # if end |
#validate_popup_value(ea_name, value, refresh) ⇒ Object
Raise an error if the named EA has a popup menu, but the provided value isn’t one of the menu items
294 295 296 297 298 299 300 301 302 303 304 305 306 |
# File 'lib/jamf/api/classic/api_objects/extendable.rb', line 294 def validate_popup_value(ea_name, value, refresh) # get the ea def. instance from the api cache, or the api cnx.c_ext_attr_definition_cache[self.class] ||= {} cnx.c_ext_attr_definition_cache[self.class][ea_name] = nil if refresh cnx.c_ext_attr_definition_cache[self.class][ea_name] ||= self.class::EXT_ATTRIB_CLASS.fetch name: ea_name, cnx: cnx ea_def = cnx.c_ext_attr_definition_cache[self.class][ea_name] return unless ea_def. return if ea_def.popup_choices.include? value.to_s raise Jamf::UnsupportedError, "The value for #{ea_name} must be one of: '#{ea_def.popup_choices.join("' '")}'" end |