ruby-jss 1.3.3 → 1.6.0b1

data/lib/jss/api_object/network_segment.rb

@@ -435,9 +435,10 @@ module JSS
         @starting_address <= thing.range.begin && @ending_address >= thing.range.end
       else
         thing = IPAddr.new thing.to_s
-        range.include? thing
+        range.cover? thing
       end
     end
+    alias cover? include?
 
     ### Does this network segment equal another?
     ### equality means the ranges are equal
@@ -459,9 +460,17 @@ module JSS
     ### @return [void]
     ###
     def building=(newval)
-      new = JSS::Building.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No building matching '#{newval}'" unless new
-      @building = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::Building.valid_id newval
+          raise JSS::MissingDataError, "No building matching '#{newval}'" unless id
+
+          JSS::Building.map_all_ids_to(:name)[id]
+        end
+
+      @building = new
       @need_to_update = true
     end
 
@@ -484,9 +493,16 @@ module JSS
     ### @return [void]
     ###
     def department=(newval)
-      new = JSS::Department.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No department matching '#{newval}' in the JSS" unless new
-      @department = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::Department.valid_id newval
+          raise JSS::MissingDataError , "No department matching '#{newval}' in the JSS" unless id
+
+          JSS::Department.map_all_ids_to(:name)[id]
+        end
+      @department = new
       @need_to_update = true
     end
 
@@ -531,9 +547,17 @@ module JSS
     ### @return [void]
     ###
     def netboot_server=(newval)
-      new = JSS::NetbootServer.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No netboot_server matching '#{newval}' in the JSS" unless new
-      @netboot_server = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::NetBootServer.valid_id newval
+          raise JSS::MissingDataError, "No netboot_server matching '#{newval}' in the JSS" unless id
+
+          JSS::NetbootServer.map_all_ids_to(:name)[id]
+        end
+
+      @netboot_server = new
       @need_to_update = true
     end
 
@@ -544,9 +568,17 @@ module JSS
     ### @return [void]
     ###
     def swu_server=(newval)
-      new = JSS::SoftwareUpdateServer.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No swu_server matching '#{newval}' in the JSS" unless new
-      @swu_server = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::SoftwareUpdateServer.valid_id newval
+          raise JSS::MissingDataError, "No swu_server matching '#{newval}' in the JSS" unless id
+
+          JSS::SoftwareUpdateServer.map_all_ids_to(:name)[id]
+        end
+
+      @swu_server = new
       @need_to_update = true
     end
 

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

@@ -148,6 +148,12 @@ module JSS
       monthly: 'Once every month'
     }.freeze
 
+    RETRY_EVENTS = {
+      none: 'none',
+      checkin: 'check-in',
+      trigger: 'trigger'
+    }.freeze
+
     RESTART_WHEN = {
       if_pkg_requires: 'Restart if a package or update requires it',
       now: 'Restart immediately',
@@ -257,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
@@ -281,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
     ######################
 
@@ -613,7 +699,6 @@ module JSS
 
       if @in_jss
         gen = @init_data[:general]
-        @frequency = gen[:frequency]
         @target_drive = gen[:target_drive]
         @offline = gen[:offline]
         @enabled = gen[:enabled]
@@ -629,6 +714,10 @@ module JSS
           trigger_enrollment_complete: gen[:trigger_enrollment_complete],
           trigger_other: gen[:trigger_other]
         }
+        @frequency = gen[:frequency]
+        @retry_event = gen[:retry_event]
+        @retry_attempts = gen[:retry_attempts]
+        @notify_failed_retries = gen[:notify_on_each_failed_retry]
 
         dtl = gen[:date_time_limitations]
 
@@ -745,8 +834,93 @@ module JSS
     # @return [void]
     #
     def frequency=(freq)
