ruby-jss 1.4.1 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef0484427943d39089bb11eb73af827c5137d79550c34ea5fdf7ca683c7c69f0
-  data.tar.gz: '09abd63abb133ee6c34aa2fcb9ae8ccc3e11b3248061ee410223bd8f25f5a7ae'
+  metadata.gz: 7c229fe64d5af063db9f075fd9345d34447160817a125fb147f72e4603d56d1c
+  data.tar.gz: a4642b384ae4bd853563928d6c399597404935c5cdce329a3f485e5ad2d92095
 SHA512:
-  metadata.gz: 962236f6ca861fbfa3f706df0d8d977f15fb1436238f7d9c061ae8043c4148b956fc187a9858f9444b8461cc7d707067278e6a9030c676af26febdc565b0cd0f
-  data.tar.gz: 7f7027d207de8ea3fd3d1c010483a9e261d4962857ec48ac6f4df0ba4d38526720ff3700078900e1df2182f191a0aaf7c3284ef3438714e1fbc9118f3aeb03ca
+  metadata.gz: dbabf94f300745834e65c574cc1b9918b03540d81f9c54a004803913452147f63e7eb0df20694ea092c05b31c0700144a55df99bc57d4f9fbbaf3c67dab1d034
+  data.tar.gz: 6aa566e804422b49bdcd258ae08386a080a567e14b1cd47e936c8098a307ca6529ec2da4963f6f801d2586a04cd9edb570e6f101e865d19861213b93ea062128

data/CHANGES.md

@@ -4,6 +4,44 @@ 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.5.1] - 2020-11-16
+
+IMPORTANT: New minimum require ruby version is 2.3.0
+
+Big thanks to @cybertunnel for many enhancements and fixes.
+
+### Added
+
+  - The .all method for subclasses of Jamf::CollectionResource now fully supports server-side paging, sorting and filtering (for endpoints that support RSQL filters). See the docs/comments for Jamf::CollectionResource.all for details
+
+  - JSS::ConfigurationProfile subclasses now have a #payload_content=(new_content) method, which takes an Array of Hashes to replace the PayloadContent of the Payload of the profile. All converstion to an XML plist (which is then embedded into the API XML) is handled automatically. WARNING: This is experimental and can easily break your profile if you aren't careful.
+
+- JSS::Server#update_activation_code method was added
+
+- Group#set_static and #set_smart can convert smart groups to static and static to smart
+
+### Changed
+
+  - Minimum required ruby version is 2.3.0
+
+  - The JSS Module now uses the faraday gem, rather than rest-client, as the underlying REST/HTTP engine for communicating with the Classic API. This brings it in line with the Jamf module which has always used faraday for connecting to the Jamf Pro API. Faraday has fewer dependencies, none of which need to be compiled. This means that installing ruby-jss on a Mac no longer requires the XCode command-line tools.
+
+  - The Jamf module, for accessing the Jamf Pro API, now requires Jamf Pro 10.25 or higher. While still in 'beta', the Jamf Pro API is becoming more stable and in compliance with standards. The Jamf module continues to be updated to work with the modernized endpoints of the JP API. Some related changes:
+    - The ids of JP API collection objects are Strings containing Integers.
+    - Boolean property names no longer start with 'is', tho aliases ending with '?' are still automatically created.
+
+  - Removed dependency on net-ldap, which hasn't been used in a while
+
+  - Removed the redundant JSS::APIConnection instance methods that were just wrappers for various APIObject subclass Class methods, e.g. `JSS.api.valid_id :computers, 'compName'`. Please use the class method directly, e.g. `JSS::Computer.valid_id 'compName'`
+
+### Fixed
+
+  - PatchSource.fetch was totally broken, now fixed
+
+  - Category object's parse_category not properly referencing API object during execution
+
+  - Many small bugs and typos.
+
 ## \[1.4.1] - 2020-10-01
 
 ### Added

data/lib/jamf.rb

@@ -41,9 +41,7 @@ require 'shellwords'
 require 'digest'
 require 'open3'
 
-
 ### Gems
-require 'rest-client'
 require 'plist'
 
 # Used, among other places, in the Connection::APIError class
