class Jamf::PeripheralType
A peripheral_type in the JSS
.
A PeripheralType
(as opposed to an individual {Jamf::Peripheral}) is just an id, a name, and an Array
of Hashes describing the fields of data to be stored for peripherals of this type.
See {#fields} for a desciption of how field definitions are stored.
For manipulating the fields, see {#fields=}, {#set_field}, {#append_field}, {#prepend_field}, {#insert_field}, and {#delete_field}
@see Jamf::APIObject
Constants
- FIELD_TYPES
field types can be one of these, either
String
or Symbol- OBJECT_HISTORY_OBJECT_TYPE
the object type for this object in the object history table. See {APIObject#add_object_history_entry}
- RSRC_BASE
The base for REST resources of this class
- RSRC_LIST_KEY
the hash key used for the JSON list output of all objects in the
JSS
- RSRC_OBJECT_KEY
The hash key used for the JSON object output. It’s also used in various error messages
Public Class Methods
Initialize
Jamf::APIObject::new
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 92 def initialize(**args) 93 94 super 95 96 @fields = [] 97 if @init_data[:fields] 98 @init_data[:fields].each{ |f| @fields[f[:order]] = f } 99 end 100 end
Public Instance Methods
Add a new field to the end of the field list
@param field the new field data
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 184 def append_field(**field) 185 field_ok? field 186 @fields << field 187 order_fields 188 @need_to_update = true 189 end
Remove a field from the array of fields.
@param order which field to remove?
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 228 def delete_field(order) 229 if @fields[order] 230 raise Jamf::MissingDataError, "Fields can't be empty" if @fields.count == 1 231 @fields.delete_at index 232 order_fields 233 @need_to_update = true 234 end 235 end
The definitions of the fields stored for this peripheral type.
Each Hash
defines a field of data to store. The keys are:
-
:name,
String
, the name of the field -
:type,
String
or Symbol, the kind of data to be stored in the field, either :text or :menu -
:choices,
Array
of Strings - if type is :menu, these are the menu choices. -
:order, the one-based index of this field amongst it’s peers.
Since Arrays are zero-based, and the field order is one-based, keeping a nil at the front of the Array
will keep the :order number in sync with the Array
index of each field definition. This is done automatically by the field-editing methods: {#fields=}, {#set_field}, {#append_field}, {#prepend_field}, {#insert_field}, and {#delete_field}.
So the Array
from the API comes like this:
[ {:type=>"text", :order=>1, :choices=>[], :name=>"make"}, {:type=>"text", :order=>2, :choices=>[], :name=>"model"}, {:type=>"text", :order=>3, :choices=>[], :name=>"family"}, {:type=>"text", :order=>4, :choices=>[], :name=>"serialnum"} ]
But will be stored in a PeripheralType
instance like this:
[ nil, {:type=>"text", :order=>1, :choices=>[], :name=>"make"}, {:type=>"text", :order=>2, :choices=>[], :name=>"model"}, {:type=>"text", :order=>3, :choices=>[], :name=>"family"}, {:type=>"text", :order=>4, :choices=>[], :name=>"serialnum"} ]
therefore
myPerifType.fields[2]
will get you the second field, which has :order => 2.
@return [Array<Hash>] The field definitions
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 134 def fields 135 @fields 136 end
Replace the entire Array
of field definitions. The :order of each will be set based on the indexes of the Array
provided.
@param new_fields the new field definitions
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 147 def fields= (new_fields) 148 unless new_fields.kind_of? Array and new_fields.reject{|c| c.kind_of? Hash }.empty? 149 raise Jamf::InvalidDataError, "Argument must be an Array of Hashes." 150 end 151 raise "A peripheral type can have a maximmum of 20 fields" if new_fields.count > 20 152 new_fields.each{ |f| field_ok? f } 153 @fields = new_fields 154 order_fields 155 @need_to_update = true 156 end
Add a new field to the middle of the fields Array
.
@param order where does the new field go?
@param field the new field data
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 214 def insert_field(order, **field) 215 field_ok? field 216 @fields.insert((order -1), field) 217 order_fields 218 @need_to_update = true 219 end
Add a new field to the beginning of the field list
@param field the new field data
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 198 def prepend_field(**field) 199 field_ok? field 200 @fields.unshift field 201 order_fields 202 @need_to_update = true 203 end
Replace the details of one specific field.
The order must already exist. Otherwise use {#append_field}, {#prepend_field}, or {#insert_field}
@param order which field are we replacing?
@param field the new field data
@return [void]
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 170 def set_field(order, **field) 171 raise Jamf::NoSuchItemError, "No field with number '#{order}'. Use #append_field, #prepend_field, or #insert_field" unless @fields[order] 172 field_ok? field 173 @fields[order] = field 174 @need_to_update = true 175 end
Private Instance Methods
is a Hash
of field data OK for use in the JSS
? Return true or raise an exception
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 248 def field_ok?(field) 249 raise Jamf::InvalidDataError, "Field elements must be hashes with :name, :type, and possibly :choices" unless field.kind_of? Hash 250 raise Jamf::InvalidDataError, "Fields require names" if field[:name].to_s.empty? 251 raise Jamf::InvalidDataError, "Fields :type must be one of: :#{FIELD_TYPES.join(', :')}" unless FIELD_TYPES.include? field[:type].to_sym 252 253 if field[:type].to_sym == :menu 254 unless field[:choices].kind_of? Array and field[:choices].reject{|c| c.kind_of? String}.empty? 255 raise Jamf::InvalidDataError, "Choices for menu fields must be an Array of Strings" 256 end # unless 257 else 258 field[:choices] = [] 259 end # if type -- menu 260 true 261 end
Close up gaps in the field order, and make each field’s :order match it’s array index
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 266 def order_fields 267 @fields.compact! 268 @fields.each_index{|i| @fields[i][:order] = i+1} 269 @fields.unshift nil 270 end
# File lib/jamf/api/classic/api_objects/peripheral_type.rb 276 def rest_xml 277 order_fields 278 doc = REXML::Document.new Jamf::Connection::XML_HEADER 279 pkg = doc.add_element RSRC_OBJECT_KEY.to_s 280 pkg.add_element('id').text = @id 281 pkg.add_element('name').text = @name 282 fields = pkg.add_element 'fields' 283 284 flds = @fields.compact 285 flds.each_index do |i| 286 field = fields.add_element 'field' 287 field.add_element('order').text =flds[i][:order] 288 field.add_element('name').text = flds[i][:name] 289 field.add_element('type').text = flds[i][:type].to_s 290 choices = field.add_element('choices') 291 unless flds[i][:choices].empty? 292 flds[i][:choices].each{|c| choices.add_element('choice').text = c} 293 end 294 end # each index do i 295 return doc.to_s 296 end