ruby-jss 1.3.3 → 1.6.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee61895968b4dc50815f33bdd50cd54c1a1fcad700243f4be3cded694c11f745
-  data.tar.gz: a7a3ce9847874fa7c26c859f6fa26e5a8802b60f42c300f347e2c40b5c38d949
+  metadata.gz: db33099b85c8a28905abb4885931b4782f169604fdda26458f0def90d9cec4cb
+  data.tar.gz: f004c3aa0aaed1934ccdf98dcce510af7f7c54e399d48692cccc6d9cffef011f
 SHA512:
-  metadata.gz: f95b9d7f49983c9899a18b7e1edb6130250e402a5284e65a9ae64829176d2c3f5fe3d35584cf6dcee85b7486e1a037c8a5ae3ef58b72d169f4ac05cebb5d8858
-  data.tar.gz: 1b5131ec5bec8b940c4daf1403f9595a4749b0b5d36cfc7bf07a2aca0adbee2446ff44dfe078e8e1651f5fa25ed6725d763ec0f5798d06ec16d70b57ea466b86
+  metadata.gz: 8ceb6d36bade8f595556f4c6208b318187bb37f228ae183d8204190f82129c3eaeb3580cfc56277d45d16e84d6889c9220c7a6b2dc02c91c689b9246355280f1
+  data.tar.gz: afa31ca7c07c083b0ee1c255153cdfc02c423e72bdcb4421035b8debe87a365c232d049932441a1583671a5552d4519a1307c8f18ca8e236114a79e1d0c8f3e4

data/CHANGES.md

