ruby-jss 1.2.10 → 1.5.2

data/lib/jss/api_object/ebook.rb

@@ -23,12 +23,11 @@
 ###
 ###
 
-# This is just a stub for now.
 
 #
 module JSS
 
-  #
+  # This is just a stub for now.
   class EBook < APIObject
 
     include Sitable

data/lib/jss/api_object/extendable.rb

@@ -23,7 +23,6 @@
 #
 #
 
-#
 module JSS
 
   # Sub-Modules
@@ -221,6 +220,7 @@ module JSS
       eaxml = REXML::Element.new('extension_attributes')
       @extension_attributes.each do |ea|
         next unless @changed_eas.include? ea[:name]
+
         ea_el = eaxml.add_element('extension_attribute')
         ea_el.add_element('name').text = ea[:name]
 

data/lib/jss/api_object/extension_attribute.rb

@@ -179,9 +179,10 @@ module JSS
       # deprecated - no longer in the UI
       @recon_display = @init_data[:recon_display] || @web_display
 
-      # the name of the EA might have spaces and caps, which the will come to us as symbols with the spaces
-      # as underscores, like this.
-      @symbolized_name = @name.gsub(/-| /, '_').to_sym
+      # When used in Advanced Search results, the EA name
+      # has colons removed, spaces & dashes turned to underscores.
+      # and then ruby-jss symbolizes the name.
+      @symbolized_name = @name.gsub(':', '').gsub(/-| /, '_').to_sym
     end # init
 
     # Public Instance Methods

data/lib/jss/api_object/group.rb

@@ -241,7 +241,7 @@ module JSS
     #
     # @param retries [Integer] If calculate_members is true, refetching the
     #   group to re-read the membership can happen too fast, the JSS won't know
-    #   it exists yet and will throw a RestClient::NotFound error.  If that
+    #   it exists yet and will throw a NoSuchItem error.  If that
     #   happens, try again this many times with a 1 second pause between attempts.
     #
     def create(calculate_members: true, retries: 10)
@@ -256,7 +256,7 @@ module JSS
           begin
             refresh_members
             break
-          rescue RestClient::NotFound
+          rescue
             sleep 1
             tries += 1
           end # begin
@@ -311,6 +311,37 @@ module JSS
       super
     end
 
+    # Change static group to smart group
+    #
+    # @param args[Hash] the options and settings use for switching the computer group from static group to smart group
+    #
+    # @option args criteria[Array] The criterias to be user for the smart group
+    def set_smart(*params)
+      return if @is_smart
+
+      params[:criteria] = [] if params[:criteria].nil?
+
+      criteria = params[:criteria]
+
+      @is_smart = true
+      @need_to_update = true
+    end
+
+    # Change smart group to static group
+    #
+    # @param args[Hash] the options and settings use for switching the computer group from smart group to static group
+    #
+    # @option args preserve_members[Boolean] Should the smart group preserve it's current members?
+    def set_static(*params)
+      return unless @is_smart
+
+      preserve_members = params.include? :preserve_members
+
+      @is_smart = false
+
+      clear() unless preserve_members
+    end
+
     # How many members of the group?
     #
     # @return [Integer] the number of members of the group

data/lib/jss/api_object/mac_application.rb

@@ -22,15 +22,19 @@
 ###    language governing permissions and limitations under the Apache License.
 ###
 
-# This is just a stub for now.
-
-#
 module JSS
 
-  #
-  class MacApplication < APIObject
+  # This is just a stub for now.
+  class MacApplication < JSS::APIObject
 
-    include Sitable
+    # Mix-Ins
+    #####################################
+    include JSS::Updatable
+    include JSS::Scopable
+    include JSS::SelfServable
+    include JSS::Categorizable
+    include JSS::VPPable
+    include JSS::Sitable
 
     ### The base for REST resources of this class
     RSRC_BASE = 'macapplications'.freeze
@@ -47,9 +51,104 @@ module JSS
     # See {APIObject#add_object_history_entry}
     OBJECT_HISTORY_OBJECT_TYPE = 350
 
+    # See JSS::Scopable
+    SCOPE_TARGET_KEY = :computers
+
+    # Where is the Category in the API JSON?
+    CATEGORY_SUBSET = :general
+
+    # How is the category stored in the API data?
+    CATEGORY_DATA_TYPE = Hash
+
     # Where is the Site data in the API JSON?
     SITE_SUBSET = :general
 
