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

new(**args) click to toggle source

Initialize

Calls superclass method 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

append_field(**field) click to toggle source

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
delete_field(order) click to toggle source

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
fields() click to toggle source

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
fields=(new_fields) click to toggle source

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
insert_field(order, **field) click to toggle source

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
prepend_field(**field) click to toggle source

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
set_field(order, **field) click to toggle source

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

field_ok?(field) click to toggle source

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
order_fields() click to toggle source

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
rest_xml() click to toggle source
    # 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