ruby-jss 1.3.3 → 1.6.0b1

data/lib/jss/validate.rb

@@ -111,8 +111,8 @@ module JSS
 
     # Confirm that the given value is a boolean value, accepting
     # strings and symbols and returning real booleans as needed
-    # Accepts: true, false, 'true', 'false', :true, :false, 'yes', 'no', :yes,
-    # or :no (all Strings and Symbols are case insensitive)
+    # Accepts: true, false, 'true', 'false', 'yes', 'no', 't','f', 'y', or 'n'
+    # as strings or symbols, case insensitive
     #
     # TODO: use this throughout ruby-jss
     #
@@ -123,11 +123,11 @@ module JSS
     # @return [Boolean] the valid boolean
     #
     def self.boolean(bool, msg = nil)
-      msg ||= 'Value must be boolean true or false'
       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
+      return true if bool.to_s =~ /^(t(rue)?|y(es)?)$/i
+      return false if bool.to_s =~ /^(f(alse)?|no?)$/i
 
+      msg ||= 'Value must be boolean true or false, or an equivalent string or symbol'
       raise JSS::InvalidDataError, msg
     end
 
@@ -176,10 +176,10 @@ module JSS
     # @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
+      return val if val.is_a?(String) && val =~ UUID_RE
 
-      val
+      msg ||= 'value must be valid uuid'
+      raise JSS::InvalidDataError, msg
     end
 
     # validate that the given value is an integer in the JSS::IBeacon::MAJOR_MINOR_RANGE
@@ -191,13 +191,56 @@ module JSS
     # @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
+      return val if ok
+
+      msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
       raise JSS::InvalidDataError, msg unless ok
+    end
 
-      val
+    # validate a country name or code from JSS::APP_STORE_COUNTRY_CODES
+    # returning the validated code, or raising an error
+    #
+    # @param country[String] The country name or code
+    #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @return [String] the valid two-letter country code
+    #
+    def self.app_store_country_code(country, msg = nil)
+      country = country.to_s.upcase
+      return country if JSS::APP_STORE_COUNTRY_CODES.value? country
+
+      JSS::APP_STORE_COUNTRY_CODES.each do |name, code|
+        return code if name.upcase == country
+      end
+
+      msg ||= 'Unknown country name or code. See JSS::APP_STORE_COUNTRY_CODES or JSS.country_code_match(str)'
+      raise JSS::InvalidDataError, msg
+    end
+
+    # validate an email address - must match the RegEx /^\S+@\S+\.\S+$/
+    # i.e.:
+    #  1 or more non-whitespace chars, followed by
+    #  an @ character, followed by
+    #  1 or more non-whitespace chars, followed by
+    #  a dot, followed by
+    #  1 or more non-whitespace chars
+    #
+    # @param email[String] The email address
+    #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @return [String] the validly formatted email address
+    #
+    def self.email_address(email, msg = nil)
+      msg ||= "'#{email}' is not formatted as a valid email address"
+      email = email.to_s
+      return email if email =~ /^\S+@\S+\.\S+$/
+
+      raise JSS::InvalidDataError, msg
     end
 
   end # module validate

data/lib/jss/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.6.0b1
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,22 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-07 00:00:00.000000000 Z
+date: 2021-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: plist
+  name: CFPropertyList
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: ruby-mysql
   requirement: !ruby/object:Gem::Requirement
@@ -46,39 +46,45 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.9.12
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
-    - - "<"
+        version: 1.0.0
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 1.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
-    - - "<"
+        version: 1.0.0
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
-  name: net-ldap
+  name: faraday_middleware
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: 1.0.0
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
   name: immutable-struct
   requirement: !ruby/object:Gem::Requirement