@@ -113,6 +111,10 @@ module Jamf
   autoload :Immutable, 'jamf/api/mixins/immutable'
   autoload :UnDeletable, 'jamf/api/mixins/undeletable'
   autoload :Abstract, 'jamf/api/mixins/abstract'
+  autoload :Pageable, 'jamf/api/mixins/pageable'
+  autoload :Filterable, 'jamf/api/mixins/filterable'
+  autoload :Sortable, 'jamf/api/mixins/sortable'
+  autoload :BulkDeletable, 'jamf/api/mixins/bulk_deletable'
 
   # Utility modules
   autoload :Validate, 'jamf/validate'
@@ -126,6 +128,7 @@ module Jamf
   autoload :Country, 'jamf/api/json_objects/country'
   autoload :Criterion, 'jamf/api/json_objects/criterion'
   autoload :DeviceEnrollmentDevice, 'jamf/api/json_objects/device_enrollment_device'
+  autoload :DeviceEnrollmentDeviceSyncState, 'jamf/api/json_objects/device_enrollment_device_sync_state'
   autoload :DeviceEnrollmentSyncStatus, 'jamf/api/json_objects/device_enrollment_sync_status'
   autoload :ExtensionAttributeValue, 'jamf/api/json_objects/extension_attribute_value'
   autoload :InstalledApplication, 'jamf/api/json_objects/installed_application'
@@ -135,6 +138,7 @@ module Jamf
   autoload :InstalledProvisioningProfile, 'jamf/api/json_objects/installed_provisioning_profile'
   autoload :InventoryPreloadExtensionAttribute, 'jamf/api/json_objects/inventory_preload_extension_attribute'
   autoload :IosDetails, 'jamf/api/json_objects/ios_details'
+  autoload :Locale, 'jamf/api/json_objects/locale'
   autoload :Location, 'jamf/api/json_objects/location'
   autoload :PrestageLocation, 'jamf/api/json_objects/prestage_location'
   autoload :PrestageSyncStatus, 'jamf/api/json_objects/prestage_sync_status'
@@ -147,16 +151,20 @@ module Jamf
   autoload :PrestagePurchasingData, 'jamf/api/json_objects/prestage_purchasing_data'
   autoload :PrestageScope, 'jamf/api/json_objects/prestage_scope'
   autoload :PrestageAssignment, 'jamf/api/json_objects/prestage_assignment'
+  autoload :TimeZone, 'jamf/api/json_objects/time_zone'
 
   # Subclasses of SingletonResource
   autoload :ClientCheckInSettings, 'jamf/api/resources/singleton_resources/client_checkin_settings'
   autoload :ReEnrollmentSettings, 'jamf/api/resources/singleton_resources/reenrollment_settings'
   autoload :AppStoreCountryCodes, 'jamf/api/resources/singleton_resources/app_store_country_codes'
+  autoload :TimeZones, 'jamf/api/resources/singleton_resources/time_zones'
+  autoload :Locales, 'jamf/api/resources/singleton_resources/locales'
 
   # Subclasses of CollectionResource
   autoload :AdvancedMobileDeviceSearch, 'jamf/api/resources/collection_resources/advanced_mobile_device_search'
   autoload :AdvancedUserSearch, 'jamf/api/resources/collection_resources/advanced_user_search'
   autoload :Attachment, 'jamf/api/resources/collection_resources/attachment'
+  autoload :Category, 'jamf/api/resources/collection_resources/category'
   autoload :Building, 'jamf/api/resources/collection_resources/building'
   autoload :Computer, 'jamf/api/resources/collection_resources/computer'
   autoload :ComputerPrestage, 'jamf/api/resources/collection_resources/computer_prestage'
@@ -168,7 +176,6 @@ module Jamf
   autoload :MobileDevicePrestage, 'jamf/api/resources/collection_resources/mobile_device_prestage'
   autoload :Site, 'jamf/api/resources/collection_resources/site'
   autoload :Script, 'jamf/api/resources/collection_resources/script'
-  autoload :TimeZone, 'jamf/api/resources/collection_resources/time_zone'
 
   # other classes used as attributes inside the resource classes
   autoload :IPAddress, 'jamf/api/attribute_classes/ip_address'

data/lib/jamf/api/abstract_classes/collection_resource.rb

