ruby-jss 0.9.2 → 0.10.0a1

data/lib/jss/api_object/categorizable.rb

@@ -141,7 +141,7 @@ module JSS
       # no change, go home.
       return nil if new_name == @category_name
 
-      raise JSS::NoSuchItemError, "Category '#{new_cat}' is not known to the JSS" unless JSS::Category.all_names(:ref).include? new_name
+      raise JSS::NoSuchItemError, "Category '#{new_cat}' is not known to the JSS" unless JSS::Category.all_names(:ref, api: @api).include? new_name
 
       @category_name = new_name
       @category_id = new_id
@@ -149,7 +149,7 @@ module JSS
     end # category =
 
     # Given a category name or id, return the name and id
-    #
+    # TODO: use APIObject.exist? and/or APIObject.valid_id
     # @param new_cat[String, Integer] The name or id of a possible category
     #
     # @return [Array<String, Integer>] The matching name and id, which may be nil.
@@ -158,10 +158,10 @@ module JSS
       # if we were given anything but a string, assume it was an id.
       if new_cat.is_a? String
         new_name = new_cat
-        new_id = JSS::Category.category_id_from_name new_cat
+        new_id = JSS::Category.category_id_from_name new_cat, api: @api
       else
         new_id = new_cat
-        new_name = JSS::Category.map_all_ids_to(:name)[new_id]
+        new_name = JSS::Category.map_all_ids_to(:name, api: @api)[new_id]
       end
       [new_name, new_id]
     end

data/lib/jss/api_object/category.rb

@@ -50,10 +50,10 @@ module JSS
     # Class Methods
     #####################################
 
-    def self.category_id_from_name(name)
+    def self.category_id_from_name(name, api: JSS.api)
       return nil if name.nil?
       return nil if name.casecmp(JSS::Category::NO_CATEGORY_NAME).zero?
-      JSS::Category.map_all_ids_to(:name).invert[name]
+      JSS::Category.map_all_ids_to(:name, api: api).invert[name]
     end # self cat id from name
 
     # Class Constants

data/lib/jss/api_object/computer.rb

@@ -44,7 +44,12 @@ module JSS
   # * barcodes 1 and 2
   # * ip_address
   # * udid
-  # * mac_addresses
+  # * mac_address & alt_mac_address
+  # * serial_number
+  #   Note: Even tho the webUI doesn't allow editing the serial_number,
+  #   the API does, and it can be useful for dealing with duplicates
+  #   that arise when a logic-board swap causes a new computer record.
+  #   to be created.
   # * location data via the Locatable module
   # * purchasing data via the Purchasable module
   # * Extension Attribute values via the Extendable module
@@ -333,22 +338,28 @@ module JSS
     # Currently this is read-only in ruby-jss, even tho the API
     # allows updating.
     #
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
     # @return [Hash] the Computer Checkin Settings from the
     #   currently connected JSS.
     #
-    def self.checkin_settings
-      JSS.api_connection.get_rsrc(CHECKIN_RSRC)[CHECKIN_KEY]
+    def self.checkin_settings(api: JSS.api)
+      api.get_rsrc(CHECKIN_RSRC)[CHECKIN_KEY]
     end
 
     # Display the current Computer Inventory Collection settings in the JSS.
     # Currently this is read-only in ruby-jss, even tho the API
     # allows updating.
     #
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
     # @return [Hash] the Computer Inventpry Collection Settings from the
     #   currently connected JSS.
     #
-    def self.inventory_collection_settings
-      JSS.api_connection.get_rsrc(INV_COLLECTION_RSRC)[INV_COLLECTION_KEY]
+    def self.inventory_collection_settings(api: JSS.api)
+      api.get_rsrc(INV_COLLECTION_RSRC)[INV_COLLECTION_KEY]
     end
 
     # A larger set of info about the computers in the JSS.
@@ -365,82 +376,85 @@ module JSS
     #
     # @param refresh[Boolean] should the data be re-queried from the API?
     #
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
-    def self.all(refresh = false)
-      JSS.api.object_list_cache[RSRC_LIST_KEY] = nil if refresh
-      return JSS.api.object_list_cache[RSRC_LIST_KEY] if JSS.api.object_list_cache[RSRC_LIST_KEY]
-      JSS.api.object_list_cache[RSRC_LIST_KEY] = JSS.api_connection.get_rsrc(self::LIST_RSRC)[self::RSRC_LIST_KEY]
+    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)
-      all(refresh).map { |i| i[:serial_number] }
+    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)
-      all(refresh).map { |i| i[:mac_address] }
+    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)
-      all(refresh).map { |i| i[:udid] }
+    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)
-      all(refresh).select { |d| d[:managed] }
+    def self.all_managed(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:managed] }
     end
 
     # @return [Array<Hash>] all unmanaged computers in the jss
