ruby-jss 1.1.3 → 1.2.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90a0bdaae94b5d0d1cb5ccad691ecf57daa75e205ceda668813655484ee232c8
-  data.tar.gz: 6c8e0211b2397df59d576b8fec2901f22003dd2d562c7a755209ebd0026493ca
+  metadata.gz: 2aa99b8b7dcfc161d2251f1af4b6efa5d302a575bcadc5feb843536252acf98b
+  data.tar.gz: cb691744d29c3d9ff178cd56d33dcab35f7a5a00ddcdc831b6ade3f33209496e
 SHA512:
-  metadata.gz: de40656a561b6624eaa28b4c851314de7bb4a84e151f656d1c021a784255c5c95ce76b2e7013553cc02f3094707934481e05059bf931b3fd9c659eedb8e05415
-  data.tar.gz: 8fdef7af00dc52b1ce253288415eade80d8d3812ed5470ad84f0e3c9292c95e32b1080b7c56e7457ce21e927bb0782e63124df1bb5efa2423e95694c620a148e
+  metadata.gz: 3fc08c5a37bd84d8077b15827357918e2d1b901b85f5341099540941cff8001ffcbeb0242a2e133e1909efd0fc14b6910e92b8f5d03660344129dd1404485f24
+  data.tar.gz: 6548b0c75545dda10280d8200cb2496799dcf015304c2e5d32da3db34591f2ee02e53c7e6bb15f6138628744ee16cb87760f8215ced4f19a7325a07683dfe505

data/CHANGES.md

@@ -4,43 +4,94 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.2.0] - Unreleased
+### Added
+- APIConnection#flushcache can be used to flush all cached data, or just for specific APIObject lists or ExtensionAttribute definitions. This is now used more often throughout ruby-jss.
+
+### Fixed
+- Group.all_static was returning all_smart,  now actually returns all_static
+
+- Fix in error message raised in Group.change_membership
+
+- APIConnection#connect now flushes all cached data, so if you use it to change which server is being used by an existing connection, you don't keep the cached data from the old server.
+
+- PatchPolicy now overrides APIObject.fetch to still allow for fetching by name, even there's no patchpolicies/name/... endpoint
+
+### Changed
+- Group#create with `calculate_members: true`, will sometimes try to re-read the new group before the JSS knows it exists, causing a `404 Not Found` error.  This is especially common when using a clustered environment behind a load-balanced hostname (like _something.jamfcloud.com_).
+Now, if a 404 happens when trying to refresh the membership using calculate_members, ruby-jss will retry every second for up to 10 seconds.
+To change the number of retries, provide an integer with the `retries:` parameter. If you don't need to know the group members after creation, pass `calculate_members: false` when calling Group#create or Group#save
+
+- Creating, Updating, or Deleting objects of the APIObject subclasses now flushes the cached `all` lists for that class, so subseqent uses of the `all` lists will refresh the data from the API. This means that `APIObject.valid_id` will work immediately upon object creation. NOTE: However, when using a clustered environment behind a load-balanced hostname (like jamfcloud.com), it may take some time for the `all` list to update on all nodes of the cluster, so you might still need to pause up to the number of seconds defined of the cluster's sync interval to ensure valid lists.
+
+- Case-insentive lookup & validation methods in APIObject now use `String#casecmp?` for much simpler code
+
+- Creatable#create no longer takes an `api:` parameter (it never should have) The API connection given in #make is always used for creating the object in the API.
+
+- Added class JSS::IBeacon, implementing the .../ibeacons/... endpoints
+
 ## \[1.1.3] - 2019-09-23
 ### Added
 - MobileDeviceExtensionAttribute now has a `.history` class method matching that of ComputerExtensionAttribute. Requires direct MySQL database access. Thanks @aurica!
+
 - JSS::AmbiguousError exception class
+
 - More caching of API data to improve general speed
   - The hashes created by `APIObject.map_all_ids_to(blah)`
   - ExtensionAttribute definitions when used by extendable classes
+
 - APIObject.fetch can take the search term `:random` and you'll get a randomly selected object. Example: `a_random_computer = JSS::Computer.fetch :random`
+
 - Keys of the hash returned by `Computer#hardware` are now available as instance methods on Computer objects. So as well as `a_computer.hardware[:total_ram]` you can also do `a_computer.total_ram`
+
 - Policy now recognizes the frequency Symbol `:once_per_user_per_computer`
+
 - Attribute reader :management_status added to Computer class
+
 - Implemented some useful String methods from newer versions of Ruby into older Rubies: `casecmp?`, `delete_prefix`, & `delete_suffix`
+
 - master_distribution_point class method in APIConnection & DistribtutionPoint now raise an error when no dist. point is 'master'
   - The error states that the cloud dist. point may be the master, and there's no classic API access to it.
 
 
 ### Fixed
 - Can't Modify Frozen Hash error when instantiating JSS::Scopbable::Scope. Thanks to @shahn for reporting this one.
+
 - MobileDeviceExtensionAttribute now handles empty `as_of` timestamp. Thanks @aurica!
+
 - A few typos. Thanks to @cybertunnel for finding some.