@@ -4,6 +4,148 @@ 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.6.0] - 2021-05-??
+
+### Fixed
+
+  - Creating JSS::User's no longer requires a valid LDAP server. Many thanks to @aaron-mmt for filing and fixing this issue!
+
+  - HTTP 409 errors are handled more appropriately, and should report the actual error message from the server, e.g. 'Duplicate Primary MAC Address'
+
+### Changed
+
+  - ruby-jss no longer uses the 'plist' gem due to a remote code execution security issue when using `Plist.parse_xml`. Plists are now handled by the CFPropertyList gem.  The existing wrapper method `JSS.parse_plist` bas been updated to use the new gem, and a new wrapper method has been added to convert ruby data to XML plist: `JSS.xml_plist_from(data)`. All internal references to methods from the insecure 'plist' gem have been replaced with calls to those wrapper methods.
+
+  Many many thanks to actae0n of Blacksun Hackers Club for reporting this security issue and providing examples of how it could be exploited.
+
+  - In preparation for the removal of the 'runScript' command in the jamf binary, JSS::Script no longer uses it within the 'run' instance method. Instead, it just does what the jamf binary did: It creates a private temp folder, writes the script to disk in that temp folder, executes the script with any given params, then deletes the folder, returning the exit status and output from the script.
+
+  - Jamf::Script#run now takes parameters in the named params `p4:` through `p11:` for consistency with other parts of ruby-jss.
+
+  - Since Jamf Scripts can no longer be stored in a distribution point, which according to Jamf has been the case for a while, all code for dealing with them that way has been removed.
+
+  - JSS::NetworkSegment#include? now uses Range#cover? under the hood, rather than Range#include?, which can take a very very long time with large segments.
+
+  - JSS.expand_min_os has been updated to handle Apple's new version numbers for macOS. This method takes a string like '>=10.14.3' and expands it into a large array of greater OS versions and is used by the 'os_limitations' method of Packages and Scripts.  For any range of versions that includes Big Sur, both '11.x.x' and '10.16' as included in the output, to catch machines that may have SYSTEM_VERSION_COMPAT set in their env.
+
+
+## \[1.5.3] - 2020-12-28
+
+### Fixed
+
+  - Classic API connections were not setting their default timeouts properly when first connected. This was causing an error in Policy#flush_logs
+
+## \[1.5.2] - 2020-12-21
+
+### Added
+
+  - JSS::Policy#flush_logs can now be called as a class method JSS::Policy.flush_logs, passing in the policy names or ids, without instantiating the policy
+
+  - Both the class and instance 'flush_logs' methods for JSS::Policy take a named parameter 'computers:' which is an array of the computer identifiers for which the policy should be flushed.
+
+  - JSS::Computer instances now have a 'flush_policy_logs' method which is a wrapper for calling JSS::Policy.flush_logs for just that computer
+
+  - JSS::ConfigurationProfile: #update/#save now takes boolean param redeploy_to_all: which defaults to false. The default means redeploy only to newly assigned machines in scope. Setting this to true will push the profile out to all machines in scope, even if they already have the profile.
+
+### Changed
+
+  - JSS.expand_min_os, used to expand strings like '>=10.14.5' into comma-separated versions to be used in Package and Script os_limitations, has been updated to handle Big Sur being both 10.16 and 11.0, and for future OSes to be 12.x, 13.x etc.
+  NOTE: If you've used this feature in the past, you might want to look at your package and script seetings and update them, since they will refer to OSes 10.17 and higher.
+
+  - JSS::APIConnection: initialize @object_list_cache as an empty hash. This provides more useful error messages when forgetting to pass non-default connection objects, and the default one is unused.
+
+### Fixed
+
+  - JSS::Scopable::Scope#remove_target and #remove_limitation didn't always remove the item.
+
+  - JSS::Scopable::Scope: when calling the API for any reason, we now pass in the .api connection of the container. Not doing so when using a non-default connection object would cause problems.
+
+
+## \[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
+
+  - Support for JP API connections to https://tryitout.jamfcloud.com/, the open API test server provided by Jamf. It uses internal tokens, so the /auth endpoint is disabled. Now as with the Classic API, `Jamf::Connection.connect`  will accpt any name & password when connecting to that host.
+
+## \[1.4.0] - 2020-09-14
+
+### Added
+
+  - Class JSS::VPPAccount, implementing the 'vppacconts' endpoint.
+
+  - Constant JSS::APP_STORE_COUNTRY_CODES, a Hash with keys being the official country names used by the App Store, and values being the two-letter codes for those names. This static Hash is derived from a Jamf Pro API end point, and will be updated as needed. These codes are used by JSS::VPPAccount
+
+  - Module Method JSS.country_code_match(str) whic allows you to filter the JSS::APP_STORE_COUNTRY_CODES Hash to only those key-value pairs that include the given string.
+
+  - Mixin Class Method VPPable.all_vpp_device_assignable, returns a Hash of Hashes showing the total, used, and remaining licenses for all members of the target class that are VPP-assignable by device.
+
+  - Scopable::Scope#in_scope?(machine) Given a JSS::Computer or MobileDevice, or an identifier for one, it is in the scope? WARNING: For scopes that include Jamf Users or User Groups as targets or exclusions, this method may return an incorrect value. See the discussion in the comments/documentation for the Scopable::Scope class under `IMPORTANT - Users & User Groups in Targets and Exclusions`
+
+  - Scopable::Scope#scoped_machines returns a Hash of ids=>names for all machines in this scope. WARNING:  This must instantiate all machines in the target class. It will still be slow, at least the first time for each target class. On the upside, the instantiated machines will be cached, so generating this list for other scopes with the same target class will be much much faster. In tests, with 1600 Computers in the JSS, it took about 7 minutes the first time, but less than 1 second after caching.
+  See also the warning for #in_scope? above, which applies here as well.
+
+  - JSS::Policy objects support 'Policy Retry' via the getter/setter methods #retry_event, #retry_attempts, and #notify_failed_retries. You can only set these values if the #frequency is :once_per_computer. To turn off policy-retry, either set the retry_event to :none, or set the retry_attempts to 0
+
+### Changed
+
+  - Prettier XML for JSS::APIObject#ppx
+
+  - Improved JSS::Validate.boolean. Accepts: true, false, 'true', 'false', 'yes', 'no', 't','f', 'y', or 'n' as Strings or Symbols, case insensitive
+
+  - The JSS::MacApplication class is more fully implemented
+
+  - JSS::Scopable::Scope now uses the word 'targets' consistently to match the UI's 'Targets' tab.  The previous word 'inclusions' still works as before.
+
+  - When using the Jamf module to access the Jamf Pro API, the minumum JamfPro version is now 10.23.0. WARNING: Like the Jamf Pro API itself, the Jamf module that accesses it is in beta and may have breaking changes at any time.
+
+### Fixed
+
+  - JSS::ExtensionAttribute: when used as a display field in an AdvancedSearch, the name of the EA in the search result Hash comes from the API as a String (turned into a Symbol) that is the EA name with colons removed and spaces & dashes turned to underscores. Previously ruby-jss didn't remove the colons
+
+  - Used an XML workaround for the common classic API bug where an XML array comes as a single-item JSON hash. This time in the JSS::User class's user_groups method.
+
+  - The Jamf Pro API endpoints for /v1/device-enrollment changed to /v1/device-enrollments and /v1/device-enrollment/sync/<id> changed to /v1/device-enrollments/<id>/syncs.  /v1/devive-enrollments/syncs.
+
+  - The Jamf Pro API endpoint for bulk-deleting Departments changed from 'delete-departments' to 'delete-multiple'
+
 ## \[1.3.3] - 2020-08-07
 
 ### Fixed

data/THANKS.md

@@ -1,6 +1,7 @@
 # With Thanks To...
 
+* Everyone who contributes to this project
 * Pixar Systems Management
-* The Pixar Mac Team
+* The Apple @ Pixar team
 * JAMF Folks
-* Alex
+* Alex

data/lib/jamf.rb

@@ -41,10 +41,7 @@ require 'shellwords'
 require 'digest'
 require 'open3'
 
-
 ### Gems
-require 'rest-client'
-require 'plist'
 
 # Used, among other places, in the Connection::APIError class
 require 'immutable-struct'
@@ -88,19 +85,14 @@ module Jamf
   # AUTOLOADING
   ##################################
 
