ruby-jss 0.6.3

data/lib/jss/api_object/peripheral.rb

@@ -0,0 +1,335 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Classes
+  #####################################
+
+  ###
+  ### A peripheral in the JSS
+  ###
+  ### @see JSS::APIObject
+  ###
+  class Peripheral  < JSS::APIObject
+
+    #####################################
+    ### MixIns
+    #####################################
+
+    include JSS::Creatable
+    include JSS::Updatable
+
+    ### periphs have a purchasing subset
+    include JSS::Purchasable
+
+    ### periphs have a location subset, which will be
+    ### stored in primary attributes.
+    include JSS::Locatable
+
+    ### periphs can take uploaded files.
+    include JSS::Uploadable
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### The base for REST resources of this class
+    RSRC_BASE = "peripherals"
+
+    ### the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :peripherals
+
+    ### The hash key used for the JSON object output.
+    ### It's also used in various error messages
+    RSRC_OBJECT_KEY = :peripheral
+
+    ### these keys, as well as :id and :name, are present in valid API JSON data for this class
+    VALID_DATA_KEYS = [:type, :bar_code_1, :computer_id ]
+
+
+    #####################################
+    ### Class Variables
+    #####################################
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    ### @return [String] the type of peripheral
+    attr_reader :type
+
+    ### @return [String] the "bar code 1" value
+    attr_reader :bar_code_1
+    
+
+    ### @return [String] the "bar code 2" value
+    attr_reader :bar_code_2
+    
+
+    ### @return [Integer] the id number of the computer to which  this periph is connected
+    attr_reader :computer_id
+
+    #####################################
+    ### Instance Methods
+    #####################################
+
+    ###
+    ### @see APIObject
+    ###
+    def initialize (args = {})
+
+      ### periphs don't really have names, and the JSS module list method for
+      ### periphs gives the computer_id as the name, so give it a temp
+      ### name of "-1", which shouldn't ever exist in the JSS
+      args[:name] ||= "-1"
+
+      super
+
+      if args[:id] == :new
+        raise JSS::InvalidDataError, "New Peripherals must have a :type, which must be one of those defined in the JSS." unless args[:type]
+        @type = args[:type]
+        raise JSS::InvalidDataError, "No peripheral type '#{@type}' in the JSS" unless JSS::PeripheralType.all_names(:refresh).include? @type
+        @fields = {}
+        @rest_rsrc = 'peripherals/id/-1'
+        @site = "None"
+        return
+      end
+
+      @type =  @init_data[:general][:type]
+      @site = JSS::APIObject.get_name(@init_data[:general][:site])
+      @bar_code_1 = @init_data[:general][:bar_code_1]
+      @bar_code_2 = @init_data[:general][:bar_code_2]
+      @computer_id = @init_data[:general][:computer_id]
+
+      ### fill in the fields
+      @fields = {}
+      @init_data[:general][:fields].each{|f| @fields[f[:name]] = f[:value] }
+
+      ### get the field defs for this PeriphType, omitting the leading nil
+      @field_defs ||= JSS::PeripheralType.new(:name => @type).fields.compact
+
+      parse_location
+      parse_purchasing
+
+    end # initialize
+
+
+    ###
+    ### reset the restrsrc after creation
+    ###
+    ### @see JSS::Creatable#create
+    ###
+    def create
+      super
+      @rest_rsrc = "peripherals/id/#{@id}"
+      @id
+    end
+
+    ###
+    ### periphs don't have names
+    ###
+    def name= (newname)
+      raise JSS::UnsupportedError, "Peripherals don't have names."
+    end
+
+    ###
+    ###
+    ### @return [Hash] the field values of the peripheral
+    ###   Each key is the fields name, as a String
+    ###   and the value is the fields value, also as a String
+    ###
+    def fields
+      @fields
+    end
+
+    ###
+    ### Set the value of a field. It will be checked to ensure validity.
+    ###
+    ### @param field[String] the field to set
+    ###
+    ### @param value[String] the new value for the field
+    ###
+    ### @return [void]
+    ###
+    def set_field(field, value)
+      check_field(field, value)
+      @fields[field] = value
+      @need_to_update = true
+    end
+
+    ###
+    ### Set the value of barcode 1
+    ###
+    ### @param new_value[String] the new barcode value
+    ###
+    ### @return [void]
+    ###
+    def bar_code_1= (new_value)
+        @bar_code_1 = new_value
+        @need_to_update = true
+    end
+    
+
+    ###
+    ### Set the value of barcode 2
+    ###
+    ### @param new_value[String] the new barcode value
+    ###
+    ### @return [void]
+    ###
+    def bar_code_2= (new_value)
+        @bar_code_2 = new_value
+        @need_to_update = true
+    end
+    
+
+    ###
+    ### Associate this peripheral with a computer.
+    ###
+    ### @param computer[String,Integer] the name or id of a computer in the JSS
+    ###
+    ### @return [void]
+    ###
+    def associate(computer)
+      if computer =~ /^d+$/
+        raise JSS::NoSuchItemError, "No computer in the JSS with id #{computer}" unless JSS::Computer.all_ids.include? computer
+        @computer_id = computer
+      else
+        raise JSS::NoSuchItemError, "No computer in the JSS with name #{computer}" unless JSS::Computer.all_names.include? computer
+        @computer_id = JSS::Computer.map_all_ids_to(:name).invert[computer]
+      end
+      @need_to_update = true
+    end
+    
+
+    ###
+    ### Disassociate this peripheral from any computer.
+    ###
+    ### This seems to have no effect in the JSS,
+    ### the  computer/user/location data always shows the most recent.
+    ###
+    ### @return [void]
+    ###
+    def disassociate
+      @computer_id = nil
+      @need_to_update = true
+    end
+    
+
+    #################################
+    ### Private Methods below here
+    private
+
+    ###
+    ### check a field, the field name must match those defined in
+    ### the appropriate peripheral type.
+    ### If a field is a menu field, the value must also be one of those defined
+    ### in the periph type.
+    ### Raise an exception if wrong.
+    ###
+    def check_field(field, value)
+      ### get the field defs for this PeriphType, omitting the leading nil
+      @field_defs ||= JSS::PeripheralType.new(:name => @type).fields.compact
+
+      ### we must have the right number of fields, and they must have the same names
+      ### as the definition
+      required_fields = @field_defs.map{|f| f[:name]}
+      raise JSS::InvalidDataError, "Peripherals of type '#{@type}' doesn't have a field '#{field}', they only have: #{required_fields.join(', ')}" unless required_fields.include? field
+
+      ### any menu fields can only have values as defined by the type.
+      menu_flds = @field_defs.select{|f| f[:type] == "menu" }
+      menu_flds.each do |mf|
+        next unless mf[:name] == field
+        raise JSS::InvalidDataError, "The value for field '#{field}' must be one of: #{mf[:choices].join(', ')}" unless mf[:choices].include? value
+      end #if menu_flds.include? field
+
+    end # check fields
+
+    ###
+    ### Return the REST XML for this pkg, with the current values,
+    ### for saving or updating
+    ###
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      periph = doc.add_element RSRC_OBJECT_KEY.to_s
+
+      general = periph.add_element('general')
+      general.add_element('type').text = @type
+      general.add_element('site').add_element('name').text = @site
+      general.add_element('bar_code_1').text = @bar_code_1
+      general.add_element('bar_code_2').text = @bar_code_2
+      general.add_element('computer_id').text = @computer_id
+
+      fields = general.add_element('fields')
+      @fields.each do |n,v|
+        fld =  fields.add_element('field')
+        fld.add_element('name').text = n
+        fld.add_element('value').text = v
+      end
+
+      if has_location?
+        periph << location_xml
+      end
+      if has_purchasing?
+        periph << purchasing_xml
+      end
+
+      return doc.to_s
+    end # rest xml
+    
+    ### Aliases
+    alias barcode_1 bar_code_1
+    alias barcode1 bar_code_1
+    alias barcode_1= bar_code_1=
+    alias barcode1= bar_code_1=
+    
+    alias barcode_2 bar_code_2
+    alias barcode2 bar_code_2
+    alias barcode_2= bar_code_2=
+    alias barcode2= bar_code_2=
+    
+    alias assign_to associate
+    alias unassign disassociate
+    
+  end # class Peripheral
+end # module