@@ -32,8 +32,9 @@ module Jamf
   #
   # Collection resources have more than one resource within them, and those
   # can (usually) be created and deleted as well as fetched and updated.
-  # The entire collection (or a part of it) can also be fetched as an Array.
-  # When the whole collection is fetched, the result is cached for future use.
+  # The entire collection (or a part of it) can also be retrieved as an Array.
+  # When the whole collection is retrieved, the result may be cached for future
+  # use.
   #
   # # Subclassing
   #
@@ -63,6 +64,10 @@ module Jamf
   class CollectionResource < Jamf::Resource
 
     extend Jamf::Abstract
+    extend Jamf::Pageable
+    extend Jamf::Sortable
+    extend Jamf::Filterable
+
     include Comparable
 
     # Public Class Methods
@@ -74,63 +79,195 @@ module Jamf
       self::OBJECT_MODEL.select { |_attr, deets| deets[:identifier] }.keys
     end
 
-    # The Collection members Array for this class, retrieved from
-    # the RSRC_PATH as Parsed JSON, but not instantiated into instances
-    # unless instantiate: is truthy.
+    def self.count(cnx: Jamf.cnx)
+      collection_count(rsrc_path, cnx: Jamf.cnx)
+    end
+
+
+    # Get all instances of a CollectionResource, possibly limited by a filter.
+    #
+    # When called without specifying paged:, sort:, or filter: (see below)
+    # this method will return a single Array of all items of its
+    # CollectionResouce subclass, in the server's default sort order. This
+    # full list is cached for future use (see Caching, below)
+    #
+    # However, the Array can be sorted by the server, filtered to contain only
+    # matching objects, or 'paged', i.e. retrieved in successive Arrays of a
+    # certain size.
+    #
+    # Sorting, filtering, and paging can all be used at the same time.
+    #
+    # #### Server-side Sorting
+    #
+    # Sorting criteria can be provided in the String format 'property:direction',
+    # where direction is 'asc' or 'desc' E.g.
+    #   "username:asc"
+    #
+    # Multiple properties are supported, either as separate strings in an Array,
+    # or a single string, comma separated. E.g.
+    #
+    #    "username:asc,timestamp:desc"
+    # is the same as
+    #    ["username:asc", "timestamp:desc"]
+    #
+    # which will sort by username alphabetically, and within each username,
+    # sort by timestamp newest first.
+    #
+    # Please see the JamfPro API documentation for the resource for details
+    # about available sorting properties and default sorting criteria
+    #
+    # #### Filtering
+    #
+    # Some CollectionResouces support RSQL filters to limit which objects
+    # are returned. These filters can be applied using the filter: parameter,
+    # in which case this `all` method will return `all that match the filter`.
+    #
+    # If the resource doesn't support filters, the filter parameter is ignored.
+    #
+    # Please see the JamfPro API documentation for the resource to see if
+    # filters are supported, and a list of available fields.
+    #
+    # #### Paging
+    #
+    # To reduce server load and local memory usage, you can request the results
+    # in 'pages', i.e. successivly retrieved Arrays, using the paged: and page_size:
+    # parameters.
+    #
+    # When paged: is truthy, the call to `all` returns the first group of objects
+    # containing however many are specified by page_size: The default page size
+    # is 100,  the minimum is 1, and the maximum is 2000.
+    #
+    # Once you have made a paged call to `all`, you must use the `next_page_of_all`
+    # method to get the next Array of objects. That method merely repeats the last
+    # request made by `all` after incrementing the page number by 1.
+    # When `next_page_of_all` returns an empty array, you have retrieved all
+    # availalble objects.
+    #
+    # `next_page_of_all` always reflects the last _paged_ call to `all`. Any
+    # subsequent paged call to `all` will reset the paging process for that
+    # collection class, and any unfinished previous paged calls to `all` will
+    # be forgotten
+    #
+    # #### Instantiation
+    #
+    # All data from the API comes from the server in JSON format, mostly as
+    # JSON 'objects', which are the equivalent of ruby Hashes.
+    # When fetching an individual instance of an object from the API, ruby-jss
+    # uses the JSON Hash to create the ruby object, i.e. to 'instantiate' it as
+    # an instance of its class. Doing this for many objects can slow things down.
+    #
+    # Because of this, the 'all' method defaults to returning an Array of the
+    # minimally-processed JSON Hashes it gets from the API. If you can get your
+    # desired data from these Hashes, it's far more efficient to do so.
+    #
+    # However sometimes you really need the fully instantiated ruby objects for
+    # all of them - especially if you're using filters and not actually processing
+    # all items of the class.  In such cases you can pass a truthy value to the
+    # instantiate: parameter, and the Array will contain fully instantiated
+    # ruby objects, not Hashes of API data.
     #
