ruby-jss 2.0.0b1 → 2.0.0rc1

data/lib/jamf/api/classic/api_objects/distribution_point.rb

@@ -107,27 +107,18 @@ module Jamf
     def self.master_distribution_point(refresh = false, default: nil, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      @master_distribution_point = nil if refresh
-      return @master_distribution_point if @master_distribution_point
-
       all_ids(refresh, cnx: cnx).each do |dp_id|
         dp = fetch id: dp_id, cnx: cnx
-        if dp.master?
-          @master_distribution_point = dp
-          break
-        end
+        return dp if dp.master?
       end
 
-      # If we're here, the Cloud DP might be master, but there's no
-      # access to it in the API :/
-      raise Jamf::NoSuchItemError, 'No Master FileShare Distribtion Point. Use the default: parameter if needed.' unless @master_distribution_point || default
-
-      if @master_distribution_point
-        @master_distribution_point
-      elsif default == :random
-        @master_distribution_point = fetch(id: all_ids.sample, cnx: cnx)
+      case default
+      when :random
+        fetch id: all_ids.sample, cnx: cnx
+      when nil
+        raise Jamf::NoSuchItemError, 'No Master FileShare Distribtion Point. Use the default: parameter if needed.'
       else
-        @master_distribution_point = fetch(default, cnx: cnx)
+        fetch default, cnx: cnx
       end
     end
 
@@ -267,38 +258,9 @@ module Jamf
     # @return [String] the ssh password as a SHA256 digest
     attr_reader :ssh_password_sha256
 
-    # As well as the standard :id, :name, and :data, you can
-    # instantiate this class with :id => :master, in which case you'll
-    # get the Master Distribution Point as defined in the JSS.
-    # An error will be raised if one hasn't been defined.
-    #
-    # You can also do this more easily by calling JSS.master_distribution_point
-    #
     def initialize(**args)
-      # TODO: this looks redundant with super....
-      args[:cnx] ||= args[:api]
-      args[:cnx] ||= Jamf.cnx
-
-      @cnx = args[:cnx]
-
-      @init_data = nil
-
-      # looking for master?
-      if args[:id] == :master
-
-        self.class.all_ids(cnx: @cnx).each do |id|
-          @init_data = @cnx.c_get("#{RSRC_BASE}/id/#{id}")[RSRC_OBJECT_KEY]
-          if @init_data[:is_master]
-            @id = @init_data[:id]
-            @name = @init_data[:name]
-            break
-          end # if data is master
-          @init_data = nil
-        end # each id
-      end # if args is master
-
-      super(args) if @init_data.nil?
-
+      super 
+      
       @ip_address = @init_data[:ip_address]
       @local_path = @init_data[:local_path]
       @enable_load_balancing = @init_data[:enable_load_balancing]
@@ -365,7 +327,7 @@ module Jamf
                when :ro then @read_only_password_sha256
                when :http then @http_password_sha256
                when :ssh then @ssh_password_sha256
-      end # case
+               end # case
 
       return nil if sha256 == EMPTY_PW_256
 
@@ -449,7 +411,7 @@ module Jamf
                    JSS.stdin line
                  else
                    pw
-      end
+                 end
 
       pwok = check_pw(access, password)
       unless pwok
@@ -466,7 +428,7 @@ module Jamf
                  when 'smb' then '/sbin/mount_smbfs'
                  when 'afp' then '/sbin/mount_afp'
                  else raise "Can't mount distribution point #{@name}: no known connection type."
-      end
+                 end
 
       @mountpoint.mkpath
 

data/lib/jamf/api/classic/api_objects/mobile_device_application.rb

@@ -50,7 +50,6 @@ module Jamf
     include Jamf::VPPable
     include Jamf::Sitable
 
-
     # Class Methods
     #####################################
 
@@ -162,6 +161,10 @@ module Jamf
     #   does its backups (to icloud or itunes)?
     attr_reader :prevent_backup_of_app_data
 
+    # @return [Boolean] Should this app auto-update on devices?
+    attr_reader :keep_app_updated_on_devices
+    alias auto_update? keep_app_updated_on_devices
+
     # @return [Boolean] should the JSS update the icon and description from the app
     #   source?
     attr_reader :keep_description_and_icon_up_to_date
@@ -185,7 +188,6 @@ module Jamf
     #   which contains a plist <dict> element with config data.
     attr_reader :configuration_prefs
 
-
     # Constructor
     #####################################
 
@@ -208,6 +210,7 @@ module Jamf
       @itunes_country_region = general[:itunes_country_region]
       @itunes_sync_time = general[:itunes_sync_time]
       @deploy_as_managed_app = general[:deploy_as_managed_app]
+      @keep_app_updated_on_devices = general[:keep_app_updated_on_devices]
       @remove_app_when_mdm_profile_is_removed = general[:remove_app_when_mdm_profile_is_removed]
       @prevent_backup_of_app_data = general[:prevent_backup_of_app_data]
       @keep_description_and_icon_up_to_date = general[:keep_description_and_icon_up_to_date]
@@ -232,6 +235,7 @@ module Jamf
     #
     def display_name=(new_val)
       return nil if new_val.to_s == @display_name
+
       @display_name = new_val.to_s
       @need_to_update = true
     end
@@ -274,6 +278,7 @@ module Jamf
     #
     def url=(new_val)
       return nil if new_val == @url
+
       @url = new_val
       @need_to_update = true
     end
@@ -288,6 +293,7 @@ module Jamf
     def make_available_after_install=(new_val)
       return nil if new_val == @make_available_after_install
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @make_available_after_install = new_val
       @need_to_update = true
     end
@@ -302,10 +308,25 @@ module Jamf
     def deploy_as_managed_app=(new_val)
       return nil if new_val == @deploy_as_managed_app
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @deploy_as_managed_app = new_val
       @need_to_update = true
     end
 
+    # Set whether or not this app should be auto-updated on devices
+    #
+    # @param new_val[Boolean] The new value
+    #
+    # @return [void]
+    #
+    def keep_app_updated_on_devices=(new_val)
+      return nil if new_val == @keep_app_updated_on_devices
+      raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
+      @keep_app_updated_on_devices = new_val
+      @need_to_update = true
+    end
+    alias auto_update= keep_app_updated_on_devices=
 
     # Set whether or not this app should be removed when
     # the device is unmanaged
@@ -317,6 +338,7 @@ module Jamf
     def remove_app_when_mdm_profile_is_removed=(new_val)
       return nil if new_val == @remove_app_when_mdm_profile_is_removed
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @remove_app_when_mdm_profile_is_removed = new_val
       @need_to_update = true
     end
@@ -330,11 +352,11 @@ module Jamf
     def prevent_backup_of_app_data=(new_val)
       return nil if new_val == @prevent_backup_of_app_data
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @prevent_backup_of_app_data = new_val
       @need_to_update = true
     end
 
-
     # Set whether or not the jss should update info about this app from the app store
     #
     # @param new_val[Boolean] The new value
@@ -344,6 +366,7 @@ module Jamf
     def keep_description_and_icon_up_to_date=(new_val)
       return nil if new_val == @keep_description_and_icon_up_to_date
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @keep_description_and_icon_up_to_date = new_val
       @need_to_update = true
     end
@@ -357,6 +380,7 @@ module Jamf
     def free=(new_val)
       return nil if new_val == @free
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @free = new_val
       @need_to_update = true
     end
@@ -371,6 +395,7 @@ module Jamf
     def take_over_management=(new_val)
       return nil if new_val == @take_over_management
       raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+
       @take_over_management = new_val
       @need_to_update = true
     end
@@ -432,6 +457,7 @@ module Jamf
     #
     def external_url=(new_val)
       return nil if new_val == @external_url
+
       @external_url = new_val
       @need_to_update = true
     end
@@ -445,11 +471,11 @@ module Jamf
     #
     def configuration_prefs=(new_val)
       return nil if new_val == @configuration_prefs
+
       @configuration_prefs = new_val
       @need_to_update = true
     end
 
-
     # Save the application to a file.
     #
     # @param path[Pathname, String] The path to which the file should be saved.
@@ -462,10 +488,12 @@ module Jamf
     #
     def save_ipa(path, overwrite = false)
       return nil unless @ipa[:data]
+
       path = Pathname.new path
-      path = path + @ipa[:name] if path.directory? && @ipa[:name]
+      path += @ipa[:name] if path.directory? && @ipa[:name]
 
       raise Jamf::AlreadyExistsError, "The file #{path} already exists" if path.exist? && !overwrite
+
       path.delete if path.exist?
       path.jss_save Base64.decode64(@ipa[:data])
     end
@@ -507,6 +535,7 @@ module Jamf
     #
     def refresh_ipa
       return nil unless @in_jss
+
       fresh_data = @cnx.c_get(@rest_rsrc)[self.class::RSRC_OBJECT_KEY]
       @ipa = fresh_data[:general][:ipa]
     end
@@ -523,6 +552,7 @@ module Jamf
       gen.add_element('deploy_as_managed_app').text = @deploy_as_managed_app
       gen.add_element('remove_app_when_mdm_profile_is_removed').text = @remove_app_when_mdm_profile_is_removed
       gen.add_element('prevent_backup_of_app_data').text = @prevent_backup_of_app_data
+      gen.add_element('keep_app_updated_on_devices').text = @keep_app_updated_on_devices
       gen.add_element('keep_description_and_icon_up_to_date').text = @keep_description_and_icon_up_to_date
       gen.add_element('free').text = @free
       gen.add_element('take_over_management').text = @take_over_management
@@ -540,7 +570,6 @@ module Jamf
       doc.to_s
     end
 
-
   end # class removable_macaddr
 
 end # module

data/lib/jamf/api/classic/api_objects/patch_title.rb

@@ -180,6 +180,7 @@ module Jamf
         info[:source_id] = info[:source_id].to_i
       end
       return data unless source_id
+
       data.select { |p| p[:source_id] == source_id }
     end
 
@@ -311,9 +312,11 @@ module Jamf
     # so all other lookup values have to be converted to ID before
     # the call to super
     #
-    def self.fetch(identifier = nil, **params)
-      # default api
-      api = params[:api] ? params[:api] : Jamf.cnx
+    def self.fetch(identifier = nil, **params)      
+      # default connection if unspecified
+      cnx = params.delete :cnx
+      cnx ||= params.delete :api # backward compatibility, deprecated
+      cnx ||= Jamf.cnx
 
       # source: and source_id: are considered the same, source_id: wins
       params[:source_id] ||= params[:source]
@@ -349,8 +352,8 @@ module Jamf
       cnx = api if api
 
       id = all_ids(refresh, cnx: cnx).include?(ident) ? ident : nil
-      id ||= map_all_ids_to(:source_name_id).invert[ident]
-      id ||= map_all_ids_to(:name).invert[ident]
+      id ||= map_all(:id, to: :source_name_id).invert[ident]
+      id ||= map_all(:id, to: :name).invert[ident]
       id
     end
 
@@ -376,7 +379,6 @@ module Jamf
     attr_reader :email_notification
     alias email_notification? email_notification
 
-    #
     def initialize(**args)
       super
 
@@ -421,11 +423,11 @@ module Jamf
     def versions
       return @versions unless in_jss
       return @versions unless @versions.empty?
+
       # if we are in jss, and versions is empty, re-fetch them
       @versions = self.class.fetch(id: id).versions
     end
 
-
     # @return [Hash] Subset of @versions, containing those which have packages
     #   assigned
     #
@@ -442,6 +444,7 @@ module Jamf
     def email_notification=(new_setting)
       return if email_notification == new_setting
       raise Jamf::InvalidDataError, 'New Setting must be boolean true or false' unless Jamf::TRUE_FALSE.include? @email_notification = new_setting
+
       @need_to_update = true
     end
 
@@ -454,6 +457,7 @@ module Jamf
     def web_notification=(new_setting)
       return if web_notification == new_setting
       raise Jamf::InvalidDataError, 'New Setting must be boolean true or false' unless Jamf::TRUE_FALSE.include? @web_notification = new_setting
+
       @need_to_update = true
     end
 
@@ -467,8 +471,8 @@ module Jamf
 
     # wrapper to fetch versions after creating
     def create
-      response = super
-      response
+      super
+      
     end
 
     # wrapper to clear @changed_pkgs after updating
@@ -535,6 +539,7 @@ module Jamf
         pkg = velem.add_element 'package'
         # leave am empty package element to remove the pkg assignement
         next if versions[vers].package_id == :none
+
         pkg.add_element('id').text = versions[vers].package_id.to_s
       end # do vers
     end

data/lib/jamf/api/classic/base_classes/api_object.rb

@@ -295,7 +295,7 @@ module Jamf
     # This is called automatically when subclasses are loaded by zeitwerk
     #
     def self.define_identifier_list_methods
-      Jamf.load_msg "defining list-methods for APIObject subclass #{self}"
+      Jamf.load_msg "Defining list-methods for APIObject subclass #{self}"
 
       lookup_keys.each do |als, key|
         meth_name = key.to_s.end_with?('s') ? "all_#{key}es" : "all_#{key}s"
@@ -557,8 +557,9 @@ module Jamf
     #
     ######################################
     def self.map_all(ident, to:, cnx: Jamf.cnx, refresh: false, cached_list: nil)
+      orig_ident = ident
       ident = lookup_keys[ident]
-      raise Jamf::InvalidDataError, "No identifier :#{ident} for class #{self}" unless ident
+      raise Jamf::InvalidDataError, "No identifier :#{orig_ident} for class #{self}" unless ident
 
       list = cached_list || all(refresh, cnx: cnx)
       mapped = list.map do |i|
@@ -673,28 +674,85 @@ module Jamf
     # is undefined. In short - dont' use names here unless you know they are
     # unique.
     #
+    # NOTE: Integers passed in as strings, e.g. '12345' will be converted to 
+    # integers and return the matching integer id if it exists.
+    #
+    # This means that if you have names that might match '12345' and you use
+    #    valid_id '12345' 
+    # you will get back the id 12345, if such an id exists, even if it is not
+    # the object with the name '12345'
+    #
+    # To explicitly look for '12345' as a name, use:
+    #      valid_id name: '12345' 
+    #   See the ident_and_val param below.
+    #
     # @param identfier [String,Integer] An identifier for an object, a value for
-    # one of the available lookup_keys
+    #   one of the available lookup_keys. Omit this and use 'identifier: value'
+    #   if you want to limit the search to a specific indentifier key, e.g.
+    #      name: 'somename'
+    #   or
+    #      id: 76538
     #
     # @param refresh [Boolean] Should the data be re-read from the server
     #
+    # @param ident_and_val [Hash] Do not pass in Hash.
+    #   This Hash internally holds the arbitrary identifier key
+    #   and desired value when you call ".valid_id ident: 'value'", e.g. 
+    #   ".valid_id name: 'somename'" or ".valid_id udid: some_udid"
+    #   Using explicit identifier keys like this will speed things up, since
+    #   the method doesn't have to search through all available identifiers
+    #   for the desired value.
+    #
     # @param cnx [Jamf::Connection] an API connection to use for the query.
     #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
     #
-    def self.valid_id(identifier, refresh = false, api: nil, cnx: Jamf.cnx)
+    def self.valid_id(identifier = nil, refresh = false, api: nil, cnx: Jamf.cnx, **ident_and_val)
       cnx = api if api
 
-      # refresh if needed
+      # refresh the cache if needed
       all(refresh, cnx: cnx) if refresh
 
-      # it its a valid id, return it
+      # Were we given an explict identifier key, like name: or id:?
+      # If so, just look for that.
+      unless ident_and_val.empty?
+        # only the first k/v pair of the ident_and_val hash is used
+        key = ident_and_val.keys.first
+        val = ident_and_val[key]
+
+        # if we are explicitly looking for an id, ensure we use an integer
+        # even if we were given an integer in a string.
+        if key == :id
+          val = val.to_i if val.is_a?(String) && val.j_integer?
+          return all_ids(cnx: cnx).include?(val) ? val : nil
+        end
+
+        # map the identifiers to ids, and return the id if there's
+        # a case-insensitive matching identifire
+        map_all(key, to: :id).each do |ident_val, id|
+          return id if ident_val.to_s.casecmp? val.to_s
+        end
+        nil
+      end
+
+      # If we are here, we need to seach all available identifier keys
+      # Start by looking for it as an id.
+
+      # it its a valid integer id, return it
       return identifier if all_ids(cnx: cnx).include? identifier
 
+      # if its a valid integer-in-a-string id, return it
+      if identifier.is_a?(String) && identifier.j_integer?
+        int_id = identifier.to_i
+        return int_id if all_ids(cnx: cnx).include? int_id
+      end 
+
+      # Now go through all the other identifier keys
       keys_to_check = lookup_keys(no_aliases: true)
       keys_to_check.delete :id # we've already checked :id
 
+      # loop thru looking for a match
       keys_to_check.each do |key|
         mapped_ids = map_all_ids_to key, cnx: cnx
         matches = mapped_ids.select { |_id, ident| ident.casecmp? identifier }
@@ -905,7 +963,7 @@ module Jamf
 
       # which connection?
       cnx = args.delete :cnx
-      cnx ||= args.delete :api
+      cnx ||= args.delete :api # backward compatibility, deprecated
       cnx ||= Jamf.cnx
 
       # refresh the .all list if needed
@@ -1073,7 +1131,7 @@ module Jamf
     # @param cnx [Jamf::Connection] the connection thru which to make this
     #   object. Defaults to the deault API connection in Jamf.cnx
     #
-    # @param args[Hash] The data for creating an object, such as name:
+    # @param args [Hash] The data for creating an object, such as name:
     #  See {APIObject#initialize}
     #
     # @return [APIObject] The un-created ruby-instance of a JSS object
@@ -1084,8 +1142,9 @@ module Jamf
         raise Jamf::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows."
       end
       raise ArgumentError, "Use '#{self.class}.fetch id: xx' to retrieve existing JSS objects" if args[:id]
-
-      args[:api] ||= Jamf.cnx
+      
+      args[:cnx] ||= args[:api] # deprecated
+      args[:cnx] ||= Jamf.cnx
       args[:id] = :new
       new(**args)
     end

data/lib/jamf/api/classic/base_classes/patch_source.rb

@@ -128,8 +128,9 @@ module Jamf
 
     # Fetch either an internal or external patch source
     #
-    # BUG: there's an API bug: fetching a non-existent
-    # which is why we rescue internal server errors.
+    # BUG: there's an API bug when fetching a non-existent patch source
+    # which is why we rescue 500 internal server errors and report them
+    # as 'no matching patch source'
     #
     # @see APIObject.fetch
     #
@@ -162,7 +163,7 @@ module Jamf
     # @see APIObject.make
     #
     def self.create(**args)
-      case self.name
+      case name
       when 'Jamf::PatchSource'
         Jamf::PatchExternalSource.make args
       when 'Jamf::PatchExternalSource'
@@ -184,7 +185,7 @@ module Jamf
     def self.delete(victims, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      case self.name
+      case name
       when 'Jamf::PatchSource'
         Jamf::PatchExternalSource victims, cnx: cnx
       when 'Jamf::PatchExternalSource'
@@ -292,6 +293,7 @@ module Jamf
 
       return :internel if Jamf::PatchInternalSource.valid_id ident, refresh, cnx: cnx
       return :external if Jamf::PatchExternalSource.valid_id ident, refresh, cnx: cnx
+
       nil
     end
 
@@ -324,7 +326,10 @@ module Jamf
 
     # Init
     def initialize(**args)
-      raise Jamf::UnsupportedError, 'PatchSource is an abstract metaclass. Please use PatchInternalSource or PatchExternalSource' if self.class == Jamf::PatchSource
+      if instance_of?(Jamf::PatchSource)
+        raise Jamf::UnsupportedError, 
+              'PatchSource is an abstract metaclass. Please use PatchInternalSource or PatchExternalSource'
+      end
 
       super
 

data/lib/jamf/api/connection/token.rb

@@ -87,6 +87,7 @@ module Jamf
       # @return [String] The token data
       attr_reader :token
       alias token_string token
+      alias auth_token token
 
       # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/
       attr_reader :base_url

data/lib/jamf/api/connection.rb

@@ -106,7 +106,7 @@ module Jamf
   # If you provide connection details when calling 'new', they will be passed
   # to the {#connect} method immediately. Otherwise you can call {#connect} later.
   #
-  #   production_api = Jamf::Connection.new(
+  #   production_server = Jamf::Connection.new(
   #     'https://produser@prodserver.address.org:8443/'
   #     name: 'prod',
   #     pw: :prompt
@@ -231,8 +231,4 @@ module Jamf
 
   end # class Connection
 
-  # Some backward compatibility
-  # @deprecated
-  APIConnection = Connection
-
 end # module

data/lib/jamf/api/jamf_pro/api_objects/inventory_preload_record.rb

@@ -110,7 +110,6 @@ module Jamf
     # Must define this when extending Filterable
     FILTER_KEYS = OAPI_PROPERTIES.keys - [:extensionAttributes]
 
-
     DEVICE_TYPE_COMPUTER = 'Computer'.freeze
 
     DEVICE_TYPE_MOBILE_DEV = 'Mobile Device'.freeze