ruby-jss 4.1.1 → 4.2.0b2

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -26,175 +26,175 @@
 ###
 module Jamf
 
-    # An Icon in the JSS, used in Self Service.
-    #
-    # At the moment, icons are not API objects, they are collections of data
-    # stored in the JSS that might be included in some API object's
-    # Self Service data.
-    #
-    # The data available for an icon are:
-    #
-    # - id: the icon's id in the JSS
-    # - name: the icon's non-unique name in the JSS
-    # - uri: the uri to download or preview the icon
-    # - data: the icon file itself, base-64 encoded.
-    #
-    # Icon instances are read-only. To change the icon for a self-servable object,
-    # see {SelfServable#icon=}.
-    #
-    # NOTE: Since icons are not APIObjects, there's no way to see a list of them
-    # via the API. The Jamf::Icon class methods .all, .all_ids, and .all_names
-    # require MySQL database access. See {Jamf::DBConnection}.
-    #
-    # This also means, if you use multiple API connections, you'll have to
-    # make sure to connect to the correct MySQL server for the
-    # APIConnection you care about.
-    #
-    class Icon
-
-      #  Class Methods
-      #####################################
-
-      # Return an Array of { id:, name: } Hashes for all icons known to the JSS
-      # Since Icon lists aren't accessible via the API, this method must
-      # query the SQL database directly, and will raise an exception if you
-      # aren't connected to the database.
-      #
-      # @param refresh[Boolean] re-read the data from the server?
-      #
-      # @return [Array<Hash>] The names and ids of all icons known to the JSS
-      #
-      def self.all(refresh = false)
-        @all_icons = nil if refresh
-        return @all_icons if @all_icons
-        @all_icons = []
-        qry = 'SELECT icon_id, filename FROM icons'
-        res = Jamf::DB_CNX.db.query qry
-        res.each_hash { |icon| @all_icons << { id: icon['icon_id'].to_i, name: icon['filename'] } }
-        @all_icons
-      end
+  # An Icon in the JSS, used in Self Service.
+  #
+  # At the moment, icons are not API objects, they are collections of data
+  # stored in the JSS that might be included in some API object's
+  # Self Service data.
+  #
+  # The data available for an icon are:
+  #
+  # - id: the icon's id in the JSS
+  # - name: the icon's non-unique name in the JSS
+  # - uri: the uri to download or preview the icon
+  # - data: the icon file itself, base-64 encoded.
+  #
+  # Icon instances are read-only. To change the icon for a self-servable object,
+  # see {SelfServable#icon=}.
+  #
+  # NOTE: Since icons are not APIObjects, there's no way to see a list of them
+  # via the API. The Jamf::Icon class methods .all, .all_ids, and .all_names
+  # require MySQL database access. See {Jamf::DBConnection}.
+  #
+  # This also means, if you use multiple API connections, you'll have to
+  # make sure to connect to the correct MySQL server for the
+  # APIConnection you care about.
+  #
+  class Icon
+
+    #  Class Methods
+    #####################################
+
+    # Return an Array of { id:, name: } Hashes for all icons known to the JSS
+    # Since Icon lists aren't accessible via the API, this method must
+    # query the SQL database directly, and will raise an exception if you
+    # aren't connected to the database.
+    #
+    # @param refresh[Boolean] re-read the data from the server?
+    #
+    # @return [Array<Hash>] The names and ids of all icons known to the JSS
+    #
+    def self.all(refresh = false)
+      @all_icons = nil if refresh
+      return @all_icons if @all_icons
+
+      @all_icons = []
+      qry = 'SELECT icon_id, filename FROM icons'
+      res = Jamf::DB_CNX.db.query qry
+      res.each_hash { |icon| @all_icons << { id: icon['icon_id'].to_i, name: icon['filename'] } }
+      @all_icons
+    end
+
+    # An Array of all icon ids known to the JSS.
+    # See {Icon.all}.
+    #
+    # @param refresh[Boolean] re-read the data from the server?
+    #
+    # @return [Array<Integer>] The ids of all icons known to the JSS
+    #
+    def self.all_ids(refresh = false)
+      all(refresh).map { |i| i[:id] }
+    end
 