-    # E.g. for {Jamf::Settings::Building}, this would be the Array of Hashes
-    # returned by GETing the resource .../settings/obj/building
+    # #### Caching
     #
-    # This Array is cached in the {Jamf::Connection} instance used to
-    # retrieve it, and future calls to .all will return the cached Array
-    # unless refresh is truthy.
+    # When called without specifying paged:, sort:, or filter:
+    # this method will return a single Array of all items of its
+    # CollectionResouce subclass, in the server's default sort order.
     #
-    # TODO: Investigate https://www.rubydoc.info/github/mloughran/api_cache
+    # This Array is cached in ruby-jss, and future calls to this method without
+    # those parameters will return the cached Array. Use `refresh: true` to
+    # re-request that Array from the server. Note that the cache is of the raw
+    # JSON Hash data. Using 'instantiate:' will still be slower as each item in
+    # the cache is instantiated. See 'Instantiation' below.
     #
-    # @param refresh[Boolean] re-read the data from the API?
+    # Some other methods, e.g. .all_names, will generate or use this cached Array
+    # to derive their values.
     #
-    # @param cnx[Jamf::Connection] an API connection to use for the query.
-    #   Defaults to the corrently active connection. See {Jamf::Connection}
+    # If any of the parameters paged:, sort:, or filter: are used, an API
+    # request is made every time, and no caches are used or stored.
     #
-    # @param instantiate[Boolean] The Array contains instances of this class
-    #   rather than the JSON Hashes from the API.
+    #######
     #
-    # @return  [Array<Object>] An Array of all objects of this class in the JSS.
+    # @param sort [String, Array<String>] Server-side sorting criteria in the format:
+    #   property:direction, where direction is 'asc' or 'desc'. Multiple
+    #   properties are supported, either as separate strings in an Array, or
+    #   a single string, comma separated.
     #
-    def self.all(refresh = false, cnx: Jamf.cnx, instantiate: false)
+    # @param filter [String] An RSQL filter string. Not all collection resources
+    #   currently support filters, and if they don't, this will be ignored.
+    #
+    # @param paged [Boolean] Defaults to false. Returns only the first page of
+    #   `page_size` objects. Use {.next_page_of_all} to retrieve each successive
+    #   page.
+    #
+    # @param page_size [Integer] How many items are returned per page? Minimum
+    #   is 1, maximum is 2000, default is 100. Ignored unless paged: is truthy.
+    #   Note: the final page may contain fewer items than the page_size
+    #
+    # @param refresh [Boolean] re-fetch and re-cache the full list of all instances.
+    #   Ignored if paged:, page_size:, sort:, filter: or instantiate: are used.
+    #
+    # @param instantiate [Boolean] Defaults to false. Should the items in the
+    #   returned Array(s) be ruby instances of the CollectionObject subclass, or
+    #   plain Hashes of data as returned by the API?
+    #
+    # @param cnx [Jamf::Connection] The API connection to use, default: Jamf.cnx
+    #
+    # @return [Array<Hash, Jamf::CollectionResource>] The objects in the collection
+    #
+    def self.all(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, instantiate: false, cnx: Jamf.cnx)
       validate_not_abstract
-      cnx.collection_cache[self] = nil if refresh
-      if cnx.collection_cache[self]
-        return cnx.collection_cache[self] unless instantiate
 
-        return cnx.collection_cache[self].map { |m| new m }
-      end
+      # use the cache if not paging, filtering or sorting
+      return cached_all(refresh, instantiate, cnx) if !paged && !sort && !filter
 
