ruby-jss 1.4.1 → 1.6.0

data/lib/jss/api_object/patch_source.rb

@@ -120,30 +120,31 @@ module JSS
 
     # Fetch either an internal or external patch source
     #
-    # BUG: there's an API bug: fetching a non-existent ids
+    # BUG: there's an API bug: fetching a non-existent
     # which is why we rescue internal server errors.
     #
     # @see APIObject.fetch
     #
-    def self.fetch(arg, api: JSS.api)
+    def self.fetch(searchterm = nil, **args)
       if self == JSS::PatchSource
         begin
-          fetched = JSS::PatchInternalSource.fetch arg, api: api
-        rescue RestClient::ResourceNotFound, RestClient::InternalServerError, JSS::NoSuchItemError
+          fetched = JSS::PatchInternalSource.fetch searchterm, **args
+        rescue
           fetched = nil
         end
         unless fetched
           begin
-            fetched = JSS::PatchExternalSource.fetch arg, api: api
-          rescue RestClient::ResourceNotFound, RestClient::InternalServerError, JSS::NoSuchItemError
+            fetched = JSS::PatchExternalSource.fetch searchterm, **args
+          rescue
             raise JSS::NoSuchItemError, 'No matching PatchSource found'
           end
         end
         return fetched
       end # if self == JSS::PatchSource
+
       begin
-        super
-      rescue RestClient::ResourceNotFound, RestClient::InternalServerError, JSS::NoSuchItemError
+        super searchterm, **args
+      rescue JSS::NoSuchItemError
         raise JSS::NoSuchItemError, "No matching #{self::RSRC_OBJECT_KEY} found"
       end
     end
@@ -211,7 +212,7 @@ module JSS
       begin
         # TODO: remove this and adjust parsing when jamf fixes the JSON
         raw = JSS::XMLWorkaround.data_via_xml(rsrc, AVAILABLE_TITLES_DATA_MAP, api)
-      rescue RestClient::ResourceNotFound
+      rescue JSS::NoSuchItemError
         return []
       end
 

data/lib/jss/api_object/policy.rb

@@ -263,14 +263,14 @@ module JSS
     }.freeze
 
     LOG_FLUSH_INTERVAL_PERIODS = {
-      day: 'Day',
-      days: 'Day',
-      week: 'Week',
-      weeks: 'Week',
-      month: 'Month',
-      months: 'Month',
-      year: 'Year',
-      years: 'Year'
+      day: 'Days',
+      days: 'Days',
+      week: 'Weeks',
+      weeks: 'Weeks',
+      month: 'Months',
+      months: 'Months',
+      year: 'Years',
+      years: 'Years'
     }.freeze
 
     # the object type for this object in
@@ -287,6 +287,86 @@ module JSS
     # How is the category stored in the API data?
     CATEGORY_DATA_TYPE = Hash
 