+
 - A bug when parsing the `server_path` parameter to `API::Connection.new`
+
 - Bugs in handling blank values in Policy#search_by_path and Policy#printer_ids. Thanks @cybertunnel
+
 - Computer.management_data with a specified subset returned one level too high in the data structure
+
 - NetworkSegment.my_network_segment: error in number of params passed to other methods
+
 - Script#name= now works again, no longer uses a constant from an ancient version. Thanks @shahn
+
 - Computer#asset_tag= now accepts nil to erase the value
+
 - APIConnection.my_distribution_point & DistributionPoint.my_distribution_point now return the master_distribution_point object if there isn't one assigned to the current network segment.
+
 - RestClient no longer warns about calling 'to_i' on Responses when calling APIConnection#put_rsrc & #post_rsrc
 
 ### Changed
 - Monkey Patches are being moved to a better, more traceable technique, see https://www.justinweiss.com/articles/3-ways-to-monkey-patch-without-making-a-mess/
+
 - MobileDevices and Computers now raise JSS::AmbiguousError when being fetched by explicitly by name, e.g. `JSS::Computer.fetch name: 'foo'` and that name is not unique in the JSS. Previously, you'd get an object back, but no guarantee as to which one it was. You'll still get an undefined object if you use a bare searchterm, e.g. `JSS::Computer.fetch 'foo'`
+
 - Documentation for subclassing APIObject is updated & expanded. See the comments above the class definition in api_object.rb
+
 - `APIObject.valid_id` is now case-insensitive
+
 - Removed deprecated VALID_DATA_KEYS constants from APIObject subclasses
+
 - Various changes in APIObject and its subclasses to try making `.fetch` and other lookup-methods faster.
+
 - All of the NetworkSegment-related methods in APIConnection have been moved back to NetworkSegment. The methods in APIConnection still work, but are marked deprecated and will go away eventually.
+
 - Removed last call to deprecated `URI.encode`, replaced with `CGI.escape`
 
 

data/lib/jss/api_connection.rb

@@ -324,6 +324,9 @@ module JSS
 
     RSRC_NOT_FOUND_MSG = 'The requested resource was not found'.freeze
 
+    # These classes are extendable, and may need cache flushing for EA definitions
+    EXTENDABLE_CLASSES = [JSS::Computer, JSS::MobileDevice, JSS::User].freeze
+
     # Attributes
     #####################################
 
@@ -420,10 +423,8 @@ module JSS
     #
     def initialize(args = {})
       @name = args.delete :name
-      @name ||= :disconnected
+      @name ||= :unknown
       @connected = false
-      @object_list_cache = {}
-      @ext_attr_definition_cache = {}
       connect args unless args.empty?
     end # init
 
@@ -467,6 +468,9 @@ module JSS
     # @return [true]
     #
     def connect(args = {})
+      # new connections always get new caches
+      flushcache
+
       args[:no_port_specified] = args[:port].to_s.empty?
       args = apply_connection_defaults args
 
@@ -966,15 +970,33 @@ module JSS
     # Empty all cached lists from this connection
     # then run garbage collection to clear any available memory
     #
+    # If an APIObject Subclass's RSRC_LIST_KEY is specified, only the caches
+    # for that class are flushed (e.g. :computers, :comptuer_groups)
+    #
     # NOTE if you've referenced objects in these caches, those objects
     # won't be removed from memory, but all cached data will be recached
     # as needed.
     #
+    # @param key[Symbol, Class] Flush only the caches for the given RSRC_LIST_KEY. or
+    #   the EAdef cache for the given extendable class. If nil (the default)
+    #   flushes all caches
+    #
     # @return [void]
     #
-    def flushcache
-      @object_list_cache = {}
-      @ext_attr_definition_cache = {}
+    def flushcache(key = nil)
+      if EXTENDABLE_CLASSES.include? key
+        @ext_attr_definition_cache[key] = {}
+      elsif key
+        map_key_pfx = "#{key}_map_"
+        @object_list_cache.delete_if do |cache_key, _cache|
+          cache_key == key || cache_key.to_s.start_with?(map_key_pfx)
+        end
+        @ext_attr_definition_cache
+      else
+        @object_list_cache = {}
+        @ext_attr_definition_cache = {}
+      end
+
       GC.start
     end
 
@@ -1001,7 +1023,7 @@ module JSS
 
     # raise exception if not connected
     def validate_connected
-      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless connected?
+      raise JSS::InvalidConnectionError, "Connection '#{@name}' Not Connected. Use .connect first." unless connected?
     end
 
     # Apply defaults from the JSS::CONFIG,
@@ -1258,8 +1280,8 @@ module JSS
   # @return [APIConnection] the new, active connection
   #
   def self.new_api_connection(args = {})
+    args[:name] ||= :default
     @api = APIConnection.new args
-    @api
   end
 
   # Switch the connection used for all API interactions to the
@@ -1282,7 +1304,7 @@ module JSS
   # @return [void]
   #
   def self.use_default_connection
-    use_api_connection API
+    use_api_connection @api
   end
 
   # The currently active JSS::APIConnection instance.