-      # TODO:  make sure all collection resources use this format
-      # for paging. Also -ask Jamf about a  url that returns
-      # ALL objects in one query, regardless of number.
-      page = 0
-      raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
-      results = raw[:results]
-
-      until results.size >= raw[:totalCount]
-        page += 1
-        raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
-        results += raw[:results]
-      end
+      # we are sorting, filtering or paging
+      sort = parse_collection_sort(sort)
+      filter = parse_collection_filter(filter)
 
+      result =
+        if paged
+          first_collection_page(rsrc_path, page_size, sort, filter, cnx)
+        else
+          fetch_all_collection_pages(rsrc_path, sort, filter, cnx)
+        end
+      instantiate ? result.map { |m| new m } : result
+    end
 
-      cnx.collection_cache[self] = results
+    # PRIVATE
+    # return the cached/cachable version of .all, possibly instantiated
+    #
+    # @param refresh [Boolean] refetch the cache from the server?
+    #
+    # @param instantiate [Boolean] Return an array of instantiated objects, vs
+    #   JSON hashes?
+    #
+    # @param cnx [Jamf::Connection] The Connection to use
+    #
+    # @return [Array<Hash,Object>] All the objects in the collection
+    #
+    def self.cached_all(refresh, instantiate, cnx)
+      cnx.collection_cache[self] = nil if refresh
+      unless cnx.collection_cache[self]
+        sort = nil
+        filter = nil
+        cnx.collection_cache[self] = fetch_all_collection_pages(rsrc_path, sort, filter, cnx)
+      end
+      instantiate ? cnx.collection_cache[self].map { |m| new m } : cnx.collection_cache[self]
+    end
+    private_class_method :cached_all
 
-      return cnx.collection_cache[self] unless instantiate
 
-      cnx.collection_cache[self].map { |m| new m }
+    # Fetch the next page of a paged .all request. See
+    # {Jamf::Pagable.next_collection_page}
+    def self.next_page_of_all
+      next_collection_page
     end
 
     # An array of the ids for all collection members. According to the
     # specs ALL collection resources must have an ID, which is used in the
     # resource path.
     #
+    # NOTE: This method uses the cached version of .all
+    #
     # @param refresh (see .all)
     #
     # @param cnx (see .all)
@@ -138,14 +275,14 @@ module Jamf
     # @return [Array<Integer>]
     #
     def self.all_ids(refresh = false, cnx: Jamf.cnx)
-      all(refresh, cnx: cnx).map { |m|  m[:id] }
+      all(refresh: refresh, cnx: cnx).map { |m| m[:id] }
     end
 
-    # rubocop:disable Naming/UncommunicativeMethodParamName
-
     # A Hash of all members of this collection where the keys are some
     # identifier and values are any other attribute.
     #
+    # NOTE: This method uses the cached version of .all
+    #
     # @param ident [Symbol] An identifier of this Class, used as the key
     #   for the mapping Hash. Aliases are acceptable, e.g. :sn for :serialNumber
     #
@@ -166,76 +303,149 @@ module Jamf
       real_to = attr_key_for_alias to
       raise Jamf::NoSuchItemError, "No attribute #{to} for class #{self}" unless self::OBJECT_MODEL.key? real_to
 
-      ident = real_ident
-      to = real_to
-      list = all refresh, cnx: cnx
-      to_class = self::OBJECT_MODEL[to][:class]
+      list = all refresh: refresh, cnx: cnx
+      to_class = self::OBJECT_MODEL[real_to][:class]
       mapped = list.map do |i|
         [
-          i[ident],
-          to_class.is_a?(Symbol) ? i[to] : to_class.new(i[to])
+          i[real_ident],
+          to_class.is_a?(Symbol) ? i[real_to] : to_class.new(i[real_to])
         ]
       end # do i
       mapped.to_h
     end
-    # rubocop:enable Naming/UncommunicativeMethodParamName
 
-    # Given any identfier value for this collection, return the id of the
-    # object that has such an identifier.
+    # Given a key (identifier) and value for this collection, return the raw data
+    # Hash (the JSON object) for the matching API object or nil if there's no
+    # match for the given value.
     #
-    # Return nil if there's no match for the given value.
+    # In general you should use this if the form:
     #
-    # If you know the value is a certain identifier, e.g. a serialNumber,
-    # then you can specify the identifier for a faster search:
+    #    raw_data identifier: value
     #
