ruby-jss 0.6.3

data/lib/jss/api_object/extendable.rb

@@ -0,0 +1,221 @@
+### 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
+  #####################################
+
+  #####################################
+  ### Sub-Modules
+  #####################################
+
+  ### 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  ({JSS::Computer}s, {JSS::MobileDevice}s,
+  ### and {JSS::User}s). For working with the Extension Attributes themselves, see
+  ### {JSS::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 {JSS::Computer}'s Array has one Hash for each {JSS::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 {JSS::ExtensionAttribute} subclass defines the relevant extension attributes.
+  ### For Example, {JSS::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.
+  ###
+  module Extendable
+
+    #####################################
+    ###  Constants
+    #####################################
+
+    ###
+    EXTENDABLE = true
+
+
+    ### 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.
+    NUMERIC_TYPES = ["Number", "Integer"]
+
+    #####################################
+    ###  Variables
+    #####################################
+
+    #####################################
+    ###  Attribtues
+    #####################################
+
+    ### @return [Array<Hash>] The extension attribute values for the object
+    attr_reader :extension_attributes
+
+    ### @return [Hash] A mapping of Ext Attrib names to their values
+    attr_reader :ext_attrs
+
+    #####################################
+    ###  Mixed-in Instance Methods
+    #####################################
+
+
+
+    ###
+    ### 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
+    ###
+    ### @return [void]
+    ###
+    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 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
+    ###
+    ### @param name[String] the name of the extension attribute to set
+    ###
+    ### @param value[String,Time,Time,Integer] the new value for the extension attribute for this user
+    ###
+    ### @return [void]
+    ###
+    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
+
+    ###
+    ### @api private
+    ###
+    ### @return [REXML::Element] An <extension_attribute> element to be
+    ###  included in the rest_xml of objects that mix-in this module.
+    ###
+    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
+
+  end # module Purchasable
+end # module JSS

data/lib/jss/api_object/extension_attribute.rb