@@ -1290,7 +1312,7 @@ module JSS
   # @return [JSS::APIConnection]
   #
   def self.api
-    @api
+    @api ||= APIConnection.new name: :default
   end
 
   # aliases of module methods
@@ -1310,7 +1332,7 @@ module JSS
   end
 
   # create the default connection
-  new_api_connection(name: :default) unless @api
+  new_api_connection unless @api
 
   # Save the default connection in the API constant,
   # mostly for backward compatibility.

data/lib/jss/api_object.rb

@@ -345,7 +345,7 @@ module JSS
       no_aliases ? @lookup_keys.values.uniq : @lookup_keys
     end
 
-    # Given a lookup or, or an alias of one, return the matching fetch_rsrc_key
+    # Given a lookup key, or an alias of one, return the matching fetch_rsrc_key
     # for building a fetch/GET resource URL, or nil if no fetch_rsrc_key is defined.
     #
     # See {OTHER_LOOKUP_KEYS} in the APIObject class comments/docs above for details.
@@ -452,7 +452,7 @@ module JSS
 
       cache = api.object_list_cache
       cache_key = self::RSRC_LIST_KEY
-      cache[cache_key] = nil if refresh
+      api.flushcache(cache_key) if refresh
       return cache[cache_key] if cache[cache_key]
 
       cache[cache_key] = api.get_rsrc(self::RSRC_BASE)[cache_key]
@@ -582,6 +582,7 @@ module JSS
     # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
     #
     def self.valid_id(identifier, refresh = false, api: JSS.api)
+
       # refresh if needed
       all(refresh, api: api) if refresh
 
@@ -591,26 +592,11 @@ module JSS
       keys_to_check = lookup_keys(no_aliases: true)
       keys_to_check.delete :id # we've already checked :id
 
-      # downcase for speedy case-insensitivity -
-      # include?, and I assume value?, is faster with downcasing. See
-      # https://stackoverflow.com/questions/9333952/case-insensitive-arrayinclude/9334066#9334066
-      identifier.downcase! if identifier.is_a? String
-
       keys_to_check.each do |key|
         mapped_ids = map_all_ids_to key, api: api
-        # downcase - see comment above
-        mapped_ids.each { |_k, v| v.downcase! if v.is_a? String }
-
-        # if name is not unique, skip to the next key, there is no
-        # valid id for a non-unique name
-        if key == :name
-          num_name_matches = mapped_ids.values.select { |n| n == identifier }.size
-          next unless num_name_matches == 1
-        else
-          next unless mapped_ids.value? identifier
-        end
-
-        return mapped_ids.invert[identifier]
+        matches = mapped_ids.select { |_id, ident| ident.casecmp? identifier }
+        # If exactly one match, return the id
+        return matches.keys.first if matches.size == 1
       end
 
       nil
@@ -627,8 +613,10 @@ module JSS
     #
     #   # => the Integer id, or nil if no such serial number
     #
-    # Raises a JSS::Ambiguous error if NON_UNIQUE_NAMES is set and
-    #  a :name isn't unique
+    # Raises a JSS::Ambiguous error if there's more than one matching value
+    # for any key, which might be true of names for Computers and Devices
+    #
+    # This is similar to .valid_id, except only one key is searched
     #
     # @param key [Symbol] they key in which to look for the identifier. Must be
     #   a valid lookup key for this subclass.
@@ -645,24 +633,23 @@ module JSS
     # @return [Integer, nil] the id of the matching object, or nil if it
     #   doesn't exist
     #
-    def self.id_for_identifier(key, ident, refresh = false, api: JSS.api)
+    def self.id_for_identifier(key, val, refresh = false, api: JSS.api)
       # refresh if needed
       all(refresh, api: api) if refresh
 
       # get the real key if an alias was used
       key = real_lookup_key key
 
-      return all_ids.include?(ident) ? ident : nil if key == :id
-
-      validate_unique_name(ident) if key == :name
+      # do id's expicitly, they are integers
+      return all_ids.include?(val) ? val : nil if key == :id
 
-      # downcase for speed
-      ident.downcase! if ident.is_a? String
       mapped_ids = map_all_ids_to key, api: api
-      mapped_ids.each { |_k, v| v.downcase! if v.is_a? String }
-      return nil unless mapped_ids.value? ident
+      matches = mapped_ids.select { |_id, map_val| val.casecmp? map_val }
+      raise JSS::AmbiguousError, "Key #{key}: value '#{val}' is not unique for #{self}" if matches.size > 1
 
-      mapped_ids.invert[ident]
+      return nil if matches.size.zero?
+
+      matches.keys.first
     end
 
     # Return true or false if an object of this subclass
@@ -814,52 +801,70 @@ module JSS
       api ||= JSS.api
 
       # refresh the .all list if needed
-      all(:refresh, api: api) if args.delete :refresh
+      if args.delete(:refresh) || searchterm == :random
+        all(:refresh, api: api)
+        just_refreshed = true
+      else
+        just_refreshed = false
+      end
 
       # a random object?