-    #   valid_id serialNumber: 'AB12DE34' # => Int or nil
+    # where identifier is one of the available identifiers for this class
+    # like id:, name:, serialNumber: etc.
     #
-    # If you don't know wich identifier you have, just pass the value and
-    # all identifiers are searched
+    # In the unlikely event that you dont know which identifier a value is for
+    # or want to be able to take any of them without specifying, then
+    # you can use
     #
-    #   valid_id 'AB12DE34' # => Int or nil
-    #   valid_id 'SomeComputerName' # => Int or nil
+    #   raw_data some_value
     #
-    # When the value is a string, the seach is case-insensitive
+    # If some_value is an integer or a string containing an integer, it
+    # is assumed to be an :id otherwise all the available identifers
+    # are searched, in the order you see them when you call <class>.identifiers
     #
-    # TODO: When 'Searchability' is more dialed in via the searchable
-    # mixin, which implements enpoints like 'POST /v1/search-mobile-devices'
-    # then use that before using the 'all' list.
+    # If no matching object is found, nil is returned.
     #
-    # @param value [Object] A value to search for as an identifier.
+    # Everything except :id is treated as a case-insensitive String
     #
-    # @param refresh[Boolean] Reload the list data from the API
+    # @param value [String, Integer] The identifier value to search fors
     #
-    # @param ident: [Symbol] Restrict the search to this identifier.
-    #  E.g. if :serialNumber, then the value must be
-    #  a known serial number, it is not checked against other identifiers
+    # @param key: [Symbol] The identifier being used for the search.
+    #  E.g. if :serialNumber, then the value must be a known serial number, it
+    #  is not checked against other identifiers. Defaults to :id
     #
     # @param cnx: (see .all)
     #
-    # @return [Object, nil] the primary identifier of the matching object,
+    # @return [Hash, nil] the basic dataset of the matching object,
     #   or nil if it doesn't exist
     #
-    def self.valid_id(value = nil, refresh: true, cnx: Jamf.cnx, **ident_hash)
-      unless ident_hash.empty?
-        ident, value = ident_hash.first
-        return id_from_other_ident ident, value, refresh, cnx: cnx
-      end
+    def self.raw_data(value = nil, cnx: Jamf.cnx, **ident_and_val)
+      validate_not_abstract
+
+      # given a value with no ident key
+      return raw_data_by_value_only(value, cnx: Jamf.cnx) if value
+
+      # if we're here, we should know our ident key and value
+      ident, value = ident_and_val.first
+      raise ArgumentError, 'Required parameter "identifier: value", where identifier is id:, name: etc.' unless ident && value
+
+      return raw_data_by_id(value, cnx: cnx) if ident == :id
+      return unless identifiers.include? ident
+
+      raw_data_by_other_identifier(ident, value, cnx: cnx)
+    end
+
+    # Match the given value in all possibly identifiers
+    def self.raw_data_by_value_only(value, cnx: Jamf.cnx)
+      return raw_data_by_id(value, cnx: cnx) if value.to_s.j_integer?
 
-      # check the id itself first
-      return value if all_ids(refresh, cnx: cnx).include? value
+      identifiers.each do |ident|
+        next if ident == :id
 
-      idents = identifiers - [:id]
-      val_is_str = value.is_a? String
+        id = raw_data_by_other_identifier(ident, value, cnx: cnx)
+        return id if id
+      end # identifiers.each
+      return
+    end
+    private_class_method :raw_data_by_value_only
+
+    # get the basic dataset by id, with optional
+    # request params to get more than basic data
+    def self.raw_data_by_id(id, request_params: nil, cnx: Jamf.cnx)
+      cnx.get "#{rsrc_path}/#{id}#{request_params}"
+    rescue => e
+      return if e.httpStatus == 404
+
+      raise e
+    end
+    private_class_method :raw_data_by_id
+
+    # Given an indentier attr. key, and a value,
+    # return the id where that ident has that value, or nil
+    #
+    def self.raw_data_by_other_identifier(identifier, value, refresh: false, cnx: Jamf.cnx)
+      # if the API supports filtering by this identifier, just use that
+      return all(filter: "#{identifier}=='#{value}'", paged: true, page_size: 1, cnx: cnx).first if self::OBJECT_MODEL[identifier][:filter_key]
 
