ruby-jss 1.0.4 → 1.1.0b1

data/lib/jss/api_object/account.rb

@@ -37,6 +37,9 @@ module JSS
 
   # A User or group in the JSS.
   #
+  # TODO: Split this into 2 classes, with lots of custom code.
+  # Thanks Jamf!
+  #
   # @see JSS::APIObject
   #
   class Account < JSS::APIObject
@@ -60,17 +63,28 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :account
 
-    # these keys,  as well as :id and :name, can be used to look up objects of this class in the JSS
+    # these keys,  as well as :id and :name, can be used to look up objects of
+    # this class in the JSS
     OTHER_LOOKUP_KEYS = {
-      userid: {rsrc_key: :userid, list: :all_user_ids},
-      username: {rsrc_key: :username, list: :all_user_names},
-      groupid: {rsrc_key: :groupid, list: :all_group_ids},
-      groupname: {rsrc_key: :groupname, list: :all_group_names}
+      userid: { fetch_rsrc_key: :userid },
+      username: { fetch_rsrc_key: :username },
+      groupid: { fetch_rsrc_key: :groupid },
+      groupname: { fetch_rsrc_key: :groupname }
     }.freeze
 
     # Class Methods
     #####################################
 
+    # override auto-defined method
+    def self.all_ids(_refresh = false, **_bunk)
+      raise '.all_ids is not valid for JSS::Account, use .all_user_ids or .all_group_ids'
+    end
+
+    # override auto-defined method
+    def self.all_names(_refresh = false, **_bunk)
+      raise '.all_names is not valid for JSS::Account, use .all_user_names or .all_group_names'
+    end
+
     # @return [Array<Hash>] all JSS account users
     def self.all_users(refresh = false, api: JSS.api)
       all(refresh, api: api)[:users]

data/lib/jss/api_object/advanced_search/advanced_computer_search.rb

@@ -65,9 +65,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :advanced_computer_search
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:sql_text, :display_fields, :computers].freeze
-
     # what kind of thing is returned by this search?
     RESULT_CLASS = JSS::Computer
 

data/lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb

@@ -59,9 +59,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :advanced_mobile_device_search
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:sql_text, :display_fields, :mobile_devices].freeze
-
     # what kind of thing is returned by this search?
     RESULT_CLASS = JSS::MobileDevice
 

data/lib/jss/api_object/advanced_search/advanced_user_search.rb

@@ -59,9 +59,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :advanced_user_search
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:criteria, :display_fields, :users].freeze
-
     # what kind of thing is returned by this search?
     RESULT_CLASS = JSS::User
 

data/lib/jss/api_object/building.rb

@@ -63,9 +63,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :building
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [].freeze
-
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}

data/lib/jss/api_object/category.rb

@@ -69,9 +69,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :category
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:priority].freeze
-
     # When no category has been assigned, this is the 'name' and id used
     NO_CATEGORY_NAME = JSS::Categorizable::NO_CATEGORY_NAME
     NO_CATEGORY_ID = JSS::Categorizable::NO_CATEGORY_ID

data/lib/jss/api_object/computer.rb

@@ -180,19 +180,35 @@ module JSS
     # Where is the Site data in the API JSON?
     SITE_SUBSET = :general
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    #   DEPRECATED, with be removed in a future release.
-    VALID_DATA_KEYS = %i[sus distribution_point alt_mac_address].freeze
-
-    # these keys,  as well as :id and :name, can be used to look up objects of this class in the JSS
+    # these keys,  as well as :id and :name, can be used to look up objects
+    # of this class in the JSS
+    #
+    # the wierd alises mac_addresse and macaddresse
+    # are for proper pluralization of 'mac_address' and such
     OTHER_LOOKUP_KEYS = {
-      udid: { rsrc_key: :udid, list: :all_udids },
-      serialnumber: { rsrc_key: :serialnumber, list: :all_serial_numbers },
-      serial_number: { rsrc_key: :serialnumber, list: :all_serial_numbers },
-      macaddress: { rsrc_key: :macaddress, list: :all_mac_addresses },
-      mac_address: { rsrc_key: :macaddress, list: :all_mac_addresses }
+      udid: {
+        aliases: [:uuid, :guid],
+        fetch_rsrc_key: :udid
+      },
+      serial_number: {
+        aliases: [:serialnumber, :sn],
+        fetch_rsrc_key: :serialnumber
+      },
+      mac_address: {
+        aliases: [
+          :mac_address,
+          :mac_addresse,
+          :macaddress,
+          :macaddresse,
+          :macaddr
+        ],
+        fetch_rsrc_key: :macaddress
+      }
+
     }.freeze
 