-      if searchterm == :random
-        return new id: all_ids.sample, api: api
-      end
+      return new id: all.sample[:id], api: api if searchterm == :random
 
       # get the lookup key and value, if given
       fetch_key, fetch_val = args.to_a.first
+      fetch_rsrc_key = fetch_rsrc_key(fetch_key)
 
-      if fetch_key
-        validate_unique_name(fetch_val) if fetch_key == :name
+      err_detail = "where #{fetch_key} = #{fetch_val}"
 
-        # does this lookup key have a fetch_rsrc_key?
-        fetch_rsrc_key = fetch_rsrc_key(fetch_key)
-        return new fetch_rsrc: "#{self::RSRC_BASE}/#{fetch_rsrc_key}/#{CGI.escape fetch_val.to_s}", api: api if fetch_rsrc_key
-      end
+      # names should raise an error if more than one exists,
+      # so we always have to do id_for_identifier, which will do so.
+      if fetch_rsrc_key == :name
+        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, api: api
+        fetch_rsrc = id ? "#{self::RSRC_BASE}/name/#{CGI.escape fetch_val.to_s}" : nil
+
+      # if the fetch rsrc key exists, it can be used directly in an endpoint path
+      # so, use it directly, rather than looking up the id first.
+      elsif fetch_rsrc_key
+        fetch_rsrc = "#{self::RSRC_BASE}/#{fetch_rsrc_key}/#{CGI.escape fetch_val.to_s}"
 
-      # if we'ere here, we need to get the id from either the lookup key/val or
-      # the searchterm
-      if fetch_key
-        # it has an OTHER_LOOKUP_KEY but that key doesn't have a fetch_rsrc
-        # so we look in the .map_all_ids_to_* hash for it.
-        id = id_for_identifier fetch_key, fetch_val, api: api
-        err_detail = "where #{fetch_key} = #{fetch_val}"
+      # it has an OTHER_LOOKUP_KEY but that key doesn't have a fetch_rsrc
+      # so we look in the .map_all_ids_to_* hash for it.
+      elsif fetch_key
+        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, api: api
+        fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil
+
+      # no fetch key was given in the args, so try a search term
       elsif searchterm
         id = valid_id searchterm, api: api
+        fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil
         err_detail = "matching #{searchterm}"
+
       else
         raise ArgumentError, 'Missing searchterm or fetch key'
       end
-      raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found #{err_detail}" unless id
 
-      new id: id, api: api
+      begin
+        return new fetch_rsrc: fetch_rsrc, api: api
+      rescue RestClient::NotFound
+        raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found #{err_detail}" unless fetch_rsrc
+      end
     end # fetch
 
     # Make a ruby instance of a not-yet-existing APIObject.
     #
-    # This is the preferred way to create new objects in the JSS.
-    # It's a wrapper for using APIObject.new with the 'id: :new' parameter.
-    # and helps avoid the confusion of using ruby's .new class method for making
-    # ruby instances.
+    # This is how to create new objects in the JSS. A name: must be provided,
+    # and different subclasses can take other named parameters.
     #
     # For retrieving existing objects in the JSS, use {APIObject.fetch}
     #
-    # For actually creating the object in the JSS, see {APIObject#create}
+    # After calling this you'll have a local instance, which will be created
+    # in the JSS when you call #create on it. see {APIObject#create}
+    #
+    # @param name[String] The name of this object, generally must be uniqie
+    #
+    # @param api[JSS::APIConnection] the connection thru which to make this
+    #   object. Defaults to the deault API connection in JSS.api
     #
     # @param args[Hash] The data for creating an object, such as name:
     #  See {APIObject#initialize}
@@ -868,6 +873,9 @@ module JSS
     #
     def self.make(**args)
       validate_not_metaclass(self)
+      unless constants.include?(:CREATABLE)
+        raise JSS::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] ||= JSS.api
@@ -921,9 +929,14 @@ module JSS
           api.delete_rsrc "#{self::RSRC_BASE}/id/#{vid}"
         else
           skipped << vid
-        end # if current_ids include v
+        end # if current_ids include vid
       end # each victim
 
+      # clear any cached all-lists or id-maps for this class
+      # so they'll re-cache as needed
+      api.flushcache self::RSRC_LIST_KEY
+      # all :refresh, api: api
+
       skipped
     end # self.delete
 
@@ -932,17 +945,6 @@ module JSS
       raise JSS::UnsupportedError, 'JSS::APIObject is a metaclass. Do not use it directly' if klass == JSS::APIObject
     end
 
-    # Raise an exception if a name is being used for fetching and it isn't
-    # unique. Case Insensitive
-    def self.validate_unique_name(name, refresh = false)
-      return unless defined? self::NON_UNIQUE_NAMES
-
-      name.downcase!
-      matches = all_names(refresh).map(&:downcase).select { |n| n == name }
-      raise JSS::AmbiguousError, "Name '#{name}' is not unique for #{self}" if matches.size > 1
-    end
-
-
     # Attributes
     #####################################
 
@@ -1024,9 +1026,11 @@ module JSS
     def save
       if @in_jss
         raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
+
         update
       else
         raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
+
         create
       end
     end