+    # All valid script parameters
+    SCRIPT_PARAMETERS_AVAILABLE = %i[parameter4 parameter5 parameter6 parameter7 parameter8 parameter9 parameter10 parameter11].freeze
+
+    # Class Methods
+    ######################
+
+    # Flush logs for a given policy older than some number of days, weeks,
+    # months or years, possibly limited to one or more computers.
+    #
+    # With no parameters, flushes all logs for the policy for all computers.
+    #
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
+    #
+    # WARNING: Log flushing can take a long time, and the API call doesnt return
+    # until its finished. The connection timeout will be temporarily raised to
+    # 30 minutes, unless it's already higher.
+    #
+    # @param policy[Integer,String] The id or name of the policy to flush
+    #
+    # @param older_than[Integer] 0, 1, 2, 3, or 6
+    #
+    # @param period[Symbol] :days, :weeks, :months, or :years
+    #
+    # @param computers[Array<Integer,String>] Identifiers of the target computers
+    #   either ids, names, SNs, macaddrs, or UDIDs. If omitted, flushes logs for
+    #   all computers
+    #
+    # @param api [JSS::APIConnection] the API  connection to use.
+    #
+    # @return [void]
+    #
+    def self.flush_logs(policy, older_than: 0, period: :days, computers: [], api: JSS.api)
+      orig_timeout = api.cnx.options.timeout
+      pol_id = valid_id policy
+      raise JSS::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id
+
+      older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
+      raise JSS::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
+
+      period = LOG_FLUSH_INTERVAL_PERIODS[period]
+      raise JSS::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
+
+      computers = [computers] unless computers.is_a? Array
+
+      # log flushes can be really slow
+      api.timeout = 1800 unless orig_timeout && orig_timeout > 1800
+
+      return api.delete_rsrc "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}" if computers.empty?
+
+      flush_logs_for_specific_computers pol_id, older_than, period, computers, api
+    ensure
+      api.timeout = orig_timeout
+    end
+
+    # use an XML body in a DELETE request to flush logs for
+    # a list of computers - used by the flush_logs class method
+    def self.flush_logs_for_specific_computers(pol_id, older_than, period, computers, api)
+      # build the xml body for a DELETE request
+      xml_doc = REXML::Document.new JSS::APIConnection::XML_HEADER
+      lf = xml_doc.add_element 'logflush'
+      lf.add_element('log').text = 'policy'
+      lf.add_element('log_id').text = pol_id.to_s
+      lf.add_element('interval').text = "#{older_than} #{period}"
+      comps_elem = lf.add_element 'computers'
+      computers.each do |c|
+        id = JSS::Computer.valid_id c
+        next unless id
+
+        ce = comps_elem.add_element 'computer'
+        ce.add_element('id').text = id.to_s
+      end
+
+      # Do a DELETE request with a body.
+      api.cnx.delete(LOG_FLUSH_RSRC) do |req|
+        req.headers[JSS::APIConnection::HTTP_CONTENT_TYPE_HEADER] = JSS::APIConnection::MIME_XML
+        req.body = xml_doc.to_s
+      end
+    end
+    private_class_method :flush_logs_for_specific_computers
+
     # Attributes
     ######################
 
@@ -1408,6 +1488,53 @@ module JSS
       removed
     end
 
+    # Set a script parameter
+    #
+    # @param identifier [Integer,String] identifier the id or name of a script in this policy
+    #
+    # @param opts [Hash] opts the options to alter for this script
+    #
+    # @option [String] parameter4: the value of the 4th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter5: the value of the 5th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter6: the value of the 6th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter7: the value of the 7th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter8: the value of the 8th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter9: the value of the 9th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter10: the value of the 10th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @option [String] parameter11: the value of the 11th parameter passed to the script. this
+    #   overrides the same parameter in the script object itself.
+    #
+    # @return [Array] the scripts array
+    #
+    def set_script_parameters(identifier, **opts)
+      id = JSS::Script.valid_id identifier, api: @api
+      raise JSS::NoSuchItemError, "No script matches '#{identifier}'" unless id
+
+      script_data = @scripts.select { |s| s[:id] == id }[0]
+      raise JSS::InvalidDataError, "Script #{id} is not configured. Use add_script method." unless script_data
+
+      opts.each do |parameter, value|
+        script_data[parameter] = value if SCRIPT_PARAMETERS_AVAILABLE.include? parameter
+      end
+
+      @need_to_update = true
+      @scripts
+    end # end set_script_parameter
+
     ###### Directory Bindings
 
     # @return [Array] the id's of the directory_bindings handled by the policy
@@ -1715,34 +1842,37 @@ module JSS
     end
     alias execute run
 
-    # Flush all policy logs for this policy older than
-    # some number of days, weeks, months or years.
+    # Flush logs for this policy older than
+    # some number of days, weeks, months or years, possibly limited to
+    # one or more computers
+    #
+    # With no parameters, flushes all logs for all computers
     #