-  end
+    # Attributes
+    #############################################
+
+    # @return [String]
+    attr_reader :version
+
+    # @return [Boolean]
+    attr_reader :is_free
+    alias free? is_free
+
+    # @return [String]
+    attr_reader :bundle_id
+
+    # @return [String]
+    attr_reader :url
+
+    ## Constructor
+    #####################################
+
+    def initialize(args = {})
+      super
+      general = @init_data[:general]
+      @version = general[:version]
+      @is_free = general[:is_free]
+      @bundle_id = general[:bundle_id]
+      @url = general[:url]
+    end
+
+    # Overrides, because consistency isn't alway a thing in the
+    # classic API
+    #############################################
+
+    # Override self_service_display_name getter
+    def self_service_display_name
+      raise JSS::UnsupportedError, 'MacApplications do not have separate display names. Please use the object name.'
+    end
+
+    # Override self_service_display_name setter
+    def self_service_display_name=(_newname)
+      raise JSS::UnsupportedError, 'MacApplications do not have separate display names. Please use the object name.'
+    end
+
+    # Override reinstall_button_text getter
+    def reinstall_button_text
+      raise JSS::UnsupportedError, 'MacApplications do not have separate text for reinstall buttons. Please use install_button_text.'
+    end
+
+    # Override reinstall_button_text setter
+    def reinstall_button_text=(_new)
+      raise JSS::UnsupportedError, 'MacApplications do not have separate text for reinstall buttons. Please use install_button_text.'
+    end
+
+    # Alas, SSvc icons are not uploadable via the API for
+    # mac apps
+    def upload(_type, _local_file)
+      raise JSS::UnsupportedError, 'The Classic API does not support uploading icons for MacApplications. Please use the Web UI'
+    end
+
+    ## Private Instance Methods
+    #####################################
+    private
+
+    ### Return the xml for creating or updating this script in the JSS
+    ###
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      obj = doc.add_element RSRC_OBJECT_KEY.to_s
+
+      general = obj.add_element('general')
+
+      general.add_element('version').text = @version
+      general.add_element('is_free').text = @is_free.to_s
+      general.add_element('bundle_id').text = @bundle_id
+      general.add_element('url').text = @url
+
+      obj << @scope.scope_xml
+
+      add_self_service_xml doc
+      add_category_to_xml doc
+      add_site_to_xml doc
+      add_vpp_xml doc
+
+      doc.to_s
+
+    end
+
+  end # class MacApplication
 
-end
+end # Module JSS

data/lib/jss/api_object/mobile_device_application.rb

@@ -444,6 +444,18 @@ module JSS
       refresh_ipa
     end
 
+    # Remove the various cached data
+    # from the instance_variables used to create
+    # pretty-print (pp) output.
+    #
+    # @return [Array] the desired instance_variables
+    #
+    def pretty_print_instance_variables
+      vars = super
+      vars.delete :@ipa
+      vars
+    end
+
     # Private Instance Methods
     ###########################################
     private

data/lib/jss/api_object/network_segment.rb

@@ -67,21 +67,70 @@ module JSS
     ### Class Methods
     #####################################
 
-    ### All NetworkSegments in the jss as IPAddr object Ranges representing the
-    ### Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
-    ### the range looks like:
-    ###   <IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>
-    ###
-    ### Using the #include? method on those Ranges is very useful.
-    ###
-    ### @param refresh[Boolean] re-read the data from the API?
-    ###
-    ### @param api[JSS::APIConnection] The API connection to query
-    ###
-    ### @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
-    ###
+    # All NetworkSegments in the given API as ruby Ranges of IPAddr instances
+    # representing the Segment,
+    # e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
+    # the range looks like:
+    #  <IPAddr: IPv4:10.24.9.1/255.255.255.255>
+    #   ..
+    #  <IPAddr: IPv4:10.24.15.254/255.255.255.255>
+    #
+    # Using the #include? method on those Ranges is very useful.
+    #
+    # Note1: We don't use the IPAddr#to_range method because that works
+    #   best for masked IPAddrs (which are ranges of IPs with widths
+    #   determined by the mask) and Jamf Network Segments can have arbitrary
+    #   widths.
+    #
+    # Note2: See the network_ranges_as_integers method below, which is similar
+    #   but much faster.
+    #
+    # @param refresh[Boolean] should the data be re-queried?
+    #
+    # @param api[JSS::APIConnection] the API to query
+    #
+    # @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
+    #   keyed by id
+    #
     def self.network_ranges(refresh = false, api: JSS.api)