@@ -1120,6 +1124,12 @@ module JSS
       @id = nil
       @in_jss = false
       @need_to_update = false
+
+      # clear any cached all-lists or id-maps for this class
+      # so they'll re-cache as needed
+      @api.flushcache self.class::RSRC_LIST_KEY
+      # self.class.all :refresh, api: @api
+
       :deleted
     end # delete
 
@@ -1275,7 +1285,12 @@ module JSS
 
       raise JSS::MissingDataError, "You must provide a :name to create a #{self.class::RSRC_OBJECT_KEY}." unless args[:name]
 
-      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" if self.class.all_names(api: @api).include? args[:name]
+      return if defined? self.class::NON_UNIQUE_NAMES
+
+      matches = self.class.all_names(:refresh, api: @api).select { |n| n.casecmp? args[:name] }
+
+      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" unless matches.empty?
+
     end
 
     # Given initialization args, perform an API lookup for an object.
@@ -1462,6 +1477,7 @@ module JSS
     end
 
     # Meta Programming
+    ####################################################
 
     # Loop through the defined lookup keys and make
     # .all_<key>s methods for each one, with
@@ -1537,6 +1553,7 @@ require 'jss/api_object/computer_invitation'
 require 'jss/api_object/department'
 require 'jss/api_object/distribution_point'
 require 'jss/api_object/ebook'
+require 'jss/api_object/ibeacon'
 require 'jss/api_object/ldap_server'
 require 'jss/api_object/mac_application'
 require 'jss/api_object/mobile_device'

data/lib/jss/api_object/advanced_search.rb

@@ -198,6 +198,18 @@ module JSS
       @id # remember to return the id
     end
 
+    # Wrapper/alias for both create and update
+    def save(get_results = false)
+      if @in_jss
+        raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
+        update get_results
+      else
+        raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
+        create get_results
+      end
+    end
+
+
     # Requery the API for the search results.
     #
     # This can be very slow, so temporarily reset the API timeout to 30 minutes

data/lib/jss/api_object/computer.rb

@@ -1076,13 +1076,13 @@ module JSS
 
     def serial_number=(new_val)
       return nil if new_val == @serial_number
-      @serial_number =  new_val.empty? ? new_val : JSS::Validate.unique_identifier(JSS::Computer, :serial_number, new_val, api: api)
+      @serial_number =  new_val.empty? ? new_val : JSS::Validate.doesnt_already_exist(JSS::Computer, :serial_number, new_val, api: api)
       @need_to_update = true
     end
 
     def udid=(new_val)
       return nil if new_val == @udid
-      @udid = new_val.empty? ? new_val : JSS::Validate.unique_identifier(JSS::Computer, :udid, new_val, api: api)
+      @udid = new_val.empty? ? new_val : JSS::Validate.doesnt_already_exist(JSS::Computer, :udid, new_val, api: api)
       @need_to_update = true
     end
 

data/lib/jss/api_object/creatable.rb

@@ -71,15 +71,21 @@ module JSS
     #
     # @return [Integer] the jss ID of the newly created object
     #
-    def create(api: nil)
-      api ||= @api
+    def create
       raise JSS::UnsupportedError, "Creating or editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless creatable?
+
       raise AlreadyExistsError, "This #{self.class::RSRC_OBJECT_KEY} already exists. Use #update to make changes." if @in_jss
-      api.post_rsrc(rest_rsrc, rest_xml) =~ %r{><id>(\d+)</id><}
+
+      @api.post_rsrc(rest_rsrc, rest_xml) =~ %r{><id>(\d+)</id><}
       @id = Regexp.last_match(1).to_i
       @in_jss = true
       @need_to_update = false
       @rest_rsrc = "#{self.class::RSRC_BASE}/id/#{@id}"
+
+      # clear any caches for this class
+      # so they'll re-cache as needed
+      @api.flushcache self.class::RSRC_LIST_KEY
+
       @id
     end
 

data/lib/jss/api_object/extension_attribute.rb

@@ -180,6 +180,7 @@ module JSS
         raise MissingDataError, 'No popup_choices set for Pop-up Menu input_type.' unless @popup_choices.is_a?(Array) && !@popup_choices.empty?
       end
       super
+      @api.flushcache self.class
     end
 
     # @see JSS::APIObject#delete
@@ -191,6 +192,7 @@ module JSS
       @api.open_timeout = orig_open_timeout + 1800
       begin
         super
+        @api.flushcache self.class
       ensure
         @api.timeout = orig_timeout
         @api.open_timeout = orig_open_timeout
@@ -233,7 +235,7 @@ module JSS
     #
     def data_type=(new_val)
       return nil if @data_type == new_val
-      raise JSS::InvalidDataError, "data_type must be a string, one of: #{DATA_TYPES.join(', ')}" unless DATA_TYPES.include? new_val
+      raise JSS::InvalidDataError, "data_type must be a string, one of: '#{DATA_TYPES.join("', '")}'" unless DATA_TYPES.include? new_val
       @data_type = new_val
       @need_to_update = true
     end #

data/lib/jss/api_object/group.rb