@@ -120,11 +126,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 description: |2
-      The ruby-jss gem provides the JSS module, a framework for interacting with the REST API
-      of the Jamf Software Server (JSS), the core of Jamf Pro, an enterprise/education
-      tool for managing Apple devices, from Jamf Software LLC.
-      JSS API objects are implemented as Ruby classes, and interact with each oher to
-      allow simpler automation of Jamf-related tasks. For details see the README file."
+      The ruby-jss gem provides native ruby access to the REST APIs of Jamf Pro,
+      an enterprise/education tool for managing Apple devices, from jamf.com.
+      The JSS module provides access to the 'Classic' API, while the Jamf module
+      provides access to the more modern 'Jamf Pro' API. Jamf Pro objects are
+      implemented as classes and, within each module, can interact with each other.
+      The underlying data transfer using JSON or XML is handled automatically
+      under the hood to allow simpler, intuitive automation of Jamf-related Tasks.
 email: ruby-jss@pixar.com
 executables:
 - cgrouper
@@ -147,82 +155,56 @@ files:
 - bin/netseg-update
 - data/ruby-jss.conf.example
 - lib/jamf.rb
-- lib/jamf/api/abstract_classes/advanced_search.rb
-- lib/jamf/api/abstract_classes/collection_resource.rb
-- lib/jamf/api/abstract_classes/generic_reference.rb
-- lib/jamf/api/abstract_classes/json_object.rb
-- lib/jamf/api/abstract_classes/prestage.rb
-- lib/jamf/api/abstract_classes/prestage_skip_setup_items.rb
-- lib/jamf/api/abstract_classes/resource.rb
-- lib/jamf/api/abstract_classes/singleton_resource.rb
 - lib/jamf/api/attribute_classes/ip_address.rb
 - lib/jamf/api/attribute_classes/timestamp.rb
+- lib/jamf/api/base_classes/collection_resource.rb
+- lib/jamf/api/base_classes/json_object.rb
+- lib/jamf/api/base_classes/prestage.rb
+- lib/jamf/api/base_classes/resource.rb
+- lib/jamf/api/base_classes/singleton_resource.rb
 - lib/jamf/api/connection.rb
 - lib/jamf/api/connection/api_error.rb
 - lib/jamf/api/connection/api_error_styleguide.rb
 - lib/jamf/api/connection/token.rb
-- lib/jamf/api/json_objects/account_prefs.rb
-- lib/jamf/api/json_objects/android_details.rb
-- lib/jamf/api/json_objects/appletv_details.rb
-- lib/jamf/api/json_objects/attachment.rb
-- lib/jamf/api/json_objects/cellular_network.rb
 - lib/jamf/api/json_objects/change_log_entry.rb
-- lib/jamf/api/json_objects/computer_prestage_skip_setup_items.rb
 - lib/jamf/api/json_objects/country.rb
-- lib/jamf/api/json_objects/criterion.rb
 - lib/jamf/api/json_objects/device_enrollment_device.rb
+- lib/jamf/api/json_objects/device_enrollment_device_sync_state.rb
 - lib/jamf/api/json_objects/device_enrollment_sync_status.rb
-- lib/jamf/api/json_objects/extension_attribute_value.rb
-- lib/jamf/api/json_objects/installed_application.rb
-- lib/jamf/api/json_objects/installed_certificate.rb
-- lib/jamf/api/json_objects/installed_configuration_profile.rb
-- lib/jamf/api/json_objects/installed_ebook.rb
-- lib/jamf/api/json_objects/installed_provisioning_profile.rb
 - lib/jamf/api/json_objects/inventory_preload_extension_attribute.rb
-- lib/jamf/api/json_objects/ios_details.rb
-- lib/jamf/api/json_objects/location.rb
+- lib/jamf/api/json_objects/locale.rb
 - lib/jamf/api/json_objects/md_prestage_name.rb
 - lib/jamf/api/json_objects/md_prestage_names.rb
 - lib/jamf/api/json_objects/md_prestage_skip_setup_items.rb
-- lib/jamf/api/json_objects/mobile_device_details.rb
-- lib/jamf/api/json_objects/mobile_device_security.rb
 - lib/jamf/api/json_objects/prestage_assignment.rb
 - lib/jamf/api/json_objects/prestage_location.rb
 - lib/jamf/api/json_objects/prestage_purchasing_data.rb
 - lib/jamf/api/json_objects/prestage_scope.rb
 - lib/jamf/api/json_objects/prestage_sync_status.rb