-      raise JSS::InvalidDataError, "New frequency must be one of :#{FREQUENCIES.keys.join ', :'}" unless FREQUENCIES.key?(freq)
-      @frequency = FREQUENCIES[freq]
+      raise JSS::InvalidDataError, "New frequency must be one of :#{FREQUENCIES.keys.join ', :'}" unless FREQUENCIES.key?(freq) || FREQUENCIES.value?(freq)
+
+      freq = freq.is_a?(Symbol) ? FREQUENCIES[freq] : freq
+      return if freq == @frequency
+
+      @frequency = freq
+      @need_to_update = true
+    end
+
+    # @return [String] The event that causes a policy retry
+    def retry_event
+      return RETRY_EVENTS[:none] unless FREQUENCIES[:once_per_computer] == @frequency
+
+      @retry_event
+    end
+
+    # Set the event that causes a retry if the policy fails.
+    # One of the ways to turn off policy retry is to set this to :none
+    # The other is to set the retry_attempts to 0
+    #
+    # @param [Symbol, String] A key or value from RETRY_EVENTS
+    # @return [void]
+    #
+    def retry_event=(evt)
+      validate_retry_opt
+      raise JSS::InvalidDataError, "Retry event must be one of :#{RETRY_EVENTS.keys.join ', :'}" unless RETRY_EVENTS.key?(evt) || RETRY_EVENTS.value?(evt)
+
+      evt = evt.is_a?(Symbol) ? RETRY_EVENTS[evt] : evt
+      return if evt == @retry_event
+
+      # if the event is not 'none' and attempts is <= 0,
+      # set events to 1, or the API won't accept it
+      unless evt == RETRY_EVENTS[:none]
+        @retry_attempts = 1 unless @retry_attempts.positive?
+      end
+
+      @retry_event = evt
+      @need_to_update = true
+    end
+
+    # @return [Integer] How many times wil the policy be retried if it fails.
+    #   -1 means no retries,  otherwise, an integer from 1 to 10
+    def retry_attempts
+      return 0 unless FREQUENCIES[:once_per_computer] == @frequency
+
+      @retry_attempts
+    end
+
+    # Set the number of times to retry if the policy fails.
+    # One of the ways to turn off policy retry is to set this to 0 or -1
+    # The other is to set retry_event to :none
+    #
+    # @param [Integer] From -1 to 10
+    # @return [void]
+    #
+    def retry_attempts=(int)
+      validate_retry_opt
+      raise JSS::InvalidDataError, 'Retry attempts must be an integer from 0-10' unless int.is_a?(Integer) && (-1..10).include?(int)
+
+      # if zero or -1, turn off retries
+      if int <= 0
+        @retry_event = RETRY_EVENTS[:none]
+        int = -1
+      end
+      return if @retry_attempts == int
+
+      @retry_attempts = int
+      @need_to_update = true
+    end
+
+    # @return [Boolean] Should admins be notified of failed retry attempts
+    def notify_failed_retries?
+      return false unless FREQUENCIES[:once_per_computer] == @frequency
+
+      @notify_failed_retries
+    end
+    alias notify_failed_retries notify_failed_retries?
+    alias notify_on_each_failed_retry notify_failed_retries?
+
+    # @param bool[Boolean] Should admins be notified of failed retry attempts
+    # @return [void]
+    def notify_failed_retries=(bool)
+      validate_retry_opt
+      bool = JSS::Validate.boolean bool
+      return if @notify_failed_retries == bool
+
+      @notify_failed_retries = bool
       @need_to_update = true
     end
 
@@ -1314,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
@@ -1621,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
@@ -1656,6 +1880,17 @@ module JSS
 
     private
 
+    # raise an error if a trying to set retry options when
+    # frequency is not 'once per comptuer'
+    #
+    # @return [void]
+    #
+    def validate_retry_opt
+      return if FREQUENCIES[:once_per_computer] == @frequency
+
+      raise JSS::UnsupportedError, 'Policy retry is only available when frequency is set to :once_per_computer'
+    end
+
     # raise an error if a package being added isn't valid
     #
     # @see #add_package
@@ -1786,6 +2021,10 @@ module JSS
       general.add_element('name').text = @name
       general.add_element('enabled').text = @enabled
       general.add_element('frequency').text = @frequency
+      general.add_element('retry_event').text = @retry_event
+      general.add_element('retry_attempts').text = @retry_attempts.to_s
+      general.add_element('notify_on_each_failed_retry').text = @notify_failed_retries.to_s
+
       general.add_element('target_drive').text = @target_drive
       general.add_element('offline').text = @offline