-      api.network_ranges refresh
+      @network_ranges = nil if refresh
+      return @network_ranges if @network_ranges
+
+      @network_ranges = {}
+      all(refresh, api: api).each do |ns|
+        @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address])
+      end
+      @network_ranges
+    end # def network_segments
+
+    # An IPv4 Address is really just a 32-bit integer, displayed as four
+    # 8-bit integers. e.g. '10.0.69.1' is really the integer 167789825
+    # The #to_i method of IPAddr objects returns that integer (or the first of
+    # them if the IPAddr is masked).
+    #
+    # Using ranges made of those integers is far faster than using ranges
+    # if IPAddr objects, so that's what this method returns.
+    #
+    # See also: the network_ranges method above
+    #
+    # @param refresh[Boolean] should the data be re-queried?
+    #
+    # @param api[JSS::APIConnection] the APIConnection to query
+    #
+    # @return [Hash{Integer => Range}] the network segments as Integer Ranges
+    #   keyed by id
+    #
+    def self.network_ranges_as_integers(refresh = false, api: JSS.api)
+      @network_ranges_as_integers = nil if refresh
+      return @network_ranges_as_integers if @network_ranges_as_integers
+
+      @network_ranges_as_integers = {}
+      all(refresh, api: api).each do |ns|
+        first = IPAddr.new(ns[:starting_address]).to_i
+        last = IPAddr.new(ns[:ending_address]).to_i
+        @network_ranges_as_integers[ns[:id]] = first..last
+      end
+      @network_ranges_as_integers
     end # def network_segments
 
     ### An alias for {NetworkSegment.network_ranges}
@@ -195,23 +244,72 @@ module JSS
     ###
     ### @return [Array<Integer>] the ids of the NetworkSegments containing the given ip
     ###
-    def self.network_segments_for_ip(ip, refresh = false, api: JSS.api)
-      ok_ip = IPAddr.new(ip)
-      matches = []
-      network_ranges(refresh, api: api).each { |id, subnet| matches << id if subnet.include?(ok_ip) }
-      matches
+    def self.network_segments_for_ip(ipaddr, refresh = false, api: JSS.api)
+      # get the ip as a 32bit interger
+      ip = IPAddr.new(ipaddr.to_s).to_i
+      # a hash of NetSeg ids => Range<Integer>
+      network_ranges_as_integers(refresh, api: api).select { |_id, range| range.include? ip }.keys
+    end
+
+    # Which network segment is seen as current for a given IP addr?
+    #
+    # According to the Jamf Pro Admin Guide, if an IP is in more than one network
+    # segment, it uses the 'smallest' (narrowest) one - the one with fewest
+    # IP addrs within it.
+    #
+    # If multiple ones have the same width, then it uses the one of
+    # those with the lowest starting address
+    #
+    # @return [Integer, nil] the id of the current net segment, or nil
+    #
+    def self.network_segment_for_ip(ipaddr, refresh: false, api: JSS.api)
+      # get the ip as a 32bit interger
+      ip = IPAddr.new(ipaddr.to_s).to_i
+      # a hash of NetSeg ids => Range<Integer>
+      ranges = network_ranges_as_integers(refresh, api: api).select { |_id, range| range.include? ip }
+
+      # we got nuttin
+      return nil if ranges.empty?
+
+      # if we got only one, its the one
+      return ranges.keys.first if ranges.size == 1
+
+      # got more than one, sort by range size/width, asc.
+      sorted_by_size = ranges.sort_by { |_i, r| r.size }.to_h
+
+      # the first one is the smallest/narrowest.
+      _smallest_range_id, smallest_range = sorted_by_size.first
+
+      smallest_range_size = smallest_range.size
+
+      # select all of them that are the same size
+      all_of_small_size = sorted_by_size.select { |_i, r| r.size == smallest_range_size }
+
+      # sort them by the start of each range (r.first)
+      # and return the lowest start (returned by min_by)
+      my_range_id, _my_range = all_of_small_size.min_by { |_i, r| r.first }
+
+      # and return the id
+      my_range_id
     end
 