-    def self.all_unmanaged(refresh = false)
-      all(refresh).reject { |d| d[:managed] }
+    def self.all_unmanaged(refresh = false, api: JSS.api)
+      all(refresh, api: api).reject { |d| d[:managed] }
     end
 
     # @return [Array<Hash>] all laptop computers in the jss
-    def self.all_laptops(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /book/i }
+    def self.all_laptops(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /book/i }
     end
 
     # @return [Array<Hash>] all macbooks in the jss
-    def self.all_macbooks(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^macbook\d/i }
+    def self.all_macbooks(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^macbook\d/i }
     end
 
     # @return [Array<Hash>] all macbookpros in the jss
-    def self.all_macbookpros(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^macbookpro\d/i  }
+    def self.all_macbookpros(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^macbookpro\d/i  }
     end
 
     # @return [Array<Hash>] all macbookairs in the jss
-    def self.all_macbookairs(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^macbookair\d/i  }
+    def self.all_macbookairs(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^macbookair\d/i  }
     end
 
     # @return [Array<Hash>] all xserves in the jss
-    def self.all_xserves(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /serve/i }
+    def self.all_xserves(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /serve/i }
     end
 
     # @return [Array<Hash>] all desktop macs in the jss
-    def self.all_desktops(refresh = false)
-      all(refresh).reject { |d| d[:model] =~ /serve|book/i }
+    def self.all_desktops(refresh = false, api: JSS.api)
+      all(refresh, api: api).reject { |d| d[:model] =~ /serve|book/i }
     end
 
     # @return [Array<Hash>] all imacs in the jss
-    def self.all_imacs(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^imac/i }
+    def self.all_imacs(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^imac/i }
     end
 
     # @return [Array<Hash>] all mac minis in the jss
-    def self.all_minis(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^macmini/i }
+    def self.all_minis(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^macmini/i }
     end
 
     # @return [Array<Hash>] all macpros in the jss
-    def self.all_macpros(refresh = false)
-      all(refresh).select { |d| d[:model] =~ /^macpro/i }
+    def self.all_macpros(refresh = false, api: JSS.api)
+      all(refresh, api: api).select { |d| d[:model] =~ /^macpro/i }
     end
 
     # Send an MDM command to one or more managed computers by id or name
@@ -455,10 +469,13 @@ module JSS
     #
     # @param passcode[String] some commands require a 6-character passcode
     #
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
     # @return [String] The uuid of the MDM command sent, if applicable
     #  (blank pushes do not generate uuids)
     #
-    def self.send_mdm_command(targets, command, passcode = nil)
+    def self.send_mdm_command(targets, command, passcode = nil, api: JSS.api)
       raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless COMPUTER_MDM_COMMANDS.keys.include? command
 
       command = COMPUTER_MDM_COMMANDS[command]
@@ -475,10 +492,10 @@ module JSS
 
       # make sure its an array of ids
       targets.map! do |comp|
-        if all_ids.include? comp.to_i
+        if all_ids(api: api).include? comp.to_i
           comp.to_i
-        elsif all_names.include? comp
-          map_all_ids_to(:name).invert[comp]
+        elsif all_names(api: api).include? comp
+          map_all_ids_to(:name, api: api).invert[comp]
         else
           raise JSS::NoSuchItemError, "No computer found matching '#{comp}'"
         end # if
@@ -486,11 +503,12 @@ module JSS
 
       cmd_rsrc << "/id/#{targets.join ','}"
 
-      result = JSS::API.post_rsrc cmd_rsrc, nil
+      result = api.post_rsrc cmd_rsrc, nil
       result =~ %r{<command_uuid>(.*)</command_uuid>}
       Regexp.last_match(1)
     end # send mdm command
 
+
     # Attributes
     #####################################
 
@@ -814,6 +832,9 @@ module JSS
     # Get application usage data for this computer
     # for a given date range.
     #
+    # TODO: Make this a class method so we can retrieve it without
+    # instantiating the Computer.
+    #
     # @param start_date [String,Date,DateTime,Time]
     #
     # @param end_date [String,Date,DateTime,Time] Defaults to start_date
@@ -834,7 +855,7 @@ module JSS
       end
       start_date = start_date.strftime APPLICATION_USAGE_DATE_FMT
       end_date = end_date.strftime APPLICATION_USAGE_DATE_FMT
-      data = JSS.api_connection.get_rsrc(APPLICATION_USAGE_RSRC + "/id/#{@id}/#{start_date}_#{end_date}")
+      data = @api.get_rsrc(APPLICATION_USAGE_RSRC + "/id/#{@id}/#{start_date}_#{end_date}")
       parsed_data = {}
       data[APPLICATION_USAGE_KEY].each do |day_hash|
         date = Date.parse day_hash[:date]
