ruby-jss 1.2.10 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0734256ff4d9e553418ff9e0189e85cbb455751e682af0278dfff3f85f9a6070
-  data.tar.gz: 40fde852a9d6f4cc22a804b0240038bdb17d319e1d51edaa8c974ad50d05861d
+  metadata.gz: 609ac9ae5ba3ddf1c4c8392acda8d1f1f0bba99e119da2781bd1e8d841a294f5
+  data.tar.gz: 28be9609494e02d11e863e5a64d80c82d866650efd599967400e434d157633ba
 SHA512:
-  metadata.gz: 721bc4ef63c7c1114a66bb772a609c4589879977e65922eb008dacf478ea17cc09a78e367e4a8297b46139b9d08f5d16fa6ffa7e0516af6c7ccc571ab37e39da
-  data.tar.gz: 0d8788ff29178d488fc11da8fa4c77c3ca5b40c8a770979cc7bf11bb8ab727f43315e2632ed74c8ae9685d79142e2536e1239624c236ba218fc2de5c70adddd4
+  metadata.gz: f57b6c5c4b127688a6b9fd190a7927e1d1c6332061d1126b23d03b2d39566898fd5a0876ac73e801f6f9824cb45e149d13d6a4e97154b5c08f199ac593e74cdc
+  data.tar.gz: 1086564724dd9398f1bf540df6a092c90045d9226a78ff1eeade1fc6af4442b566fca2fea896f3e0a25aa62a60d568cc43331c5adb89c5929d53a3bcdf063419

data/CHANGES.md

@@ -4,6 +4,210 @@ 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.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
+  - Regression where JSS::Package#required_processor= wouldn't take 'x86'
+
+## \[1.3.2] - 2020-07-31
+Many thanks to @cybertunnel for adding a huge amount of code to get JSS::Policy fully implimented, as well as other fixes and updates!
+
+### Added
+  - new class JSS::DockItem
+  - new classes JSS::DirectoryBinding and JSS::DirectoryBindingType
+  - new class JSS::Printer
+  - new class JSS::DiskEncryptionConfiguration
+  - JSS::Policy:
+    - getters and setters for `#user_message_start` and `#user_message_end`
+    - `#set_management_account` and `#verify_management_password`
+    - `#add_dock_item` and `#remove_dock_item`
+    - `#directory_bindings`, `#add_directory_binding` and `#remove_directory_binding`
+    - `#add_printer` and `#remove_printer`
+    - `#reissue_key`, `#apply_encryption_configuration`, and `#remove_encryption_configuration`
+
+
+### Changed
+  - JSS::Package:
+    - no longer issues a warning when changing the file_name of a package
+    - Updated the CPU type string from 'x86' to 'Intel/x86'
+    - Methods which used to always use the master distribution point now accept a parameter `dist_point: dp` where dp is the name or id of a fileshare distribution point. If not specified, it still defaults to the Master Distribution Point.  This is needed because if the Cloud Distribution Point is the master, there is no access to it via the Classic API, and any use of DistributionPoint.master_distribution_point will raise an error.
+
+## \[1.3.1] - 2020-06-21
+
+### Changed
+
+  - JSS::MobileDeviceApplication when using PrettyPrint (pp) in irb, no longer shows the base64 data for the ipa file.
+
+  - JSS::DistributionPoint.my_distribution_point and .master_distribution_point now have options for dealing with the Cloud Distribution Point (which is not available in the classic API) being the master.
+
+### Fixed
+
+  - JSS::NetworkSegment.distribution_point=  now takes nil or an empty string to unset the dist point.
+
+## \[1.3.0] - 2020-06-05
+
+### Added
+
+  - JSS::NetworkSegment.network_ranges_as_integers method, Similar to NetworkSegment.network_ranges, but the ranges are of Integers, not IPAddr instances. This makes for *MUCH* faster range calculations, needed to implement improvements to NetworkSegment.network_segment_for_ip
+
+  - JSS::Package.all_filenames_by, returns a Hash of all distribution point filenames for all packages, keyed by either the package id, or the package name. NOTE: as with JSS::Package.all_filenames, this method must instantiate all JSS::Package objects, so it will be slow.
+
+### Changed
+
+  - JSS.expand_min_os now expands to macOS 10.30.x, which should hold us for a while
+
+  - JSS::NetworkSegment.network_segment_for_ip and .my_network_segment are no longer deprecated, but now return an integer NetSeg id (or nil). The plural forms of those methods still return an Array of ids for all the matching network segments.
+
+  - The logic for JSS::NetworkSegment.network_segment_for_ip (and .my_network_segment) now matches how the Jamf server does it:  when you IP address is in more than one Network Segment, Jamf uses the smallest/narrowest one (the one containing fewest IP addresses). If more than one of your Network Segments are that same width, the one with the lowest starting IP address is used.
+
+  - In some networking situations (e.g. Split-tunnel VPN with multiple active network ports) the JSS::APIObject.delete method will raise a 404 NotFound error, seemingly because the object was already deleted but a second http DELETE is sent (I think). We now just rescue and ignore that error, since the fact that it's not found means it was indeed deleted.
+
+### Fixed
+
+  - A copy/paste bug in Jamf::Prestage.serials_for_prestage
+
+## \[1.2.15] - 2020-04-30
+
+### Fixed
+
+  - USER_CONF_FILE is always a pathname, never nil
+
+  - issues with Array#j_ci_* methods related to removing safe navigation
+
+## \[1.2.13] - 2020-04-29
+
+### Fixed
+
+  - Ruby 2.6 needs parens in more places than 2.3, apparently
+
+## \[1.2.12] - 2020-04-29
+
+### Added
+
+  - Backport of `#dig` for Arrays, Hashes and OpenStructs, for compatibiliy with older rubiesd (for a while longer anyway). Gratefully borrowed from https://github.com/Invoca/ruby_dig
+
+### Changed
+
+  - Removed all safe navigation operators (`&.`) for compatibility with older rubies (for a while longer anyway)
+
+
+## \[1.2.11] - 2020-04-26
+
+### Fixed
+
+  - Bug in Package#install that prevented installs from 'alt_download_url'.
+
 ## \[1.2.10] - 2020-04-25
 
 ### Added