@@ -0,0 +1,466 @@
+### 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
+
+
+
+  #####################################
+  ### Constants
+  #####################################
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  ####################################
+  ### Classes
+  #####################################
+
+
+  ###
+  ### The parent class of ExtensionAttribute objects in the JSS.
+  ###
+  ### The API extension attribute objects work with the definitions of extension
+  ### attributes, not the resulting values stored in the JSS with the inventory
+  ### reports.
+  ###
+  ### This superclass, however, uses the {AdvancedSearch} subclasses to provide
+  ### access to the reported values in two ways:
+  ### * A list of  target objects with a certain value for the ExtensionAttribute instance.
+  ###   See the {#all_with_result} method for details
+  ### * A list of the most recent value for this ExtensionAttribute in all targets in the JSS
+  ###
+  ### The {ComputerExtensionAttribute} subclass offers a {ComputerExtensionAttribute#history}
+  ### method providing the history of values for the EA for one computer. This requires
+  ### MySQL access to the JSS database since that history isn't available via the API.
+  ###
+  ### Subclasses of ExtensionAttribute must define these constants:
+  ### * TARGET_CLASS - the {APIObject} subclass to which the extention attribute applies.
+  ###   e.g. {JSS::Computer}
+  ###
+  ### * ALL_TARGETS_CRITERION - a {JSS::Criteriable::Criterion} instance that will be used in
+  ###   an {AdvancedSearch} to find all of members of the TARGET_CLASS
+  ###
+  ### @see JSS::APIObject
+  ###
+  class ExtensionAttribute < JSS::APIObject
+
+    #####################################
+    ### Mix-Ins
+    #####################################
+    include JSS::Creatable
+    include JSS::Updatable
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### What kinds of data can be created by EAs?
+    ### Note, Dates must be in the format "YYYY-MM-DD hh:mm:ss"
+    DATA_TYPES = ["String", "Date", "Integer"]
+    DEFAULT_DATA_TYPE = "String"
+
+    ### Where does the data come from?
+    INPUT_TYPES = [ "Text Field", "Pop-up Menu", "script", "LDAP Attribute Mapping"]
+    DEFAULT_INPUT_TYPE = "Text Field"
+
+    ### These input types can be modified, the others cannot.
+    EDITABLE_INPUT_TYPES = ["Text Field", "Pop-up Menu"]
+
+    ### Where can it be displayed in the WebApp?
+    ### subclasses can add to this list
+    WEB_DISPLAY_CHOICES = [
+      "General",
+      "Operating System",
+      "Hardware",
+      "User and Location",
+      "Purchasing",
+      "Extension Attributes"
+    ]
+    DEFAULT_WEB_DISPLAY_CHOICE = "Extension Attributes"
+
+    LAST_RECON_FIELD = 'Last Inventory Update'
+    LAST_RECON_FIELD_SYM = LAST_RECON_FIELD.gsub(' ', '_').to_sym
+
+    USERNAME_FIELD = "Username"
+    USERNAME_FIELD_SYM = USERNAME_FIELD.to_sym
+
+    ######################
+    ### Attributes
+    ######################
+
+    ### :id, :name, :in_jss, :need_to_update, and :rest_rsrc come from JSS::APIObject
+
+    ### @return [String] description of the ext attrib
+    attr_reader :description
+
+    ### @return [String] the type of data created by the EA. Must be one of DATA_TYPES
+    attr_reader :data_type
+
+    ### @return [String]  where does this data come from? Must be one of the INPUT_TYPES.
+    attr_reader :input_type
+
+    ### @return [Array<String>] the choices available in the UI when the @input_type is "Pop-up Menu"
+    attr_reader :popup_choices
+
+    ### @return [String] In which part of the web UI does the data appear?
+    attr_reader :web_display
+
+
+
+    #####################################
+    ### Constructor
+    #####################################
+
+    ###
+    ### @see JSS::APIObject#initialize
+    ###
+    def initialize(args = {})
+
+      super args
+
+      ### @init_data now has the raw data
+      ### so fill in our attributes or set defaults
+
+      @description = @init_data[:description]
+      @data_type = @init_data[:data_type] || DEFAULT_DATA_TYPE
+      @web_display = @init_data[:inventory_display] || DEFAULT_WEB_DISPLAY_CHOICE
+
+
+      if @init_data[:input_type]
+        @input_type = @init_data[:input_type][:type] || DEFAULT_INPUT_TYPE
+        @popup_choices = @init_data[:input_type][:popup_choices]
+      else
+        @input_type = DEFAULT_INPUT_TYPE
+      end
+
+      ### the name of the EA might have spaces and caps, which the will come to us as symbols with the spaces
+      ### as underscores, like this.
+      @symbolized_name = @name.gsub(' ','_').to_sym
+
+    end # init
+
+    #####################################
+    ### Public Instance Methods
+    #####################################
+
+    ###
+    ### @see JSS::Creatable#create
+    ###
+    def create
+      if @input_type == "Pop-up Menu"
+          raise MissingDataError, "No popup_choices set for Pop-up Menu input_type." unless @popup_choices.kind_of? Array and (not @popup_choices.empty?)
+      end
+      super
+    end
+
+    ###
+    ### @see JSS::Updatable#update
+    ###
+    def update
+      if @input_type == "Pop-up Menu"
+          raise MissingDataError, "No popup_choices set for Pop-up Menu input_type." unless @popup_choices.kind_of? Array and (not @popup_choices.empty?)
+      end
+      super
+    end
+
+
+    ###
+    ### @see JSS::APIObject#delete
+    ###
+    def delete
+      orig_open_timeout = JSS::API.cnx.options[:open_timeout]
+      orig_timeout = JSS::API.cnx.options[:timeout]
+      JSS::API.timeout = orig_timeout + 1800
+      JSS::API.open_timeout = orig_open_timeout + 1800
+      begin
+        super
+      ensure
+        JSS::API.timeout = orig_timeout
+        JSS::API.open_timeout = orig_open_timeout
+      end
+    end
+
+    ###
+    ### Change the description of this EA
+    ###
+    ### @param new_val[String] the new value
+    ###
+    ### @return [void]
+    ###
+    def description= (new_val)
+      return nil if @description == new_val
+      @description = new_val
+      @need_to_update = true
+    end #  name=(newname)
+
+    ###
+    ### Change the data type of this EA
+    ###
+    ### @param new_val[String] the new value, which must be a member of DATA_TYPES
+    ###
+    ### @return [void]
+    ###
+    def data_type= (new_val)
+      return nil if @data_type == new_val
+      raise JSS::InvalidDataError, "data_type must be a string, one of: #{DATA_TYPES.join(", ")}" unless DATA_TYPES.include? new_val
+      @data_type = new_val
+      @need_to_update = true
+    end #
+
+
+    ###
+    ### Change the inventory_display of this EA
+    ###
+    ### @param new_val[String] the new value, which must be a member of INVENTORY_DISPLAY_CHOICES
+    ###
+    ### @return [void]
+    ###
+    def web_display= (new_val)
+      return nil if @web_display == new_val
+      raise JSS::InvalidDataError, "inventory_display must be a string, one of: #{INVENTORY_DISPLAY_CHOICES.join(", ")}" unless WEB_DISPLAY_CHOICES.include? new_val
+      @web_display = new_val
+      @need_to_update = true
+    end #
+
+
+    ###
+    ### Change the input type of this EA
+    ###
+    ### @param new_val[String] the new value, which must be a member of INPUT_TYPES
+    ###
+    ### @return [void]
+    ###
+    def input_type= (new_val)
+      return nil if @input_type == new_val
+      raise JSS::InvalidDataError, "input_type must be a string, one of: #{INPUT_TYPES.join(", ")}" unless INPUT_TYPES.include? new_val
+      @input_type = new_val
+      @popup_choices = nil if @input_type == "Text Field"
+      @need_to_update = true
+    end #
+
+    ###
+    ### Change the Popup Choices of this EA
+    ### New value must be an Array, the items will be converted to Strings.
+    ###
+    ### This automatically sets input_type to "Pop-up Menu"
+    ###
+    ### Values are checked to ensure they match the @data_type
+    ### Note, Dates must be in the format "YYYY-MM-DD hh:mm:ss"
+    ###
+    ### @param new_val[Array<#to_s>] the new values
+    ###
+    ### @return [void]
+    ###
+    def popup_choices= (new_val)
+      return nil if @popup_choices == new_val
+      raise JSS::InvalidDataError, "popup_choices must be an Array" unless new_val.kind_of?(Array)
+
+      ### convert each one to a String,
+      ### and check that it matches the @data_type
+      new_val.map! do |v|
+        v = v.to_s.strip
+        case @data_type
+          when "Date"
+            raise JSS::InvalidDataError, "data_type is Date, but '#{v}' is not formatted 'YYYY-MM-DD hh:mm:ss'" unless v =~ /^\d{4}(-\d\d){2} (\d\d:){2}\d\d$/
+          when "Integer"
+            raise JSS::InvalidDataError, "data_type is Integer, but '#{v}' is not one" unless v =~ /^\d+$/
+        end
+        v
+      end
+      self.input_type = "Pop-up Menu"
+      @popup_choices = new_val
+      @need_to_update = true
+    end #
+
+
+    ###
+    ### Get an Array of Hashes for all inventory objects
+    ### with a desired result in their latest report for this EA.
+    ###
+    ### Each Hash is one inventory object (computer, mobile device, user), with these keys:
+    ###   :id - the computer id
+    ###   :name - the computer name
+    ###   :value - the matching ext attr value for the objects latest report.
+    ###
+    ### This is done by creating a temprary {AdvancedSearch} for objects with matching
+    ### values in the EA field, then getting the #search_results hash from it.
+    ###
+    ### The AdvancedSearch is then deleted.
+    ###
+    ### @param search_type[String] how are we comparing the stored value with the desired value.
+    ### must be a member of JSS::Criterion::SEARCH_TYPES
+    ###
+    ### @param desired_value[String] the value to compare with the stored value to determine a match.
+    ###
+    ### @return [Array<Hash{:id=>Integer,:name=>String,:value=>String,Integer,Time}>] the items that match the result.
+    ###
+    def all_with_result(search_type, desired_value)
+      raise JSS::NoSuchItemError, "EA Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY}." unless @in_jss
+      raise JSS::InvalidDataError, "Invalid search_type, see JSS::Criteriable::Criterion::SEARCH_TYPES" unless JSS::Criteriable::Criterion::SEARCH_TYPES.include? search_type.to_s
+      begin
+
+        search_class = self.class::TARGET_CLASS::SEARCH_CLASS
+        acs = search_class.new :id => :new, :name => "JSSgem-EA-#{Time.now.to_jss_epoch}-result-search"
+        acs.display_fields = [@name]
+        crit_list = [JSS::Criteriable::Criterion.new(:and_or => "and", :name => @name, :search_type => search_type.to_s, :value => desired_value)]
+        acs.criteria = JSS::Criteriable::Criteria.new crit_list
+
+        acs.create :get_results
+
+        results = []
+
+        acs.search_results.each{ |i|
+          value = case @data_type
+            when "Date" then JSS.parse_datetime i[@symbolized_name]
+            when "Integer" then i[@symbolized_name].to_i
+            else i[@symbolized_name]
+          end # case
+          results << {:id => i[:id], :name => i[:name], :value => value}
+        }
+
+      ensure
+        acs.delete
+      end
+      results
+    end
+
+
+
+    ### Return an Array of Hashes showing the most recent value
+    ### for this EA on all inventory objects in the JSS.
+    ###
+    ### Each Hash is one inventory object (computer, mobile device, user), with these keys:
+    ###   :id - the jss id
+    ###   :name - the object (computer, user, mobiledevice) name
+    ###   :value - the most recent ext attr value for the object.
+    ###   :as_of - the timestamp of when the value was collected (nil for User EAs)
+    ###   :username - the username associated with the object
+    ###
+    ### This is done by creating a temporary {AdvancedSearch}
+    ### for all objects, with the EA as a display field. The #search_result
+    ### then contains the desired data.
+    ###
+    ### The AdvancedSearch is then deleted.
+    ###
+    ### @return [Array<Hash{:id=>Integer,:name=>String,:value=>String,Integer,Time,:as_of=>Time}>]
+    ###
+    ### @see JSS::AdvancedSearch
+    ###
+    ### @see JSS::AdvancedComputerSearch
+    ###
+    ### @see JSS::AdvancedMobileDeviceSearch
+    ###
+    ### @see JSS::AdvancedUserSearch
+    ###
+    def latest_values
+      raise JSS::NoSuchItemError, "EA Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY}." unless @in_jss
+      tmp_advsrch = "JSSgem-EA-#{Time.now.to_jss_epoch}-latest-search"
+
+      begin
+        search_class = self.class::TARGET_CLASS::SEARCH_CLASS
+        acs = search_class.new :id => :new, :name => tmp_advsrch
+        acs.display_fields = self.class::TARGET_CLASS == JSS::User ?  [@name, USERNAME_FIELD] : [@name, USERNAME_FIELD, LAST_RECON_FIELD]
+
+        # search for 'Username like "" ' because all searchable object classes have a "Username" value
+        crit =  JSS::Criteriable::Criterion.new(:and_or => "and", :name => "Username", :search_type => "like", :value => '')
+        # crit = self.class::ALL_TARGETS_CRITERION
+        acs.criteria = JSS::Criteriable::Criteria.new [crit]
+        acs.create :get_results
+
+        results = []
+
+        acs.search_results.each do |i|
+          value = case @data_type
+            when "Date" then JSS.parse_datetime i[@symbolized_name]
+            when "Integer" then i[@symbolized_name].to_i
+            else i[@symbolized_name]
+          end # case
+
+          as_of = Time.parse(i[LAST_RECON_FIELD_SYM]) if i[LAST_RECON_FIELD_SYM]
+
+          results << {:id => i[:id], :name => i[:name], :username => i[USERNAME_FIELD_SYM] , :value => value, :as_of => as_of }
+        end #acs.search_results.each
+
+      ensure
+        acs.delete
+        self.class::TARGET_CLASS::SEARCH_CLASS.new(:name => tmp_advsrch).delete if self.class::TARGET_CLASS::SEARCH_CLASS.all_names(:refresh).include? tmp_advsrch
+      end
+
+      results
+
+    end
+
+
+    ### aliases
+
+    alias desc description
+
+
+
+    ######################
+    ### Private Instance Methods
+    #####################
+
+    private
+
+    ###
+    ### Return a REXML object for this ext attr, with the current values.
+    ### Subclasses should augment this in their rest_xml methods
+    ### then return it .to_s, for saving or updating
+    ###
+    def rest_rexml
+      ea = REXML::Element.new self.class::RSRC_OBJECT_KEY.to_s
+      ea.add_element('name').text = @name
+      ea.add_element('description').text = @description
+      ea.add_element('data_type').text = @data_type
+      ea.add_element('inventory_display').text = @web_display
+
+      it = ea.add_element('input_type')
+      it.add_element('type').text = @input_type
+      if @input_type == "Pop-up Menu"
+        pcs = it.add_element('popup_choices')
+        @popup_choices.each{|pc| pcs.add_element('choice').text = pc}
+      end
+      return ea
+    end # rest xml
+
+
+  end # class ExtAttrib
+
+end # module JSS
+
+require "jss/api_object/extension_attribute/computer_extension_attribute"
+require "jss/api_object/extension_attribute/mobile_device_extension_attribute"
+require "jss/api_object/extension_attribute/user_extension_attribute"