-      # An Array of all icon ids known to the JSS.
-      # See {Icon.all}.
-      #
-      # @param refresh[Boolean] re-read the data from the server?
-      #
-      # @return [Array<Integer>] The ids of all icons known to the JSS
-      #
-      def self.all_ids(refresh = false)
-        all(refresh).map { |i| i[:id] }
-      end
+    # An Array of all icon names known to the JSS.
+    # See {Icon.all}.
+    # NOTE: Icon names are not unique
+    #
+    # @param refresh[Boolean] re-read the data from the server?
+    #
+    # @return [Array<Integer>] The names of all icons known to the JSS
+    #
+    def self.all_names(refresh = false)
+      all(refresh).map { |i| i[:name] }
+    end
 
-      # An Array of all icon names known to the JSS.
-      # See {Icon.all}.
-      # NOTE: Icon names are not unique
-      #
-      # @param refresh[Boolean] re-read the data from the server?
-      #
-      # @return [Array<Integer>] The names of all icons known to the JSS
-      #
-      def self.all_names(refresh = false)
-        all(refresh).map { |i| i[:name] }
-      end
+    #  Attributes
+    #####################################
 
-      #  Attributes
-      #####################################
-
-      # @return [Integer] the icon's id in the JSS
-      attr_reader :id
-
-      # @return [String] the icon's name in the JSS
-      #   NOTE: these are not unique
-      attr_reader :name
-      alias filename name
-
-      # @return [String] The URI for downloading or previewing the icon from the JSS
-      attr_reader :uri
-
-      # @return [String] The raw icon file.
-      attr_reader :data
-
-
-      #  Constructor
-      #####################################
-
-      # Set up a new Jamf::Icon instance
-      #
-      # @param icon_data[Hash] The :self_service_icon Hash from the :self_service
-      #   Hash of an object's API @init_data
-      #
-      # @return [Jamf::Icon] The new object
-      #
-      def initialize(icon_data)
-        return unless icon_data.is_a? Hash
-        @id = icon_data[:id]
-        @name = icon_data[:filename]
-        @uri = icon_data[:uri]
-        @data = icon_data[:data]
-
-        # if no :filename, its called :name
-        @name ||= icon_data[:name]
-
-        # if there's no id, as with MobileDeviceConfigurationProfile
-        # get it from the end of the uri if possible
-        if @uri && !@id
-          @id = Regexp.last_match(1).to_i if @uri =~ /(\d+)$/
-        end
-
-        # decode the icon data, or grab from
-        # the URI if needed
-        @data = Base64.decode64(@data) if @data
-        begin
-          @data ||= URI.parse(@uri).read if @uri
-        rescue
-          @data = nil
-        end
+    # @return [Integer] the icon's id in the JSS
+    attr_reader :id
 
-      end
+    # @return [String] the icon's name in the JSS
+    #   NOTE: these are not unique
+    attr_reader :name
+    alias filename name
 
-      # Instance Methods
-      #####################################
+    # @return [String] The URI for downloading or previewing the icon from the JSS
+    attr_reader :uri
 
-      # Open the icon's URL in the current user's browser
-      #
-      # @return [void]
-      #
-      def show_in_browser
-        return nil unless @uri
-        system "/usr/bin/open '#{@uri}'"
-      end
+    # @return [String] The raw icon file.
+    attr_reader :data
 
-      # Save the icon to a file.
-      #
-      # @param path[Pathname, String] The path to which the file should be saved.
-      # If the path given is an existing directory, the icon's current filename will
-      # be used, if known.
-      #
-      # @param overwrite[Boolean] Overwrite the file if it exists? Defaults to false
-      #
-      # @return [void]
-      #
-      def save(path, overwrite = false)
-        path = Pathname.new path
-        path = path + @name if path.directory? && @name
-
-        raise Jamf::AlreadyExistsError, "The file #{path} already exists" if path.exist? unless overwrite
-        path.delete if path.exist?
-        path.jss_save @data
-      end
+    #  Constructor
+    #####################################
 
-      # Remove the data  object from
-      # the instance_variables used to create
-      # pretty-print (pp) output.
-      #
-      # @return [Array] the desired instance_variables
-      #
-      def pretty_print_instance_variables
-        vars = instance_variables.sort
-        vars.delete :@data
-        vars
+    # Set up a new Jamf::Icon instance
+    #
+    # @param icon_data[Hash] The :self_service_icon Hash from the :self_service
+    #   Hash of an object's API @init_data
+    #
+    # @return [Jamf::Icon] The new object
+    #
+    def initialize(icon_data)
+      return unless icon_data.is_a? Hash
+
+      @id = icon_data[:id]
+      @name = icon_data[:filename]
+      @uri = icon_data[:uri]
+      @data = icon_data[:data]
+
+      # if no :filename, its called :name
+      @name ||= icon_data[:name]
+
+      # if there's no id, as with MobileDeviceConfigurationProfile
+      # get it from the end of the uri if possible
+      @id = Regexp.last_match(1).to_i if @uri && !@id && @uri =~ (/(\d+)$/)
+
+      # decode the icon data, or grab from
+      # the URI if needed
+      @data = Base64.decode64(@data) if @data
+      begin
+        @data ||= URI.parse(@uri).read if @uri
+      rescue
+        @data = nil
       end