@@ -55,7 +259,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Classic API (JSS module)
   - Sitable objects now recognize the string "None" as meaning no site is assigned. Thanks @cybertunnel for this fix!
+
   - Scopable::Scope now deals with some bugs in the API regarding Jamf & LDAP users & user groups in targets, limitations, & exclusions. Please see the documentation/comments for the class in the file or the online documentation. Thanks @cybertunnel again!
+
   - Criteriable::Criteria can now be empty - containing no criterion objects. When criteriable objects are created (such as Advanced Searches) the default JSS::Criteriable::Criteria object has no criteria.  To remove all criteria, use `criteria.clear`, `criteria = nil`, or `criteria = JSS::Criteriable::Criteria.new` and then save. Once again, thanks to @cybertunnel for finding this.
 
 - Jamf Pro API (Jamf module)
@@ -99,7 +305,8 @@ Note that the `last_inventory_update` value does NOT indicate such communication
 
 - All APIObject Subclasses (Policy, Computer, MobileDevice, ComputerGroup, etc..) now have `get_raw`, `post_raw` & `put_raw` class methods, which are simpler wrappers for APIConnection#get_rsrc, #post_rsrc, and #put_rsrc.
   - `get_raw`  takes an object's id, and returns the 'raw' JSON (parsed into a ruby Hash with symbolized keys) or a REXML::Document (from which you'll probably want to use the `root` element). If you pass `as_string: true` you'll get the un-parsed JSON or XML string directly from the API
-  This can be useful when you need to retrieve the full object, to get some data not available in the summary-list, but instantiating the full ruby class is too slow.
+  This can be useful when you need to retrieve the full object, to get some data not available in the summary-list, but instantiating the full ruby class is too slow
+
   - `post_raw` & `put_raw` can send raw XML to the API without instantiating objects. In some cases, where you're making simple changes to simple XML, this can be faster than fetching a full instance and the re-saving it.
   WARNING You must create or acquire the XML to be sent, and no validation will be performed on it. It must be a String of XML, or something that returns such a string with #to_s, such as a REXML::Document, or a REXML::Element.
 

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
@@ -88,19 +86,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 +105,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 +123,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 +133,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 +146,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 +171,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' below.
+    #
+    # Some other 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