-    # @deprecated use network_segments_for_ip
-    # Here for Backward compatibility
-    def self.network_segment_for_ip(ip, api: JSS.api)
-      network_segments_for_ip(ip, api: api)
+    # given 2 IPAddr instances, find out how 'wide' they are -
+    # how many IP addresses exist between them.
+    def self.ip_range_width(ip1, ip2)
+      raise ArgumentError, 'Parameters must be IPAddr objects' unless ip1.is_a?(IPAddr) && ip2.is_a?(IPAddr)
+
+      low, high = [ip1, ip2].sort
+      high.to_i - low.to_i
     end
 
-    ### Find the current network segment ids for the machine running this code
-    ###
-    ### @return [Array<Integer>] the NetworkSegment ids for this machine right now.
-    ###
+    # Find the current network segment ids for the machine running this code
+    #
+    # See my_network_segment to get the current one according to the server.
+    #
+    # @param names [Boolean] the array will contain Network Segment names, not ids
+    #
+    # @return [Array<Integer>,Array<String>] the NetworkSegment ids or names for this machine right now.
+    #
     def self.my_network_segments(refresh = false, names: false, api: JSS.api)
       ids = network_segments_for_ip JSS::Client.my_ip_address, refresh, api: api
       return ids unless names
@@ -220,35 +318,23 @@ module JSS
       ids.map { |id| ids_to_names[id] }
     end
 
-    # @deprecated use my_network_segments
-    # Here for backward compatibility
-    def self.my_network_segment(api: JSS.api)
-      my_network_segments api: api
-    end
-
-    # All NetworkSegments in the given API as IPAddr object Ranges representing the
-    # Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
-    # the range looks like:
-    #   <IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>
+    # Which network segment is seen as current? According to the
+    # Jamf Pro Admin Guide, the 'smallest' one - the one with fewest IP
+    # addrs within it.  If multiple ones have the same number of IPs,
+    # then its the one with the lowest starting address
     #
-    # Using the #include? method on those Ranges is very useful.
+    # @param name [Boolean] return the name of the netsegment, not the id
     #
-    # @param refresh[Boolean] should the data be re-queried?
-    #
-    # @param api[JSS::APIConnection] the API to query
-    #
-    # @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
-    #   keyed by id
-    #
-    def self.network_ranges(refresh = false, api: JSS.api)
-      @network_ranges = nil if refresh
-      return @network_ranges if @network_ranges
-      @network_ranges = {}
-      all(refresh, api: api).each do |ns|
-        @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address])
-      end
-      @network_ranges
-    end # def network_segments
+    # @return [Integer, String, nil] the id of the current net segment, or nil
+    def self.my_network_segment(refresh = false, name: false, api: JSS.api)
+      my_ip = JSS::Client.my_ip_address
+      return nil unless my_ip
+
+      id = network_segment_for_ip(my_ip, refresh: refresh, api: api)
+      return id unless name
+
+      map_all_ids_to(:name)[id]
+    end
 
     ### Attributes
     #####################################
@@ -373,9 +459,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
 
@@ -398,9 +492,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
 
@@ -419,14 +520,22 @@ module JSS
 
     ### set the distribution_point
     ###
-    ### @param newval[String, Integer] the new dist. point by name or id, must be in the JSS
+    ### @param newval[String, Integer, nil] the new dist. point by name or id, must be in the JSS, or nil  or blank to unset
     ###
     ### @return [void]
     ###
     def distribution_point=(newval)
-      new = JSS::DistributionPoint.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No distribution_point matching '#{newval}' in the JSS" unless new
-      @distribution_point = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::DistributionPoint.valid_id newval
+          raise JSS::MissingDataError, "No distribution_point matching '#{newval}' in the JSS" unless id
+
+          JSS::DistributionPoint.map_all_ids_to(:name)[id]
+        end
+
+      @distribution_point = new
       @need_to_update = true
     end
 
@@ -437,9 +546,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
 
@@ -450,9 +567,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