-- lib/jamf/api/json_objects/purchasing_data.rb
-- lib/jamf/api/mixins/abstract.rb
+- lib/jamf/api/json_objects/time_zone.rb
+- lib/jamf/api/mixins/base_class.rb
 - lib/jamf/api/mixins/bulk_deletable.rb
 - lib/jamf/api/mixins/change_log.rb
 - lib/jamf/api/mixins/extendable.rb
+- lib/jamf/api/mixins/filterable.rb
 - lib/jamf/api/mixins/immutable.rb
-- lib/jamf/api/mixins/locatable.rb
 - lib/jamf/api/mixins/lockable.rb
-- lib/jamf/api/mixins/referable.rb
+- lib/jamf/api/mixins/pageable.rb
 - lib/jamf/api/mixins/searchable.rb
+- lib/jamf/api/mixins/sortable.rb
 - lib/jamf/api/mixins/uncreatable.rb
 - lib/jamf/api/mixins/undeletable.rb
-- lib/jamf/api/resources/collection_resources/account.rb
-- lib/jamf/api/resources/collection_resources/advanced_mobile_device_search.rb
-- lib/jamf/api/resources/collection_resources/advanced_user_search.rb
 - lib/jamf/api/resources/collection_resources/building.rb
 - lib/jamf/api/resources/collection_resources/category.rb
-- lib/jamf/api/resources/collection_resources/computer.rb
 - lib/jamf/api/resources/collection_resources/computer_prestage.rb
 - lib/jamf/api/resources/collection_resources/department.rb
 - lib/jamf/api/resources/collection_resources/device_enrollment.rb
-- lib/jamf/api/resources/collection_resources/extension_attribute.rb
 - lib/jamf/api/resources/collection_resources/inventory_preload_record.rb
-- lib/jamf/api/resources/collection_resources/mobile_device.rb
 - lib/jamf/api/resources/collection_resources/mobile_device_prestage.rb
 - lib/jamf/api/resources/collection_resources/script.rb
-- lib/jamf/api/resources/collection_resources/site.rb
-- lib/jamf/api/resources/collection_resources/time_zone.rb
 - lib/jamf/api/resources/singleton_resources/app_store_country_codes.rb
-- lib/jamf/api/resources/singleton_resources/authorization.rb
-- lib/jamf/api/resources/singleton_resources/client_checkin_settings.rb
-- lib/jamf/api/resources/singleton_resources/reenrollment_settings.rb
+- lib/jamf/api/resources/singleton_resources/locales.rb
+- lib/jamf/api/resources/singleton_resources/time_zones.rb
 - lib/jamf/client.rb
 - lib/jamf/client/jamf_binary.rb
 - lib/jamf/client/jamf_helper.rb
@@ -264,6 +246,7 @@ files:
 - lib/jss/api_object/advanced_search/advanced_computer_search.rb
 - lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb
 - lib/jss/api_object/advanced_search/advanced_user_search.rb
+- lib/jss/api_object/app_store_country_codes.rb
 - lib/jss/api_object/building.rb
 - lib/jss/api_object/categorizable.rb
 - lib/jss/api_object/category.rb
@@ -346,6 +329,7 @@ files:
 - lib/jss/api_object/updatable.rb
 - lib/jss/api_object/uploadable.rb
 - lib/jss/api_object/user.rb
+- lib/jss/api_object/vpp_account.rb
 - lib/jss/api_object/vppable.rb
 - lib/jss/api_object/webhook.rb
 - lib/jss/client.rb
@@ -405,15 +389,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: A Ruby interface to the Jamf Pro REST API
+summary: A Ruby interface to the Jamf Pro REST APIs
 test_files: []

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