@@ -84,7 +84,7 @@ module JSS
     # groups.
     #
     def self.all_static(refresh = false, api: JSS.api)
-      all(refresh, api: api).select { |g| (g[:is_smart]) }
+      all(refresh, api: api).reject { |g| g[:is_smart] }
     end
 
     # Immediatly add and/or remove members in a static group without
@@ -105,7 +105,7 @@ module JSS
     # @return [void]
     #
     def self.change_membership(group, add_members: [], remove_members: [], api: JSS.api)
-      raise JSS::NoSuchItemError, "No #{self} matching '#{ident}'" unless (group_id = valid_id group, api: api)
+      raise JSS::NoSuchItemError, "No #{self} matching '#{group}'" unless (group_id = valid_id group, api: api)
       raise JSS::UnsupportedError, "Not a static group, can't change membership directly" if map_all_ids_to(:is_smart, api: api)[group_id]
 
       add_members = [add_members].flatten
@@ -210,7 +210,7 @@ module JSS
     #####################################
 
     # When creating a new group in the JSS, you must call .make with a :type key
-    # and a value of :smart or :static, as well as a :name and the :id => :new
+    # and a value of :smart or :static, as well as a :name
     #
     # @see JSS::APIObject
     #
@@ -236,23 +236,61 @@ module JSS
 
     # @see Creatable#create
     #
-    def create(calculate_members: true)
+    # @param calculate_members [Boolan] should the local membership list be
+    #   re-read from the API after the group is created?
+    #
+    # @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
+    #   happens, try again this many times with a 1 second pause between attempts.
+    #
+    def create(calculate_members: true, retries: 10)
       if @is_smart
         raise JSS::MissingDataError, 'No criteria specified for smart group' unless @criteria
       end
       super()
-      refresh_members if calculate_members
+
+      if calculate_members
+        tries = 0
+        while tries < retries
+          begin
+            refresh_members
+            break
+          rescue RestClient::NotFound
+            sleep 1
+            tries += 1
+          end # begin
+        end # while
+      end # if calc members
+
       @id
     end
 
     # @see Updatable#update
     #
-    def update
-      super
-      refresh_members
+    def update(refresh: true)
+      super()
+      refresh_members if refresh
       @id
     end
 
+    # Wrapper/alias for both create and update
+    def save(**params)
+      params[:calculate_members] = true if params[:calculate_members].nil?
+      params[:retries] = 10 if params[:retries].nil?
+      params[:refresh] = true if params[:refresh].nil?
+
+      if @in_jss
+        raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
+
+
+        update refresh: params[:refresh]
+      else
+        raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
+        create calculate_members: params[:calculate_members], retries: params[:retries]
+      end
+    end
+
     # @see APIObject#delete
     #
     def delete
@@ -269,6 +307,7 @@ module JSS
     #
     def criteria=(new_criteria)
       raise InvalidDataError, 'Only smart groups have criteria.' unless @is_smart
+
       super
     end
 

data/lib/jss/api_object/ibeacon.rb