+    end
+
+    # Instance Methods
+    #####################################
+
+    # Open the icon's URL in the current user's browser
+    #
+    # @return [void]
+    #
+    def show_in_browser
+      return nil unless @uri
+
+      system "/usr/bin/open '#{@uri}'"
+    end
+
+    # Save the icon to a file.
+    #
+    # @param path[Pathname, String] The path to which the file should be saved.
+    # If the path given is an existing directory, the icon's current filename will
+    # be used, if known.
+    #
+    # @param overwrite[Boolean] Overwrite the file if it exists? Defaults to false
+    #
+    # @return [void]
+    #
+    def save(path, overwrite = false)
+      path = Pathname.new path
+      path += @name if path.directory? && @name
+
+      raise Jamf::AlreadyExistsError, "The file #{path} already exists" if !overwrite && path.exist?
+
+      path.delete if path.exist?
+      path.jss_save @data
+    end
+
+    # Remove the data  object from
+    # the instance_variables used to create
+    # pretty-print (pp) output.
+    #
+    # @return [Array] the desired instance_variables
+    #
+    def pretty_print_instance_variables
+      vars = instance_variables.sort
+      vars.delete :@data
+      vars
+    end
 
-    end # class icon
+  end # class icon
 
 end # module

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

@@ -1,4 +1,4 @@
-# Copyright 2023 Pixar
+# Copyright 2025 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -158,7 +158,7 @@ module Jamf
 
       new_val = new_val.to_s.strip
       unless new_val.empty? or Jamf::Building.all_names(cnx: @cnx).include? new_val
-        raise Jamf::NoSuchItemError, 
+        raise Jamf::NoSuchItemError,
               "No building named #{new_val} exists in the JSS"
       end
 
@@ -172,7 +172,7 @@ module Jamf
 
       new_val = new_val.to_s.strip
       unless new_val.empty? or Jamf::Department.all_names(cnx: @cnx).include? new_val
-        raise Jamf::NoSuchItemError, 
+        raise Jamf::NoSuchItemError,
               "No department named #{new_val} exists in the JSS"
       end
 

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -146,7 +146,6 @@ module Jamf
       add_vpp_xml doc
 
       doc.to_s
-
     end
 
   end # class MacApplication

data/lib/jamf/api/classic/api_objects/management_history/audit_event.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/casper_imaging_log.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/casper_remote_log.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/computer_usage_log.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/ebook.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/hash_like.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -22,10 +22,8 @@
 ###    language governing permissions and limitations under the Apache License.
 ###
 
-#
 module Jamf
 
-  #
   module ManagementHistory
 
     # This is mixed in to the history event classes to

data/lib/jamf/api/classic/api_objects/management_history/mac_app_store_app.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/mdm_command.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/mobile_device_app.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/policy_log.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/screen_sharing_log.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/management_history/user_location_change.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -204,6 +204,7 @@ module Jamf
 
         if subset
           raise "Subset must be one of :#{@hist_subsets.join ', :'}" unless @hist_subsets.include? subset
+
           subset_rsrc = @hist_rsrc + "/id/#{id}/subset/#{subset}"
           cnx.c_get(subset_rsrc)[@hist_key][subset]
         else
@@ -263,6 +264,7 @@ module Jamf
         hist = management_history(ident, subset, cnx: cnx)
         if status
           raise Jamf::InvalidDataError, 'status must be one of :completed, :pending, or :failed' unless HIST_MDM_STATUSES.include? status
+
           statuses_to_do = [status]
         else
           statuses_to_do = HIST_MDM_STATUSES
@@ -279,7 +281,7 @@ module Jamf
             # but we always set the :status
             cmd[:status] = a_status
 
-            Jamf::ManagementHistory::MdmCommand.new cmd
+            Jamf::ManagementHistory::MdmCommand.new(**cmd)
           end # map do |cmd|
         end # statuses_to_do.each do |a_status|
         result