-      idents.each do |ident|
-        match = all(refresh, cnx: cnx).select do |m|
-          val_is_str ? m[ident].to_s.casecmp?(value) : m[ident] == value
-        end.first
-        return match[:id] if match
-      end # identifiers.each do |ident|
+      # otherwise we have to loop thru all the objects looking for the value
+      all(refresh: refresh, cnx: cnx).each { |data| return data if data[identifier].to_s.casecmp? value.to_s }
 
       nil
     end
+    private_class_method :raw_data_by_other_identifier
+
+    # Look up the valid ID for any arbitrary identifier.
+    # In general you should use this if the form:
+    #
+    #    valid_id identifier: value
+    #
+    # where identifier is one of the available identifiers for this class
+    # like id:, name:, serialNumber: etc.
+    #
+    # In the unlikely event that you dont know which identifier a value is for
+    # or want to be able to take any of them without specifying, then
+    # you can use
+    #
+    #   valid_id some_value
+    #
+    # If some_value is an integer or a string containing an integer, it
+    # is assumed to be an id: otherwise all the available identifers
+    # are searched, in the order you see them when you call <class>.identifiers
+    #
+    # If no matching object is found, nil is returned.
+    #
+    # WARNING: Do not use this to look up ids for getting the
+    # raw API data for an object. Since this calls .raw_data
+    # itself, it is redundant to use .valid_id to get an id
+    # to then pass on to .raw_data
+    # Use raw_data directly like this:
+    #    data = raw_data(ident: val)
+    #
+    #
+    # @param value [String,Integer] A value for an arbitrary identifier
+    #
+    # @param cnx [Jamf::Connection] The connection to use. default: Jamf.cnx
+    #
+    # @param ident_and_val [Hash{Symbol: String}] The identifier key and the value
+    #   to look for in that key, e.g. name: 'foo' or serialNumber: 'ASDFGH'
+    #
+    # @return [String, nil] The id (integer-in-string) of the object, or nil
+    #    if no match found
+    #
+    def self.valid_id(value = nil, cnx: Jamf.cnx, **ident_and_val)
+      raw_data(value, cnx: cnx, **ident_and_val)&.dig(:id)
+    end
 
     # Bu default, subclasses are creatable, i.e. new instances can be created
     # with .create, and added to the JSS with .save
@@ -253,15 +463,19 @@ module Jamf
       validate_not_abstract
       raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless creatable?
 
+      # Which connection to use
       cnx = params.delete :cnx
       cnx ||= Jamf.cnx
 
       params.delete :id # no such animal when .creating
-
       params.keys.each do |param|
         raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
 
-        params[param] = validate_attr param, params[param], cnx: cnx
+        if params[param].is_a? Array
+          params[param].map! { |val| validate_attr param, val, cnx: cnx }
+        else
+          params[param] = validate_attr param, params[param], cnx: cnx
+        end
       end
 
       params[:creating_from_create] = true
@@ -273,41 +487,27 @@ module Jamf
     # To create new members to be added to the JSS, use
     # {Jamf::CollectionResource.create}
     #
-    # If you know the specific identifier attribute you're looking up, e.g.
+    # You must know the specific identifier attribute you're looking up, e.g.
     # :id or :name or :udid, (or an aliase thereof) then you can specify it like
     # `.fetch name: 'somename'`, or `.fetch udid: 'someudid'`
     #
-    # If you don't know if (or don't want to type it) you can just use
-    # `.fetch 'somename'`, or `.fetch 'someudid'` and all identifiers will be
-    # searched for a match.
-    #
-    # @param ident_value[Object] A value for any identifier for this subclass.
-    #  All identifier attributes will be searched for a match.
-    #
     # @param cnx[Jamf::Connection] the connection to use to fetch the object
     #
-    # @param ident_hash[Hash] an identifier attribute key and a search value
+    # @param ident_and_val[Hash] an identifier attribute key and a search value
     #
     # @return [CollectionResource] The ruby-instance of a Jamf object
     #
-    def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
+    def self.fetch(random = nil, cnx: Jamf.cnx, **ident_and_val)
       validate_not_abstract