@@ -0,0 +1,198 @@
+### Copyright 2019 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+###
+module JSS
+
+  # Module Variables
+  #####################################
+
+  # Module Methods
+  #####################################
+
+  # Classes
+  #####################################
+
+  # An iBeacon in the JSS.
+  # @see JSS::APIObject
+  #
+  class IBeacon < JSS::APIObject
+
+    # Mix-Ins
+    #####################################
+    include JSS::Creatable
+    include JSS::Updatable
+
+    # Class Methods
+    #####################################
+
+    # Class Constants
+    #####################################
+
+    # The base for REST resources of this class
+    RSRC_BASE = 'ibeacons'.freeze
+
+    # the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :ibeacons
+
+    # The hash key used for the JSON object output.
+    # It's also used in various error messages
+    RSRC_OBJECT_KEY = :ibeacon
+
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 360
+
+    # The major & minor values, if used, must be in this range
+    MAJOR_MINOR_RANGE = 0..65_535.freeze
+
+    # If not used, this is the value for the major and minor
+    MAJOR_MINOR_UNUSED = -1
+
+    # Attributes
+    #####################################
+
+    ### @return [String] the top-level region identifier, a valid UUID
+    attr_reader :uuid
+
+    ### @return [IPAddr] the mid-level region identifier,
+    # an integer within MAJOR_MINOR_RANGE or MAJOR_MINOR_UNUSED
+    attr_reader :major
+
+    ### @return [IPAddr] the low-level region identifier,
+    # an integer within MAJOR_MINOR_RANGE or MAJOR_MINOR_UNUSED
+    attr_reader :minor
+
+    # Constructor
+    # @see JSS::APIObject.initialize
+    #####################################
+    def initialize(args = {})
+      super args
+
+      @uuid = @init_data[:uuid]
+      @major = @init_data[:major]
+      @minor = @init_data[:minor]
+
+      # defaults
+      @major ||= MAJOR_MINOR_UNUSED
+      @minor ||= MAJOR_MINOR_UNUSED
+    end # init
+
+
+    # Public Instance Methods
+    #####################################
+
+    # set the uuid
+    #
+    # @param newval[String] the new uuid
+    #
+    # @return [void]
+    #
+    def uuid=(newval)
+      JSS::Validate.uuid newval
+      @uuid = newval
+      @need_to_update = true
+    end
+
+    # Set the major value to for this iBeacon region.
+    # Use nil or -1 to not use the major value
+    #
+    # @param newval[String] the new value
+    #
+    # @return [void]
+    #
+    def major=(newval)
+      if newval.nil? || newval == MAJOR_MINOR_UNUSED
+        newval ||= MAJOR_MINOR_UNUSED
+      else
+        JSS::Validate.ibeacon_major_minor newval
+      end
+      @major = newval
+      @need_to_update = true
+    end
+
+    # Set the minoe value to for this iBeacon region.
+    # Use nil or -1 to not use the major value
+    #
+    # @param newval[String] the new value
+    #
+    # @return [void]
+    #
+    def minor=(newval)
+      if newval.nil? || newval == MAJOR_MINOR_UNUSED
+        newval ||= MAJOR_MINOR_UNUSED
+      else
+        JSS::Validate.ibeacon_major_minor newval
+      end
+
+      @minor = newval
+      @need_to_update = true
+    end
+
+    # @return is the major identifier being used in this region?
+    def using_major?
+      @major == MAJOR_MINOR_UNUSED
+    end
+
+    # @return is the minor identifier being used in this region?
+    def using_minor?
+      @minor == MAJOR_MINOR_UNUSED
+    end
+
+    # @see Creatable.create
+    def create
+      raise JSS::MissingDataError, 'uuid may not be empty' if @uuid.to_s.empty?
+
+      super
+    end
+
+    # @see Updatable.update
+    def update
+      raise JSS::MissingDataError, 'uuid may not be empty' if @uuid.to_s.empty?
+
+      super
+    end
+
+    # private instance methods
+    ######################
+    private
+
+    # the xml formated data for adding or updating this in the JSS
+    #
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      ns = doc.add_element RSRC_OBJECT_KEY.to_s
+      ns.add_element('name').text = @name
+      ns.add_element('uuid').text = @uuid
+      ns.add_element('major').text = @major.to_s
+      ns.add_element('minor').text = @minor.to_s
+      doc.to_s
+    end # rest_xml
+
+
+  end # class ibeacon
+
+end # module

data/lib/jss/api_object/mdm.rb

@@ -437,6 +437,9 @@ module JSS
       def raw_targets_to_ids(targets, api: JSS.api, expand_groups: true)
         targets = targets.is_a?(Array) ? targets : [targets]
 
+        # flush caches before checking ids and managment
+        api.flushcache self::RSRC_LIST_KEY
+
         # make sure its an array of ids
         targets.map! do |md|
           id = valid_id md, api: api
@@ -453,7 +456,7 @@ module JSS
 
         # make sure all of them are managed, or else the API will raise a 400
         # 'Bad Request' when sending the command to an unmanaged target
-        all_mgd = self.map_all_ids_to(:managed, api: api).select { |_id, mgd| mgd }.keys
+        all_mgd = map_all_ids_to(:managed, api: api).select { |_id, mgd| mgd }.keys
 
         targets.each do |target_id|
           raise JSS::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id

data/lib/jss/api_object/mobile_device.rb

@@ -497,14 +497,14 @@ module JSS
     #
     def serial_number=(new_val)
       return nil if new_val == @serial_number
-      @serial_number =  new_val.empty? ? new_val : JSS::Validate.unique_identifier(self.class, :serial_number, new_val, api: api)
+      @serial_number =  new_val.empty? ? new_val : JSS::Validate.doesnt_already_exist(self.class, :serial_number, new_val, api: api)
       @need_to_update = true
     end
 
     #
     def udid=(new_val)
       return nil if new_val == @udid
-      @udid = new_val.empty? ? new_val : JSS::Validate.unique_identifier(self.class, :udid, new_val, api: api)
+      @udid = new_val.empty? ? new_val : JSS::Validate.doesnt_already_exist(self.class, :udid, new_val, api: api)
       @need_to_update = true
     end
 

data/lib/jss/api_object/patch_policy.rb

@@ -252,9 +252,24 @@ module JSS
     def self.all_for_title(title, api: JSS.api)
       title_id = JSS::PatchTitle.valid_id title
       raise JSS::NoSuchItemError, "No PatchTitle matching '#{title}'" unless title_id
+
       api.get_rsrc("#{RSRC_BY_PATCH_TITLE}#{title_id}")[RSRC_BY_PATCH_TITLE_LIST_KEY]
     end
 
+    # Override APIObject.fetch, since there's no .../patchpolicies/name/... endpoint
+    # @see APIObject#fetch
+    #
+    def self.fetch(searchterm = nil, **args)
+      name_search = args.delete :name
+      if name_search
+        id = valid_id name_search
+        raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found #{err_detail}" unless id
+
+        args[:id] = id
+      end
+      super
+    end # fetch
+
     # Attributes
     ################################
 

data/lib/jss/api_object/updatable.rb