-    # With no parameters, flushes all logs
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
     #
-    # NOTE: Currently the API doesn't have a way to
-    # flush only failed policies.
+    # WARNING: Log flushing can take a long time, and the API call doesnt return
+    # until its finished. The connection timeout will be temporarily raised to
+    # 30 minutes, unless it's already higher.
     #
     # @param older_than[Integer] 0, 1, 2, 3, or 6
     #
     # @param period[Symbol] :days, :weeks, :months, or :years
     #
+    # @param computers[Array<Integer,String>] Identifiers of the target computers
+    #   either ids, names, SNs, macaddrs, or UDIDs
+    #
     # @return [void]
     #
-    def flush_logs(older_than: 0, period: :days)
+    def flush_logs(older_than: 0, period: :days, computers: [])
       raise JSS::NoSuchItemError, "Policy doesn't exist in the JSS. Use #create first." unless @in_jss
 
-      unless LOG_FLUSH_INTERVAL_INTEGERS.key?(older_than)
-        raise JSS::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}"
-      end
-
-      unless LOG_FLUSH_INTERVAL_PERIODS.key?(period)
-        raise JSS::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}"
-      end
-
-      interval = "#{LOG_FLUSH_INTERVAL_INTEGERS[older_than]}+#{LOG_FLUSH_INTERVAL_PERIODS[period]}"
-
-      @api.delete_rsrc "#{LOG_FLUSH_RSRC}/policy/id/#{@id}/interval/#{interval}"
+      JSS::Policy.flush_logs(
+        @id,
+        older_than: older_than,
+        period: period,
+        computers: computers,
+        api: @api
+      )
     end
 
     # Private Instance Methods

data/lib/jss/api_object/printer.rb

@@ -376,9 +376,9 @@ module JSS
         #
         # @author Tyler Morgan
         #
-        # @param newvalue [String]
+        # @param newvalue [String, Float, Array[String], Array[Float]]
         #
-        # @raise [JSS::InvalidDataError] If newvalue is not a String
+        # @raise [JSS::InvalidDataError] If newvalue is not a String, Float, Array containing Strings, or Array containing Floats.
         #
         # @example Limit Printer object to only High Sierra devices and Mojave 10.14.5 OS versions
         #   printer.os_requirements = "10.13.x, 10.14.5"
@@ -386,8 +386,14 @@ module JSS
         # @return [void]
         def os_requirements=(newvalue)
 
-            raise JSS::InvalidDataError, "os_requirements must be a string." unless newvalue.is_a? String
-
+            if newvalue.is_a? Array
+                # Parse Array
+                raise JSS::InvalidDataError, "If setting os_requirements with an array, it must contain strings or floats." unless newvalue[0].is_a?(String) || newvalue[0].is_a?(Float)
+                newvalue = newvalue.map { |x| x.to_s }.join(',')
+            else
+                raise JSS::InvalidDataError, "os_requirements must either be a string, float, or an array containing strings or floats." unless (newvalue.is_a?(String) || newvalue.is_a?(Float)) && !newvalue.nil?
+            end
+                
             @os_requirements = newvalue
 
             @need_to_update = true

data/lib/jss/api_object/scopable.rb

@@ -100,22 +100,17 @@ module JSS
       @need_to_update = true if @in_jss
     end
 
-
-    ### A wrapper around the update method, to try catching RestClient::Conflict
-    ### 409 errors when we couldn't verify all ldap users/groups due to lack of ldap connections
-    ###
+    # A wrapper around the update method, to try catching 409 conflict errors
+    # when we couldn't verify all ldap users/groups due to lack of ldap connections
+    #
     def update
-      begin
-        super
-
-      rescue RestClient::Conflict => conflict
-        if  self.scope.unable_to_verify_ldap_entries == true
-          raise JSS::InvalidDataError, "Potentially non-existant LDAP user or group in new scope values."
-        else
-          raise conflict
-        end
-
-      end # begin
+      super
+    rescue JSS::ConflictError => conflict
+      if scope.unable_to_verify_ldap_entries == true
+        raise JSS::InvalidDataError, "Potentially non-existant LDAP user or group in new scope values."
+      else
+        raise conflict
+      end
     end # update
 
   end # module Scopable