@@ -1,86 +0,0 @@
-# Copyright 2020 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.
-#
-#
-
-# The Module
-module Jamf
-
-  # Classes
-  #####################################
-
-  # A building defined in the JSS
-  class AdvancedSearch < Jamf::CollectionResource
-
-    extend Jamf::Abstract
-
-    # Constants
-    #####################################
-
-    # Object Model / Attributes
-    # See APIObject class documentation for details
-    # of how the OBJECT_MODEL hash works.
-    #####################################
-    OBJECT_MODEL = {
-
-      # @!attribute [r] id
-      #   @return [Integer]
-      id: {
-        class: :integer,
-        identifier: :primary,
-        readonly: true
-      },
-
-      # @!attribute name
-      #   @return [String]
-      name: {
-        class: :string,
-        identifier: true
-      },
-
-      # @!attribute criteria
-      #   @return [Array<Jamf::Criterion>]
-      criteria: {
-        class: Jamf::Criterion,
-        multi: true,
-        required: true
-      },
-
-      # @!attribute displayFields
-      #   @return [Array<String>]
-      displayFields: {
-        class: :string,
-        multi: true
-      },
-
-      # @!attribute site
-      #   @return [Jamf::Site::Reference]
-      site: {
-        class: Jamf::Site::Reference
-      }
-
-    }.freeze
-
-  end # class
-
-end # module

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