-  # Top-level API Abstract Classes
-  autoload :JSONObject, 'jamf/api/abstract_classes/json_object'
-  autoload :Resource, 'jamf/api/abstract_classes/resource'
-  autoload :SingletonResource, 'jamf/api/abstract_classes/singleton_resource'
-  autoload :CollectionResource, 'jamf/api/abstract_classes/collection_resource'
-
-  # Abstract Classes used for JSONObject subclasses
-  autoload :AdvancedSearch, 'jamf/api/abstract_classes/advanced_search'
-  autoload :Prestage, 'jamf/api/abstract_classes/prestage'
-  autoload :PrestageSkipSetupItems, 'jamf/api/abstract_classes/prestage_skip_setup_items'
+  # Top-level API Base Classes
+  autoload :JSONObject, 'jamf/api/base_classes/json_object'
+  autoload :Resource, 'jamf/api/base_classes/resource'
+  autoload :SingletonResource, 'jamf/api/base_classes/singleton_resource'
+  autoload :CollectionResource, 'jamf/api/base_classes/collection_resource'
 
-  # Abstract Classes not used for JSONObject subclasses
-  autoload :GenericReference, 'jamf/api/abstract_classes/generic_reference'
+  # Base Classes used for JSONObject subclasses
+  autoload :Prestage, 'jamf/api/base_classes/prestage'
 
   # MixIn Modules
   autoload :ChangeLog, 'jamf/api/mixins/change_log'
@@ -112,7 +104,11 @@ module Jamf
   autoload :UnCreatable, 'jamf/api/mixins/uncreatable'
   autoload :Immutable, 'jamf/api/mixins/immutable'
   autoload :UnDeletable, 'jamf/api/mixins/undeletable'
-  autoload :Abstract, 'jamf/api/mixins/abstract'
+  autoload :BaseClass, 'jamf/api/mixins/base_class'
+  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 +122,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 +132,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 +145,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 +170,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/base_classes/collection_resource.rb

@@ -0,0 +1,613 @@
+# 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 retrieved as an Array.
+  # When the whole collection is retrieved, the result may be 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::BaseClass
+    extend Jamf::Pageable
+    extend Jamf::Sortable
+    extend Jamf::Filterable
+
+    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
+
+    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.
+    #
+    # #### Caching
+    #
+    # 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.
+    #
+    # 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' above.
+    #
+    # Some other class methods, e.g. .all_names, will generate or use this cached
+    # Array to derive their values.
+    #
+    # 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 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.
+    #
+    # @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)
+      stop_if_base_class
+
+      # use the cache if not paging, filtering or sorting
+      return cached_all(refresh, instantiate, cnx) if !paged && !sort && !filter
+
+      # 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
+
+    # 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
+
+
+    # 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)
+    #
+    # @return [Array<Integer>]
+    #
+    def self.all_ids(refresh = false, cnx: Jamf.cnx)
+      all(refresh: refresh, cnx: cnx).map { |m| m[:id] }
+    end
+
+    # 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
+    #
+    # @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
+
+      list = all refresh: refresh, cnx: cnx
+      to_class = self::OBJECT_MODEL[real_to][:class]
+      mapped = list.map do |i|
+        [
+          i[real_ident],
+          to_class.is_a?(Symbol) ? i[real_to] : to_class.new(i[real_to])
+        ]
+      end # do i
+      mapped.to_h
+    end
+
+    # 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.
+    #
+    # In general you should use this if the form:
+    #
+    #    raw_data 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
+    #
+    #   raw_data 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.
+    #
+    # Everything except :id is treated as a case-insensitive String
+    #
+    # @param value [String, Integer] The identifier value to search fors
+    #
+    # @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 [Hash, nil] the basic dataset of the matching object,
+    #   or nil if it doesn't exist
+    #
+    def self.raw_data(value = nil, cnx: Jamf.cnx, **ident_and_val)
+      stop_if_base_class
+
+      # 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?
+
+      identifiers.each do |ident|
+        next if ident == :id
+
+        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]
+
+      # 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
+    # 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)
+      stop_if_base_class
+
+      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
+
+        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
+      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}
+    #
+    # 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'`
+    #
+    # @param cnx[Jamf::Connection] the connection to use to fetch the object
+    #
+    # @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(random = nil, cnx: Jamf.cnx, **ident_and_val)
+      stop_if_base_class
+      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
+
+      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 id
+    #
+    # @param ids [Array<String,Integer>] The ids to delete
+    #
+    # @param cnx [Jamf::Connection] The connection to use, default: Jamf.cnx
+    #
+    # @return [Array<Jamf::Connection::APIError::ErrorInfo] Info about any ids
+    #   that failed to be deleted.
+    #
+    def self.delete(*ids, cnx: Jamf.cnx)
+      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
+
+      return bulk_delete(ids, cnx: Jamf.cnx) if ancestors.include? Jamf::BulkDeletable
+
+      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
+
+          errs += e.errors
+        end # begin
+      end # ids.each
+      errs
+    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: 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
+
+
+    # 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