data/lib/jss/api_object/scopable/scope.rb

@@ -224,6 +224,7 @@ module JSS
       # A reference to the object that contains this Scope
       #
       # For telling it when a change is made and an update needed
+      # and for accessing its api connection
       attr_accessor :container
 
       # @return [Boolean] should we expect a potential 409 Conflict
@@ -246,7 +247,6 @@ module JSS
       attr_reader :all_targets
       alias all_targets? all_targets
 
-
       # The items which form the base scope of included targets
       #
       # This is the group of targets to which the limitations and exclusions apply.
@@ -408,7 +408,7 @@ module JSS
           @exclusions = {}
           @exclusion_keys.each { |k| @exclusions[k] = [] }
         end
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # Replace a list of item names for as targets in this scope.
@@ -436,7 +436,7 @@ module JSS
         list.map! do |ident|
           item_id = validate_item(:target, key, ident)
 
-          if @exclusions[key] && @exclusions[key].include?(item_id)
+          if @exclusions[key]&.include?(item_id)
             raise JSS::AlreadyExistsError, \
                   "Can't set #{key} target to '#{ident}' because it's already an explicit exclusion."
           end
@@ -448,7 +448,7 @@ module JSS
 
         @targets[key] = list
         @all_targets = false
-        @container.should_update if @container
+        @container&.should_update
       end # sinclude_in_scope
       alias set_target set_targets
       alias set_inclusion set_targets
@@ -474,13 +474,13 @@ module JSS
       def add_target(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:target, key, item)
-        return if @targets[key] && @exclusions[key].include?(item_id)
+        return if @targets[key]&.include?(item_id)
 
-        raise JSS::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key] && @exclusions[key].include?(item_id)
+        raise JSS::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key]&.include?(item_id)
 
         @targets[key] << item_id
         @all_targets = false
-        @container.should_update if @container
+        @container&.should_update
       end
       alias add_inclusion add_target
 
@@ -499,10 +499,10 @@ module JSS
         key = pluralize_key(key)
         item_id = validate_item :target, key, item, error_if_not_found: false
         return unless item_id