+    NON_UNIQUE_NAMES = true
+
     # This class lets us seach for computers
     SEARCH_CLASS = JSS::AdvancedComputerSearch
 
@@ -308,25 +324,28 @@ module JSS
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
     def self.all(refresh = false, api: JSS.api)
-      api.object_list_cache[RSRC_LIST_KEY] = nil if refresh
-      return api.object_list_cache[RSRC_LIST_KEY] if api.object_list_cache[RSRC_LIST_KEY]
-      api.object_list_cache[RSRC_LIST_KEY] = api.get_rsrc(self::LIST_RSRC)[self::RSRC_LIST_KEY]
-    end
-
-    # @return [Array<String>] all computer serial numbers in the jss
-    def self.all_serial_numbers(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |i| i[:serial_number] }
-    end
+      cache = api.object_list_cache
+      cache_key = self::RSRC_LIST_KEY
+      cache[cache_key] = nil if refresh
+      return cache[cache_key] if cache[cache_key]
 
-    # @return [Array<String>] all computer mac_addresses in the jss
-    def self.all_mac_addresses(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |i| i[:mac_address] }
+      cache[cache_key] = api.get_rsrc(self::LIST_RSRC)[cache_key]
     end
 
-    # @return [Array<String>] all computer udids in the jss
-    def self.all_udids(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |i| i[:udid] }
-    end
+    # # @return [Array<String>] all computer serial numbers in the jss
+    # def self.all_serial_numbers(refresh = false, api: JSS.api)
+    #   all(refresh, api: api).map { |i| i[:serial_number] }
+    # end
+    #
+    # # @return [Array<String>] all computer mac_addresses in the jss
+    # def self.all_mac_addresses(refresh = false, api: JSS.api)
+    #   all(refresh, api: api).map { |i| i[:mac_address] }
+    # end
+    #
+    # # @return [Array<String>] all computer udids in the jss
+    # def self.all_udids(refresh = false, api: JSS.api)
+    #   all(refresh, api: api).map { |i| i[:udid] }
+    # end
 
     # @return [Array<Hash>] all managed computers in the jss
     def self.all_managed(refresh = false, api: JSS.api)
@@ -785,7 +804,7 @@ module JSS
             identity: cert[:identity],
             name: cert[:name]
           }
-        end
+        end # map do cert
 
         # Freeze immutable things.
         # These are updated via recon, and aren't sent
@@ -798,6 +817,8 @@ module JSS
         @software.freeze
 
         @management_password = nil
+
+      # not in jss
       else
         @udid = args[:udid]
         @serial_number = args[:serial_number]
@@ -806,9 +827,43 @@ module JSS
         @alt_mac_address = args[:alt_mac_address]
         @barcode1 = args[:barcode_1]
         @barcode2 = args[:barcode_2]
-      end
+      end # if in jss
     end # initialize
 