data/lib/jss/api_object/peripheral_type.rb

@@ -0,0 +1,295 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+  #####################################
+  ### Classes
+  #####################################
+
+  ###
+  ### A peripheral_type in the JSS.
+  ###
+  ### A PeripheralType (as opposed to an individual {JSS::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 JSS::APIObject
+  ###
+  class PeripheralType  < JSS::APIObject
+
+    #####################################
+    ### MixIns
+    #####################################
+
+    include JSS::Creatable
+    include JSS::Updatable
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### The base for REST resources of this class
+    RSRC_BASE = "peripheraltypes"
+
+    ### the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :peripheral_types
+
+    ### The hash key used for the JSON object output.
+    ### It's also used in various error messages
+    RSRC_OBJECT_KEY = :peripheral_type
+
+    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
+    VALID_DATA_KEYS = [:fields]
+
+    ### field types can be one of these, either String or Symbol
+    FIELD_TYPES = [:text, :menu]
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    #####################################
+    ### Instance Methods
+    #####################################
+
+    ###
+    ### Initialize
+    ###
+    def initialize (args = {})
+
+      super
+
+      @fields = []
+      if @init_data[:fields]
+        @init_data[:fields].each{ |f|  @fields[f[:order]] = f }
+      end
+    end # initialize
+
+    ### 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
+    ###
+    def fields
+      @fields
+    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[Array<Hash>] the new field definitions
+    ###
+    ### @return [void]
+    ###
+    def fields= (new_fields)
+      unless new_fields.kind_of? Array and  new_fields.reject{|c| c.kind_of? Hash }.empty?
+        raise JSS::InvalidDataError, "Argument must be an Array of Hashes."
+      end
+      raise "A peripheral type can have a maximmum of 20 fields"  if new_fields.count > 20
+      new_fields.each{ |f| field_ok? f }
+      @fields = new_fields
+      order_fields
+      @need_to_update = true
+    end
+
+    ###
+    ### Replace the details of one specific field.
+    ###
+    ### The order must already exist. Otherwise use
+    ### {#append_field}, {#prepend_field}, or {#insert_field}
+    ###
+    ### @param order[Integer] which field are we replacing?
+    ###
+    ### @param field[Hash] the new field data
+    ###
+    ### @return [void]
+    ###
+    def set_field(order, field = {})
+      raise JSS::NoSuchItemError, "No field with number '#{order}'. Use #append_field, #prepend_field, or #insert_field" unless @fields[order]
+      field_ok? field
+      @fields[order] = field
+      @need_to_update = true
+    end
+
+    ###
+    ### Add a new field to the end of the field list
+    ###
+    ### @param field[Hash] the new field data
+    ###
+    ### @return [void]
+    ###
+    def append_field(field = {})
+      field_ok? field
+      @fields << field
+      order_fields
+      @need_to_update = true
+    end
+
+    ###
+    ### Add a new field to the beginning of the field list
+    ###
+    ### @param field[Hash] the new field data
+    ###
+    ### @return [void]
+    ###
+    def prepend_field(field = {})
+      field_ok? field
+      @fields.unshift field
+      order_fields
+      @need_to_update = true
+    end
+
+    ###
+    ### Add a new field to the middle of the fields Array.
+    ###
+    ### @param order[Integer] where does the new field go?
+    ###
+    ### @param field[Hash] the new field data
+    ###
+    ### @return [void]
+    ###
+    def insert_field(order,field = {})
+      field_ok? field
+      @fields.insert((order -1), field)
+      order_fields
+      @need_to_update = true
+    end
+
+    ###
+    ### Remove a field from the array of fields.
+    ###
+    ### @param order[Integer] which field to remove?
+    ###
+    ### @return [void]
+    ###
+    def delete_field(order)
+      if @fields[order]
+        raise JSS::MissingDataError, "Fields can't be empty" if @fields.count == 1
+        @fields.delete_at index
+        order_fields
+        @need_to_update = true
+      end
+    end
+
+
+
+    ##############################
+    ### private methods
+    ##############################
+    private
+
+    ###
+    ### is a Hash of field data OK for use in the JSS?
+    ### Return true or raise an exception
+    ###
+    def field_ok?(field)
+      raise JSS::InvalidDataError, "Field elements must be hashes with :name, :type, and possibly :choices" unless field.kind_of? Hash
+      raise JSS::InvalidDataError, "Fields require names" if field[:name].to_s.empty?
+      raise JSS::InvalidDataError, "Fields :type must be one of: :#{FIELD_TYPES.join(', :')}" unless FIELD_TYPES.include? field[:type].to_sym
+
+      if field[:type].to_sym == :menu
+        unless field[:choices].kind_of? Array and  field[:choices].reject{|c| c.kind_of? String}.empty?
+          raise JSS::InvalidDataError, "Choices for menu fields must be an Array of Strings"
+        end # unless
+      else
+        field[:choices] = []
+      end # if type -- menu
+      true
+    end # def field ok?
+
+    ###
+    ### Close up gaps in the field order, and make each field's :order match it's array index
+    ###
+    def order_fields
+      @fields.compact!
+      @fields.each_index{|i| @fields[i][:order] = i+1}
+      @fields.unshift nil
+    end
+
+
+    ###
+    ###
+    ###
+    def rest_xml
+      order_fields
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      pkg = doc.add_element RSRC_OBJECT_KEY.to_s
+      pkg.add_element('id').text = @id
+      pkg.add_element('name').text = @name
+      fields = pkg.add_element 'fields'
+
+      flds =  @fields.compact
+      flds.each_index do |i|
+        field = fields.add_element 'field'
+        field.add_element('order').text =flds[i][:order]
+        field.add_element('name').text = flds[i][:name]
+        field.add_element('type').text = flds[i][:type].to_s
+        choices = field.add_element('choices')
+        unless flds[i][:choices].empty?
+          flds[i][:choices].each{|c| choices.add_element('choice').text = c}
+        end
+      end # each index do i
+      return doc.to_s
+    end # rest xml
+
+  end # class Peripheral
+end # module