-        return unless @targets[key] && @exclusions[key].include?(item_id)
+        return unless @targets[key]&.include?(item_id)
 
         @targets[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end
       alias remove_inclusion remove_target
 
@@ -529,7 +529,7 @@ module JSS
         # check the idents
         list.map! do |ident|
           item_id = validate_item(:limitation, key, ident)
-          if @exclusions[key] && @exclusions[key].include?(item_id)
+          if @exclusions[key]&.include?(item_id)
             raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion."
           end
 
@@ -539,7 +539,7 @@ module JSS
         return nil if list.sort == @limitations[key].sort
 
         @limitations[key] = list
-        @container.should_update if @container
+        @container&.should_update
       end # set_limitation
       alias set_limitations set_limitation
 
@@ -561,14 +561,14 @@ module JSS
       def add_limitation(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:limitation, key, item)
-        return nil if @limitations[key] && @exclusions[key].include?(item_id)
+        return nil if @limitations[key]&.include?(item_id)
 
-        if @exclusions[key] && @exclusions[key].include?(item_id)
+        if @exclusions[key]&.include?(item_id)
           raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion."
         end
 
         @limitations[key] << item_id
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # Remove a single item for limiting this scope.
@@ -588,10 +588,10 @@ module JSS
         key = pluralize_key(key)
         item_id = validate_item :limitation, key, item, error_if_not_found: false
         return unless item_id
-        return unless @limitations[key] && @exclusions[key].include?(item_id)
+        return unless @limitations[key]&.include?(item_id)
 
         @limitations[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end ###
 
       # Replace an exclusion list for this scope
@@ -617,7 +617,9 @@ module JSS
           item_id = validate_item(:exclusion, key, ident)
           case key
           when *@target_keys
-            raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already explicitly included." if @targets[key] && @exclusions[key].include?(item_id)
+            if @targets[key] && @exclusions[key].include?(item_id)
+              raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already explicitly included."
+            end
           when *LIMITATIONS
             if @limitations[key] && @exclusions[key].include?(item_id)
               raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already an explicit limitation."
@@ -629,7 +631,7 @@ module JSS
         return nil if list.sort == @exclusions[key].sort
 
         @exclusions[key] = list
-        @container.should_update if @container
+        @container&.should_update
       end # limit scope
 
       # Add a single item for exclusions of this scope.
@@ -648,14 +650,14 @@ module JSS
       def add_exclusion(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:exclusion, key, item)
-        return if @exclusions[key] && @exclusions[key].include?(item_id)
+        return if @exclusions[key]&.include?(item_id)
 
-        raise JSS::AlreadyExistsError, "Can't exclude #{key} scope to '#{item}' because it's already explicitly included." if @targets[key] && @targets[key].include?(item)
+        raise JSS::AlreadyExistsError, "Can't exclude #{key} scope to '#{item}' because it's already explicitly included." if @targets[key]&.include?(item)
 
-        raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{item}' because it's already an explicit limitation." if @limitations[key] && @limitations[key].include?(item)
+        raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{item}' because it's already an explicit limitation." if @limitations[key]&.include?(item)
 
         @exclusions[key] << item_id
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # Remove a single item for exclusions of this scope
@@ -672,10 +674,10 @@ module JSS
       def remove_exclusion(key, item)
         key = pluralize_key(key)
         item_id = validate_item :exclusion, key, item, error_if_not_found: false
-        return unless @exclusions[key] && @exclusions[key].include?(item_id)
+        return unless @exclusions[key]&.include?(item_id)
 
         @exclusions[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # @api private
@@ -773,7 +775,7 @@ module JSS
       ################
       def scoped_machines
         scoped_machines = {}
-        @target_class.all_objects.each do |machine|
+        @target_class.all_objects(api: container.api).each do |machine|
           scoped_machines[machine.id] = machine.name if in_scope? machine
         end
         scoped_machines
@@ -809,7 +811,6 @@ module JSS
         a_target?(machine_data) && within_limitations?(machine_data) && !excluded?(machine_data)
       end
 
-
       # Private Instance Methods
       #####################################
       private
@@ -850,15 +851,15 @@ module JSS
 
         # id will be a string
         if key == :jamf_ldap_users
-          id = ident if JSS::User.all_names(:refresh).include?(ident) || JSS::LDAPServer.user_in_ldap?(ident)
+          id = ident if JSS::User.all_names(:refresh, api: container.api).include?(ident) || JSS::LDAPServer.user_in_ldap?(ident)
 
         # id will be a string
         elsif key == :ldap_user_groups
-          id = ident if JSS::LDAPServer.group_in_ldap? ident
+          id = ident if JSS::LDAPServer.group_in_ldap? ident, api: container.api
 
         # id will be an integer
         else
-          id = SCOPING_CLASSES[key].valid_id ident
+          id = SCOPING_CLASSES[key].valid_id ident, api: container.api
         end
 
         raise JSS::NoSuchItemError, "No existing #{key} matching '#{ident}'" if error_if_not_found && id.nil?
@@ -930,7 +931,7 @@ module JSS
       # @return [Array] the general, locacation, and parsed group IDs
       #
       def fetch_subsets(ident)
-        id = @target_class.valid_id ident
+        id = @target_class.valid_id ident, api: container.api
         raise JSS::NoSuchItemError, "No #{@target_class} matching #{machine}" unless id
 
         if @target_class == JSS::MobileDevice