@@ -854,6 +875,9 @@ module JSS
     # map the array to just those values, so subset: :smart_groups, only: :name
     # will return an array of names of smartgroups that contain this computer.
     #
+    # TODO: Make this a class method so we can retrieve it without
+    # instantiating the Computer.
+    #
     # @param subset[Symbol] Fetch only a subset of data, as an array.
     #    must be one of the symbols in MGMT_DATA_SUBSETS
     #
@@ -880,7 +904,7 @@ module JSS
       @management_data[:full] = nil if refresh
       return @management_data[:full] if @management_data[:full]
       mgmt_rsrc = MGMT_DATA_RSRC + "/id/#{@id}"
-      @management_data[:full] = JSS.api.get_rsrc(mgmt_rsrc)[MGMT_DATA_KEY]
+      @management_data[:full] = @api.get_rsrc(mgmt_rsrc)[MGMT_DATA_KEY]
       @management_data[:full]
     end
     private :full_management_data
@@ -890,7 +914,7 @@ module JSS
       @management_data[subset] = nil if refresh
       return @management_data[subset] if @management_data[subset]
       subset_rsrc = MGMT_DATA_RSRC + "/id/#{@id}/subset/#{subset}"
-      @management_data[subset] = JSS.api.get_rsrc(subset_rsrc)[MGMT_DATA_KEY]
+      @management_data[subset] = @api.get_rsrc(subset_rsrc)[MGMT_DATA_KEY]
       return @management_data[subset] unless only
       @management_data[subset].map { |d| d[only] }
     end
@@ -948,6 +972,9 @@ module JSS
     # WARNING! Its huge, better to use a subset a
     # nd one of the shortcut methods.
     #
+    # TODO: Make this a class method so we can retrieve it without
+    # instantiating the Computer.
+    #
     # @param subset[Symbol] the subset to return, rather than full history.
     #
     # @param refresh[Boolean] should we re-cache the data from the API?
@@ -969,7 +996,7 @@ module JSS
       @history[:full] = nil if refresh
       return @history[:full] if @history[:full]
       history_rsrc = HISTORY_RSRC + "/id/#{@id}"
-      @history[:full] = JSS.api.get_rsrc(history_rsrc)[HISTORY_KEY]
+      @history[:full] = @api.get_rsrc(history_rsrc)[HISTORY_KEY]
       @history[:full]
     end
     private :full_history
@@ -979,7 +1006,7 @@ module JSS
       @history[subset] = nil if refresh
       return @history[subset] if @history[subset]
       subset_rsrc = HISTORY_RSRC + "/id/#{@id}/subset/#{subset}"
-      @history[subset] = JSS.api.get_rsrc(subset_rsrc)[HISTORY_KEY]
+      @history[subset] = @api.get_rsrc(subset_rsrc)[HISTORY_KEY]
       @history[subset]
     end
     private :history_subset
@@ -1074,8 +1101,7 @@ module JSS
     def make_unmanaged
       return nil unless managed?
       set_management_to(nil, nil)
-      return unless mdm_capable
-      self.class.send_mdm_command(@id, :unmanage_device)
+      @unmange_at_update = true
     end
 
     #
@@ -1105,10 +1131,35 @@ module JSS
     #
     def ip_address=(new_val)
       return nil if @ip_address == new_val
-      new_val.strip!
-      # this raises an error if its an invalid IP address
-      IPAddr.new new_val
-      @ip_address = new_val
+      @ip_address = new_val.empty? ? new_val : JSS::Validate.ip_address(new_val)
+      @need_to_update = true
+    end
+
+    #
+    def mac_address=(new_val)
+      return nil if new_val == @mac_address
+      @mac_address =  new_val.empty? ? new_val : JSS::Validate.mac_address(new_val)
+      @need_to_update = true
+    end
+
+    #
+    def alt_mac_address=(new_val)
+      return nil if new_val == @alt_mac_address
+      @alt_mac_address = new_val.empty? ? new_val : JSS::Validate.mac_address(new_val)
+      @need_to_update = true
+    end
+
+    #
+    def serial_number=(new_val)
+      return nil if new_val == @serial_number
+      @serial_number =  new_val.empty? ? new_val : JSS::Validate.unique_identifier(JSS::Computer, :serial_number, new_val)
+      @need_to_update = true
+    end
+
+    #
+    def udid=(new_val)
+      return nil if new_val == @udid
+      @udid = new_val.empty? ? new_val : JSS::Validate.unique_identifier(JSS::Computer, :udid, new_val)
       @need_to_update = true
     end
 