-
-      id =
-        if ident_value == :random
-          all_ids.sample
-        elsif ident_value
-          valid_id ident_value, cnx: cnx
-        elsif ident_hash.empty?
-          nil
-        else
-          ident, lookup_value = ident_hash.first
-          valid_id ident => lookup_value, cnx: cnx
+      ident, value = ident_and_val.first
+      data =
+        if random
+          all.sample
+        elsif ident && value
+          raw_data(cnx: cnx, **ident_and_val)
         end
+      raise Jamf::NoSuchItemError, "No matching #{self}" unless data
 
-      raise Jamf::NoSuchItemError, "No matching #{self}" unless id
-
-      data = cnx.get "#{rsrc_path}/#{id}"
       new data, cnx: cnx
     end # fetch
 
@@ -318,36 +518,31 @@ module Jamf
       true
     end
 
-    # Delete one or more objects by identifier
-    # Any valid identifier for the class can be used (id, name, udid, etc)
-    # Identifiers can be provided as an array or as separate parameters
-    #
-    # e.g. .delete [1,3, 34, 4]
-    # or .delete 'myComputer', 'that-computer', 'OtherComputer'
+    # Delete one or more objects by id
     #
-    # @param idents[Array<integer>, Integer]
+    # @param ids [Array<String,Integer>] The ids to delete
     #
-    # @param cnx[Jamf::Connection]
+    # @param cnx [Jamf::Connection] The connection to use, default: Jamf.cnx
     #
-    # @return [Array] the identifiers that were not found, so couldn't be deleted
+    # @return [Array<Jamf::Connection::APIError::ErrorInfo] Info about any ids
+    #   that failed to be deleted.
     #
-    def self.delete(*idents, cnx: Jamf.cnx)
+    def self.delete(*ids, cnx: Jamf.cnx)
       raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
 
-      idents.flatten!
-      no_valid_ids = []
+      return bulk_delete(ids, cnx: Jamf.cnx) if ancestors.include? Jamf::BulkDeletable
 
-      idents.map do |ident|
-        id = valid_id ident
-        no_valid_ids << ident unless id
-        id
-      end
-      idents.compact!
-
-      # TODO: some rsrcs have a 'bulk delete' version...
-      idents.each { |id| cnx.delete "#{rsrc_path}/#{id}" }
+      errs = []
+      ids.each do |id_to_delete|
+        begin
+          cnx.delete "#{rsrc_path}/#{id_to_delete}"
+        rescue Jamf::Connection::APIError => e
+          raise e unless e.httpStatus == 404
 
-      no_valid_ids
+          errs += e.errors
+        end # begin
+      end # ids.each
+      errs
     end
 
     # Private Class Methods
@@ -359,7 +554,7 @@ module Jamf
       list_method_name = "all_#{attr_name}s"
 
       define_singleton_method(list_method_name) do |refresh = false, cnx: Jamf.cnx|
-        all_list = all(refresh, cnx: cnx)
+        all_list = all(refresh: refresh, cnx: cnx)
         if attr_def[:class].is_a? Symbol
           all_list.map { |i| i[attr_name] }.uniq
         else
@@ -378,24 +573,6 @@ module Jamf
     end # create_list_methods
     private_class_method :create_list_methods
 
-    # Given an indentier attr. key, and a value,
-    # return the id where that ident has that value, or nil
-    #
-    def self.id_from_other_ident(ident, value, refresh = true, cnx: Jamf.cnx)
-      raise ArgumentError, "Unknown identifier '#{ident}' for #{self}" unless identifiers.include? ident
-
-      # check the id itself first
-      return value if ident == :id && all_ids(refresh, cnx: cnx).include?(value)
-
-      # all ident values => ids
-      ident_map = map_all(ident, to: :id, cnx: cnx, refresh: refresh)
-
-      # case-insensitivity for string values
-      value = ident_map.keys.j_ci_fetch(value) if value.is_a? String
-
-      ident_map[value]
-    end
-    private_class_method :id_from_other_ident
 
     # Instance Methods
     #####################################
@@ -406,11 +583,13 @@ module Jamf
 
     def rsrc_path
       return unless exist?
+
       "#{self.class.rsrc_path}/#{@id}"
     end
 
     def delete
       raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless self.class.deletable?
+
       @cnx.delete rsrc_path
     end