+    # Make all the keys of the @hardware hash available as top-level methods
+    # on the Computer instance.
+    #
+    # This is done by catching method_missing and seeing if the method exists
+    # as key of @hardware, and if so, retuning that value, if not, passing on
+    # the method_missing call.
+    # So:
+    #    comp.processor_type
+    # is now the same as:
+    #    comp.hardware[:processor_type]
+    #
+    # The reason for using `method_missing` rather than looping through the
+    # @hardware hash during initialization and doing `define_method` is
+    # speed. When instantiating lots of computers, defining the methods
+    # for each one, when those methods may not be needed, just slows things
+    # down. This way, they're only used when needed.
+    #
+    # This method may be expanded in the future to handle other ad-hoc,
+    # top-level methods.
+    #
+    def method_missing(method, *args, &block)
+      if @hardware.key? method
+        @hardware[method]
+      else
+        super
+      end # if
+    end # def
+
+    # Companion to method_missing, allows for easier debugging in backtraces
+    # that involve missing methods.
+    def respond_to_missing?(method, *)
+      @hardware.key?(method) || super
+    end
+
     # @return [Array] the JSS groups to which thismachine belongs (smart and static)
     #
     def computer_groups

data/lib/jss/api_object/computer_invitation.rb

@@ -53,13 +53,6 @@ module JSS
     include JSS::Creatable
     include JSS::Sitable
 
-    # Class Methods
-    #####################################
-
-    def self.all_invitations(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |ci| ci[:invitation]  }
-    end
-
     # Class Constants
     #####################################
 
@@ -73,12 +66,9 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :computer_invitation
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:invitation].freeze
-
     # See JSS::APIObject
     OTHER_LOOKUP_KEYS = {
-      invitation: {rsrc_key: :invitation, list: :all_invitations}
+      invitation: { fetch_rsrc_key: :invitation }
     }.freeze
 
     # the object type for this object in

data/lib/jss/api_object/configuration_profile/osx_configuration_profile.rb

@@ -51,9 +51,6 @@ module JSS
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :os_x_configuration_profile
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = %i[distribution_method scope redeploy_on_update].freeze
-
     # Our scopes deal with computers
     SCOPE_TARGET_KEY = :computers
 

data/lib/jss/api_object/department.rb

@@ -70,9 +70,6 @@ module JSS
     ### It's also used in various error messages
     RSRC_OBJECT_KEY = :department
 
-    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = []
-
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}

data/lib/jss/api_object/distribution_point.rb

@@ -71,9 +71,6 @@ module JSS
     ### It's also used in various error messages
     RSRC_OBJECT_KEY = :distribution_point
 
-    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:read_only_username, :ssh_username, :is_master ]
-
     ### what  are the mount options? these are comma-separated, and are passed with -o
     MOUNT_OPTIONS = 'nobrowse'
 

data/lib/jss/api_object/extendable.rb

@@ -65,11 +65,7 @@ module JSS
 
     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 = %w[Number Integer].freeze
+    INVALID_DATE = '-- INVALIDLY FORMATTED DATE --'.freeze
 
     #  Attribtues
     ###################################
@@ -77,9 +73,6 @@ module JSS
     # @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
     ###################################
 
@@ -93,79 +86,124 @@ module JSS
     def parse_ext_attrs
       @extension_attributes = @init_data[:extension_attributes]
       @extension_attributes ||= []
-      @ext_attrs = {}
 
+      # remember changes as they happen so
+      # we only send changes back to the server.
+      @changed_eas = []
+    end
+
+    # @return [Array<String>] the names of all known EAs
+    #
+    def ea_names
+      ea_types.keys
+    end
+
+    # @return [Hash{String => String}] EA names => data type
+    #   (one of 'String', 'Number', or 'Date')
+    def ea_types
+      return @ea_types if @ea_types
+
+      @ea_types = {}
+      extension_attributes.each { |ea| @ea_types[ea[:name]] = ea[:type] }
+      @ea_types
+    end
+
+    # An easier-to-use hash of EA name to EA value.
+    # This isn't created until its needed, to speed up instantiation.
+    #
+    def ext_attrs
+      return @ext_attrs if @ext_attrs
+
+      @ext_attrs = {}
       @extension_attributes.each do |ea|
-        case ea[:type]
+        @ext_attrs[ea[:name]] =
+          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
-            true
-          end
+          when 'Date'
+            begin # if there's random non-date data, the parse will fail
+              JSS.parse_datetime ea[:value]
+            rescue
+              INVALID_DATE
+            end
 