@@ -1,433 +0,0 @@
-# Copyright 2020 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.
-#
-#
-
-# The module
-module Jamf
-
-  # A Collection Resource in Jamf Pro
-  #
-  # See {Jamf::Resource} for general info about API resources.
-  #
-  # 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.
-  #
-  # # Subclassing
-  #
-  # ## Creatability, & Deletability
-  #
-  # Sometimes the API doesn't support creation of new members of the collection.
-  # If that's the case, just extend the subclass with Jamf::UnCreatable
-  # and the '.create' class method will raise an error.
-  #
-  # Similarly for deletion of members: if the API doesn't have a way to delete
-  # them, extend the subclass with Jamf::UnDeletable
-  #
-  # See also Jamf::JSONObject, which talks about extending subclasses
-  # with Jamf::Immutable
-  #
-  # ## Bulk Deletion
-  #
-  # Some collection resources have a resource for bulk deletion, passing in
-  # a JSON array of ids to delete.
-  #
-  # If so, just define a BULK_DELETE_RSRC, and the .delete class method
-  # will use it, rather than making multiple calls to delete individual
-  # items. See Jamf::Category::BULK_DELETE_RSRC for an example
-  #
-  # @abstract
-  #
-  class CollectionResource < Jamf::Resource
-
-    extend Jamf::Abstract
-    include Comparable
-
-    # Public Class Methods
-    #####################################
-
-    # @return [Array<Symbol>] the attribute names that are marked as identifiers
-    #
-    def self.identifiers
-      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.
-    #
-    # E.g. for {Jamf::Settings::Building}, this would be the Array of Hashes
-    # returned by GETing the resource .../settings/obj/building
-    #
-    # 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.
-    #
-    # TODO: Investigate https://www.rubydoc.info/github/mloughran/api_cache
-    #
-    # @param refresh[Boolean] re-read the data from the API?
-    #
-    # @param cnx[Jamf::Connection] an API connection to use for the query.
-    #   Defaults to the corrently active connection. See {Jamf::Connection}
-    #
-    # @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.
-    #
-    def self.all(refresh = false, cnx: Jamf.cnx, instantiate: false)
-      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
-
-      # 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
-
-
-      cnx.collection_cache[self] = results
-
-      return cnx.collection_cache[self] unless instantiate
-
-      cnx.collection_cache[self].map { |m| new m }
-    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.
-    #
-    # @param refresh (see .all)
-    #
-    # @param cnx (see .all)
-    #
-    # @return [Array<Integer>]
-    #
-    def self.all_ids(refresh = false, cnx: Jamf.cnx)
-      all(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.
-    #
-    # @param ident [Symbol] An identifier of this Class, used as the key
-    #   for the mapping Hash. Aliases are acceptable, e.g. :sn for :serialNumber
-    #
-    # @param to [Symbol] The attribute to which the ident will be mapped.
-    #   Aliases are acceptable, e.g. :name for :displayName
-    #
-    # @param refresh (see .all)
-    #
-    # @param cnx (see .all)
-    #
-    # @return [Hash {Symbol: Object}] A Hash of identifier mapped to attribute
-    #
-    def self.map_all(ident, to:, cnx: Jamf.cnx, refresh: false)
-      real_ident = attr_key_for_alias ident
-      raise Jamf::InvalidDataError, "No identifier #{ident} for class #{self}" unless
-      identifiers.include? real_ident
-
-      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]
-      mapped = list.map do |i|
-        [
-          i[ident],
-          to_class.is_a?(Symbol) ? i[to] : to_class.new(i[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.
-    #
-    # Return nil if there's no match for the given value.
-    #
-    # If you know the value is a certain identifier, e.g. a serialNumber,
-    # then you can specify the identifier for a faster search:
-    #
-    #   valid_id serialNumber: 'AB12DE34' # => Int or nil
-    #
-    # If you don't know wich identifier you have, just pass the value and
-    # all identifiers are searched
-    #
-    #   valid_id 'AB12DE34' # => Int or nil
-    #   valid_id 'SomeComputerName' # => Int or nil
-    #
-    # When the value is a string, the seach is case-insensitive
-    #
-    # 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.
-    #
-    # @param value [Object] A value to search for as an identifier.
-    #
-    # @param refresh[Boolean] Reload the list data from the API
-    #
-    # @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 cnx: (see .all)
-    #
-    # @return [Object, nil] the primary identifier 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
-
-      # check the id itself first
-      return value if all_ids(refresh, cnx: cnx).include? value
-
-      idents = identifiers - [:id]
-      val_is_str = value.is_a? String
-
-      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|
-
-      nil
-    end
-
-    # Bu default, subclasses are creatable, i.e. new instances can be created
-    # with .create, and added to the JSS with .save
-    # If a subclass is NOT creatble for any reason, just add
-    #   extend Jamf::UnCreatable
-    # and this method will return false
-    #
-    # @return [Boolean]
-    def self.creatable?
-      true
-    end
-
-    # Make a new thing to be added to the API
-    def self.create(**params)
-      validate_not_abstract
-      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless creatable?
-
-      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
-      end
-
-      params[:creating_from_create] = true
-      new params, cnx: cnx
-    end
-
-    # Retrieve a member of a CollectionResource from the API
-    #
-    # 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.
-    # :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
-    #
-    # @return [CollectionResource] The ruby-instance of a Jamf object
-    #
-    def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
-      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
-        end
-
-      raise Jamf::NoSuchItemError, "No matching #{self}" unless id
-
-      data = cnx.get "#{rsrc_path}/#{id}"
-      new data, cnx: cnx
-    end # fetch
-
-    # By default, CollectionResource subclass instances are deletable.
-    # If not, just extend the subclass with Jamf::UnDeletable, and this
-    # will return false, and .delete & #delete will raise errors
-    def self.deletable?
-      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'
-    #
-    # @param idents[Array<integer>, Integer]
-    #
-    # @param cnx[Jamf::Connection]
-    #
-    # @return [Array] the identifiers that were not found, so couldn't be deleted
-    #
-    def self.delete(*idents, cnx: Jamf.cnx)
-      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
-
-      idents.flatten!
-      no_valid_ids = []
-
-      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}" }
-
-      no_valid_ids
-    end
-
-    # Private Class Methods
-    #####################################
-
-    # TODO: better pluralizing?
-    #
-    def self.create_list_methods(attr_name, attr_def)
-      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)
-        if attr_def[:class].is_a? Symbol
-          all_list.map { |i| i[attr_name] }.uniq
-        else
-          all_list.map { |i| attr_def[:class].new i[attr_name] }
-        end
-      end # define_singleton_method
-
-      return unless attr_def[:aliases]
-
-      # aliases - TODO: is there a more elegant way?
-      attr_def[:aliases].each do |a|
-        define_singleton_method("all_#{a}s") do |refresh = false, cnx: Jamf.cnx|
-          send list_method_name, refresh, cnx: cnx
-        end # define_singleton_method
-      end # each alias
-    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
-    #####################################
-
-    def exist?
-      !@id.nil?
-    end
-
-    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
-
-    # Two collection resource objects are the same if their id's are the same
-    def <=>(other)
-      id <=> other.id
-    end
-
-    # Private Instance Methods
-    ############################################
-    private
-
-    def create_in_jamf
-      result = @cnx.post self.class.rsrc_path, to_jamf
-      @id = result[:id]
-    end
-
-  end # class CollectionResource
-
-end # module JAMF