@@ -358,7 +360,6 @@ module Jamf
         epoch ? JSS.epoch_to_time(epoch) : nil
       end
 
-
       # The history of app store apps  for a computer
       #
       # @param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@@ -378,6 +379,7 @@ module Jamf
         hist = management_history(ident, :mac_app_store_applications, cnx: cnx)
         if status
           raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
+
           statuses_to_do = [status]
         else
           statuses_to_do = HIST_APP_STATUSES
@@ -415,6 +417,7 @@ module Jamf
         hist = management_history(ident, :applications, cnx: cnx)
         if status
           raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
+
           statuses_to_do = [status]
         else
           statuses_to_do = HIST_APP_STATUSES
@@ -480,7 +483,7 @@ module Jamf
       #
       # @see #app_store_app_history
       #
-      def installed_app_store_apps(ident,api: nil, cnx: Jamf.cnx)
+      def installed_app_store_apps(ident, api: nil, cnx: Jamf.cnx)
         cnx = api if api
 
         app_store_app_history(ident, :installed, cnx: cnx)
@@ -522,6 +525,7 @@ module Jamf
         cnx = api if api
 
         raise Jamf::UnsupportedError, 'Only computers have casper imaging logs' unless self == Jamf::Computer
+
         hist = management_history(ident, :casper_imaging_logs, cnx: cnx)
         hist.map! { |evt| Jamf::ManagementHistory::CasperImagingLog.new evt }
       end
@@ -539,6 +543,7 @@ module Jamf
         cnx = api if api
 
         raise Jamf::UnsupportedError, 'Only computers have casper remote logs' unless self == Jamf::Computer
+
         hist = management_history(ident, :casper_remote_logs, cnx: cnx)
         hist.map! { |evt| Jamf::ManagementHistory::CasperRemoteLog.new evt }
       end
@@ -556,6 +561,7 @@ module Jamf
         cnx = api if api
 
         raise Jamf::UnsupportedError, 'Only computers have usage logs' unless self == Jamf::Computer
+
         hist = management_history(ident, :computer_usage_logs, cnx: cnx)
         hist.map! { |evt| Jamf::ManagementHistory::ComputerUsageLog.new evt }
       end
@@ -574,6 +580,7 @@ module Jamf
         cnx = api if api
 
         raise Jamf::UnsupportedError, 'Only computers have screen sharing logs' unless self == Jamf::Computer
+
         hist = management_history(ident, :screen_sharing_logs, cnx: cnx)
         hist.map! { |evt| Jamf::ManagementHistory::ScreenSharingLog.new evt }
       end
@@ -591,8 +598,9 @@ module Jamf
         cnx = api if api
 
         raise Jamf::UnsupportedError, 'Only computers have policy logs' unless self == Jamf::Computer
+
         hist = management_history(ident, :policy_logs, cnx: cnx)
-        hist.map! { |evt| Jamf::ManagementHistory::PolicyLog.new evt }
+        hist.map! { |evt| Jamf::ManagementHistory::PolicyLog.new(**evt) }
       end
 
       # The array from .policy_logs, limited to status = :completed
@@ -632,6 +640,7 @@ module Jamf
         hist = management_history(ident, :ebooks, cnx: cnx)
         if status
           raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
+
           statuses_to_do = [status]
         else
           statuses_to_do = HIST_APP_STATUSES

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -26,10 +26,9 @@
 ###
 module Jamf
 
-### A mix-in module providing access to the "match" resources for some
-### JSS API objects, like computers and mobile devices.
-###
-
+  ### A mix-in module providing access to the "match" resources for some
+  ### JSS API objects, like computers and mobile devices.
+  ###
 
   #####################################
   ### Module Variables
@@ -63,7 +62,7 @@ module Jamf
 
     MATCHABLE = true
 
-    MATCH_RSRC = "match"
+    MATCH_RSRC = 'match'
 
     #####################################
     ###  Variables
@@ -89,7 +88,7 @@ module Jamf
     def match(term, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      raise Jamf::InvalidDataError, "Match term may not be empty" if term.to_s.empty?
+      raise Jamf::InvalidDataError, 'Match term may not be empty' if term.to_s.empty?
 
       rsrc = "#{self::RSRC_BASE}/#{Jamf::Matchable::MATCH_RSRC}/#{CGI.escape term.to_s}"
       cnx.c_get(rsrc)[self::RSRC_LIST_KEY]

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")