-        when *NUMERIC_TYPES
-          ea[:value] = ea[:value].to_i unless ea[:value].to_s.empty?
-        end # case
+          when *JSS::ExtensionAttribute::NUMERIC_TYPES
+            ea[:value].to_i unless ea[:value].to_s.empty?
 
-        @ext_attrs[ea[:name]] = ea[:value]
+          else # String
+            ea[:value]
+          end # case
       end # each do ea
 
-      # remember changes as they happen so
-      # we only send changes back to the server.
-      @changed_eas = []
+      @ext_attrs
     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, or an empty string
+    # 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.
     #
-    # If the ext. attrib. is defined with a data type of Integer, the value must be an Integer.
+    # 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.
     #
-    # If the ext. attrib. is defined with a data type of Date, the value will be converted to a Time
+    # 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
     #
-    # 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.
+    # 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.
     #
     # @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
+    # @param value[String,Time,Integer] the new value for the extension
+    #   attribute for this user
+    #
+    # @param validate_popup_choice[Boolean] validate the new value against the E.A. definition.
+    #   Defaults to true.
+    #
+    # @param refresh[Boolean] Re-read the ext. attrib definition from the API,
+    #   for popup validation.
     #
     # @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.fetch name: name, api: api
+    def set_ext_attr(name, value, validate_popup_choice: true, refresh: false)
+      raise ArgumentError, "Unknown Extension Attribute Name: '#{name}'" unless ea_types.key? name
 
-      if ea_def.input_type == 'Pop-up Menu' && (!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
+      value ||= JSS::BLANK
+      validate_popup_value(name, value, refresh) if validate_popup_choice
 
-      unless value == JSS::BLANK
-        case ea_def.data_type
-        when 'Date'
-          value = JSS.parse_datetime value
+      case ea_types[name]
+      when JSS::ExtensionAttribute::DATA_TYPE_DATE
+        raise JSS::InvalidDataError, "The value for #{name} must be a date, cannot be blank" if value == JSS::BLANK
 
-        when *NUMERIC_TYPES
-          raise JSS::InvalidDataError, "The value for #{name} must be an integer" unless value.is_a? Integer
+        value = JSS.parse_datetime value
 
-        end # case
-      end # unless blank
+      when *JSS::ExtensionAttribute::NUMERIC_TYPES
+        raise JSS::InvalidDataError, "The value for #{name} must be an integer" unless value.is_a? Integer
 
-      been_set = false
-      @extension_attributes.each do |ea|
-        next unless ea[:name] == name
-        ea[:value] = value
-        been_set = true
-      end
-      unless been_set
-        @extension_attributes << { id: ea_def.id, name: name, type: ea_def.data_type, value: value }
-      end
-
-      @ext_attrs[name] = value
+      else # String
+        value = value.to_s
+      end # case
+
+      # update this ea hash in the @extension_attributes array
+      @extension_attributes.each { |ea| ea[:value] = value if ea[:name] == name }
+
+      # update the shortcut hash too
+      @ext_attrs[name] = value if @ext_attrs
       @changed_eas << name
       @need_to_update = true
     end
@@ -210,6 +248,24 @@ module JSS
       eaxml
     end
 
-  end # module Purchasable
+    # Used by set_ext_attr
+    def validate_popup_value(name, value, refresh)
+      # all popups can take blanks
+      return if value == JSS::BLANK
+
+      # get the ea def. instance from the api cache, or the api
+      api.ext_attr_definition_cache[self.class] ||= {}
+      api.ext_attr_definition_cache[self.class][name] = nil if refresh
+      api.ext_attr_definition_cache[self.class][name] ||= self.class::EXT_ATTRIB_CLASS.fetch name: name, api: api
+
+      ea_def = api.ext_attr_definition_cache[self.class][name]
+      return unless ea_def.from_popup_menu?
+
+      return if 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
+
+  end # module extendable
 
 end # module JSS