@@ -1118,7 +1169,8 @@ module JSS
     #
     def update
       id = super
-      @management_password = nil
+      remove_mdm_profile if mdm_capable && managed? && @unmange_at_update
+      @unmange_at_update = false
       id
     end
 
@@ -1172,7 +1224,7 @@ module JSS
     # See JSS::Computer.send_mdm_command
     #
     def blank_push
-      self.class.send_mdm_command @id, :blank_push
+      self.class.send_mdm_command @id, :blank_push, api: @api
     end
     alias noop blank_push
     alias send_blank_push blank_push
@@ -1182,7 +1234,7 @@ module JSS
     # See JSS::Computer.send_mdm_command
     #
     def device_lock(passcode)
-      self.class.send_mdm_command @id, :device_lock, passcode
+      self.class.send_mdm_command @id, :device_lock, passcode, api: @api
     end
     alias lock device_lock
     alias lock_device device_lock
@@ -1192,7 +1244,7 @@ module JSS
     # See JSS::Computer.send_mdm_command
     #
     def erase_device(passcode)
-      self.class.send_mdm_command @id, :erase_device, passcode
+      self.class.send_mdm_command @id, :erase_device, passcode, api: @api
     end
     alias erase erase_device
     alias wipe erase_device
@@ -1206,7 +1258,7 @@ module JSS
     # See JSS::Computer.send_mdm_command
     #
     def remove_mdm_profile
-      self.class.send_mdm_command(@id, :unmanage_device)
+      self.class.send_mdm_command @id, :unmanage_device, api: @api
     end
 
     # aliases
@@ -1246,6 +1298,7 @@ module JSS
       general.add_element('ip_address').text = @ip_address
       general.add_element('mac_address').text = @mac_address
       general.add_element('udid').text = @udid
+      general.add_element('serial_number').text = @serial_number
 
       rmgmt = general.add_element('remote_management')
       rmgmt.add_element('managed').text = @managed

data/lib/jss/api_object/computer_invitation.rb

@@ -58,8 +58,8 @@ module JSS
     # Class Methods
     #####################################
 
-    def self.all_invitations
-      all.map { |ci| ci[:invitation]  }
+    def self.all_invitations(refresh = false, api: JSS.api)
+      all(refresh, api: api).map { |ci| ci[:invitation]  }
     end
 
     # Class Constants

data/lib/jss/api_object/creatable.rb

@@ -69,14 +69,18 @@ module JSS
     ###  Mixed-in Instance Methods
     #####################################
 
-    ### Create a new object in the JSS.
-    ###
-    ### @return [Integer] the jss ID of the newly created object
-    ###
-    def create
+    # Create a new object in the JSS.
+    #
+    # @param api[JSS::APIConnection] the API in which to create the object
+    #   Defaults to the API used to instantiate this object
+    #
+    # @return [Integer] the jss ID of the newly created object
+    #
+    def create(api: nil)
+      api ||= @api
       raise JSS::UnsupportedError, "Creating or editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless respond_to? :create
       raise AlreadyExistsError, "This #{self.class::RSRC_OBJECT_KEY} already exists. Use #update to make changes." if @in_jss
-      JSS.api_connection.post_rsrc(@rest_rsrc, rest_xml) =~ %r{><id>(\d+)</id><}
+      api.post_rsrc(@rest_rsrc, rest_xml) =~ %r{><id>(\d+)</id><}
       @id = Regexp.last_match(1).to_i
       @in_jss = true
       @need_to_update = false
@@ -88,12 +92,16 @@ module JSS
     ###
     ### @param name [String] the name for the new object
     ###
+    ### @param api[JSS::APIConnection] the API in which to create the object
+    ###  Defaults to the API used to instantiate this object
+    ###
     ### @return [APIObject] An uncreated clone of this APIObject with the given name
     ###
-    def clone(new_name)
+    def clone(new_name, api: nil)
+      api ||= @api
       raise JSS::UnsupportedError, 'This class is not creatable in via ruby-jss' unless respond_to? :create
       raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with that name" if \
-        self.class.all_names.include? new_name
+        self.class.all_names(:refresh, api: api).include? new_name
 
       orig_in_jss = @in_jss
       @in_jss = false
@@ -101,12 +109,15 @@ module JSS
       @id = nil
       orig_rsrc = @rest_rsrc
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape new_name}"
+      orig_api = @api
+      @api = api
 
       new_obj = dup
 
       @in_jss = orig_in_jss
       @id = orig_id
       @rest_rsrc = orig_rsrc
+      @api = orig_api
       new_obj.name = new_name
 
       new_obj