@@ -93,9 +93,15 @@ module JSS
       return nil unless @need_to_update
       raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
       raise JSS::NoSuchItemError, "Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY} in the JSS before updating it." unless @in_jss
+
       @api.put_rsrc @rest_rsrc, rest_xml
       @need_to_update = false
       refresh_icon if self_servable?
+
+      # clear any cached all-lists or id-maps for this class
+      # so they'll re-cache as needed
+      @api.flushcache self.class::RSRC_LIST_KEY
+
       @id
     end # update
 

data/lib/jss/validate.rb

@@ -49,9 +49,13 @@ module JSS
     def self.mac_address(val, msg = nil)
       msg ||= "Not a valid MAC address: '#{val}'"
       raise JSS::InvalidDataError, msg unless val =~ MAC_ADDR_RE
+
       val
     end
 
+    # Segments of a valid IPv4 address are integers in this range.
+    IP_SEGMENT_RANGE = 0..255
+
     # Validate the format and content of an IPv4 address
     #
     # @param val[String] The value to validate
@@ -65,12 +69,14 @@ module JSS
       ok = true
       parts = val.strip.split '.'
       ok = false unless parts.size == 4
-      parts.each { |p| ok = false unless p.jss_integer? && p.to_i < 256 && p.to_i >= 0 }
+      parts.each { |p| ok = false unless p.jss_integer? && IP_SEGMENT_RANGE.include?(p.to_i) }
       raise JSS::InvalidDataError, msg unless ok
+
       val
     end
 
-    # Validate that a value doesn't already exist for a given identifier of a given class
+    # Validate that a value doesn't already exist for a given identifier of a
+    # given class
     #
     # e.g. when klass = JSS::Computer, identifier = :name, and val = 'foo'
     # will raise an error when a computer named 'foo' exists
@@ -89,9 +95,17 @@ module JSS
     #
     # @return [Object] the validated unique value
     #
-    def self.unique_identifier(klass, identifier, val, msg = nil, api: JSS.api)
+    def self.doesnt_already_exist(klass, identifier, val, msg = nil, api: JSS.api)
       msg ||= "A #{klass} already exists with #{identifier} '#{val}'"
       return val unless klass.all(:refresh, api: api).map { |i| i[identifier] }.include? val
+
+      key = klass.real_lookup_key identifier
+
+      # use map_all_ids_to cuz it works with any identifer, even non-existing
+      existing_values = klass.map_all_ids_to( key, api: api).values
+      matches = existing_values.select { |existing_val| existing_val.casecmp? val }
+      return val if matches.empty?
+
       raise JSS::AlreadyExistsError, msg
     end
 
@@ -113,6 +127,7 @@ module JSS
       return bool if JSS::TRUE_FALSE.include? bool
       return true if bool.to_s =~ /^(true|yes)$/i
       return false if bool.to_s =~ /^(false|no)$/i
+
       raise JSS::InvalidDataError, msg
     end
 
@@ -131,6 +146,7 @@ module JSS
       msg ||= 'Value must be an integer'
       val = val.to_i if val.is_a?(String) && val.jss_integer?
       raise JSS::InvalidDataError, msg unless val.is_a? Integer
+
       val
     end
 
@@ -145,6 +161,42 @@ module JSS
     def self.non_empty_string(val, msg = nil)
       msg ||= 'value must be a non-empty String'
       raise JSS::InvalidDataError, msg unless val.is_a?(String) && !val.empty?
+
+      val
+    end
+
+    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.freeze
+
+    # validate that the given value is a valid uuid string
+    #
+    # @param val [Object] the thing to validate
+    #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @return [String] the valid uuid string
+    #
+    def self.uuid(val, msg = nil)
+      msg ||= 'value must be valid uuid'
+      raise JSS::InvalidDataError, msg unless val.is_a?(String) && val =~ UUID_RE
+
+      val
+    end
+
+    # validate that the given value is an integer in the JSS::IBeacon::MAJOR_MINOR_RANGE
+    #
+    # @param val [Object] the thing to validate
+    #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @return [String] the valid integer
+    #
+    def self.ibeacon_major_minor(val, msg = nil)
+      msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
+      val = val.to_i if val.is_a?(String) && val.jss_integer?
+      ok = val.is_a? Integer
+      ok = JSS::IBeacon::MAJOR_MINOR_RANGE.include? val if ok
+      raise JSS::InvalidDataError, msg unless ok
+
       val
     end
 

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of ruby-jss
-  VERSION = '1.1.3'.freeze
+  VERSION = '1.2.0b1'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.2.0b1
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-24 00:00:00.000000000 Z
+date: 2019-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist
@@ -180,6 +180,7 @@ files:
 - lib/jss/api_object/group/computer_group.rb
 - lib/jss/api_object/group/mobile_device_group.rb
 - lib/jss/api_object/group/user_group.rb
+- lib/jss/api_object/ibeacon.rb
 - lib/jss/api_object/ldap_server.rb
 - lib/jss/api_object/locatable.rb
 - lib/jss/api_object/mac_application.rb
@@ -288,12 +289,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: A Ruby interface to the Jamf Pro REST API