ruby-jss 4.2.0b2 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 998e9334c72d6bfa5826e571d4c69077d5876ecc047e5fb6d8329eec9e7935a1
-  data.tar.gz: 10cc0ac1056319a810d87234d98ab9ef8523e9156e96db018fe7729fc166988d
+  metadata.gz: 19c9e79713c2ae52e27acf1baaecdf03446328ebce206b0d4a6d6c995d98e0cf
+  data.tar.gz: b05700b3f5e07771b257af10da6b73cf44334916cbdc0442d9d7aca539518af9
 SHA512:
-  metadata.gz: 3b8b65205b159d6cc79c7dba9c3968d10746a7158037ed5326812e31b17c1a769c44d5c5ddf00442a073a5e42ee38ae993619390b088ff9ebafd089c5f4505b2
-  data.tar.gz: 8e55221f470dcaa7f385fdae5d725db9e179434b0f33fb31090bc403fed7a71c3988c4a2f6ca0ec6204ad49d20f4253d6dcf5cce31aa0f0677dcc48dc052bba7
+  metadata.gz: d400c1033d40a4128d5021e21f3fd367158caf2ed176108bf912198f76f4669bfd3500b26e0677279a9d87c65dc69974fe636588d100256f64a79315d64747b0
+  data.tar.gz: 631190601b377d45d1cb1ba80ec54decf662f7b6223d311f6b6e3a73dfea5731b86bac7d5046d47a6364395a3abb5b4ef4c1b1add424868da917ed037152fa8c

data/CHANGES.md

@@ -15,14 +15,14 @@ __Please update all installations of ruby-jss to at least v1.6.0.__
 Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue and providing examples of how it could be exploited.
 
 --------
-## \[4.2.0] Unreleased
+## \[4.2.0] 2025-06-11
 
 ### Moving forward with the Jamf Pro API
 With this release, we begin the long process of porting existing classes from the Classic API to the Jamf Pro API where possible, starting with `Jamf::Package`. So far, our implementation of classes from the Jamf Pro API has been limited to those not already implemented via the Classic API.
 
-However, because of our stated goals for implementing things in the Jamf Pro API (see [README-2.0.0.md](README-2.0.0.md)), we can't just change the existing classes without breaking lots of code. For example, in order to eliminate various 'hidden permissions requirements' and adhere more closely to the actual API, we're [eliminating cross-object validation](README-2.0.0.md#cross-object-validation-in-setters). 
+However, because of our stated goals and changes for implementing things in the Jamf Pro API (see [README-2.0.0.md](README-2.0.0.md)), we can't just change the existing classes without breaking lots of code. For example, in order to eliminate various 'hidden permissions requirements' and adhere more closely to the actual API, we're [eliminating cross-object validation](README-2.0.0.md#cross-object-validation-in-setters). 
 
-For Packages, this means that when setting the categoryId, you must provide an id, not a category name. In Jamf::Package, using the Classic API, you could provide a name, and ruby-jss would look at the categories in the API and validate/convert to an id. This required 'undocumented' permissions to see the category endpoints when working with the package endpoints. NOTE: if you have read-permissions on categories, you can still use the `Jamf::Category.valid_id` method to convert from names to ids yourself. That method is available for all collection classes in both APIs.
+For Packages this means that when setting the categoryId, for example, you must provide an id, not a category name. In the existing `Jamf::Package` class using the Classic API, you could provide a name, and ruby-jss would look at the categories in the API and validate/convert to an id. This required 'undocumented' permissions to see the category endpoints when working with the package endpoints. NOTE: if you have read-permissions on categories, you can still use the `Jamf::Category.valid_id` method to convert from names to ids yourself. That method is available for all collection classes in both APIs.
 
 In order to move forward with Jamf Pro-based classes, while providing reasonable backward compatibility, here's the plan:
 
@@ -30,15 +30,16 @@ In order to move forward with Jamf Pro-based classes, while providing reasonable
   - The original Classic API-based class will be marked as deprecated when the matching J-class is released.
   - The deprecated classes will exist for at least one year (probably longer) but will get few, if any, updates, mostly limited to security-related fixes. As of this release, `Jamf::Package` and `Jamf::Building` are deprecated. 
   - During the deprecation period, please update all your code to use the new Jamf Pro API-based classes.
-  - When the older Classic API-based class is actually removed, the remaning Jamf Pro API-based class will be aliased back to the original name, without the `J`. So at that point `Jamf::Package` and `Jamf::JPackage` will be the same class. At this time please start updating your code to use the non-J version of the class name.
+  - When the older Classic API-based class is actually removed, the remaining Jamf Pro API-based class will be aliased back to the original name, without the `J`. So at that point `Jamf::Package` and `Jamf::JPackage` will be the same class. At this time please start updating your code to use the non-J version of the class name.
   - After some long-ish period of time (2-5 years?), the `J` version of the class name will be removed. Or - maybe not! Aliases are cheap :-)
 
 If you have thoughts or comments on this, please reach out:
   - [Open an issue on github](https://github.com/PixarAnimationStudios/ruby-jss/issues)
-  - [Email the developers at ruby-jss@pixar.com](mailto:ruby-jss@pixar.com)
+  - [Email us at ruby-jss@pixar.com](mailto:ruby-jss@pixar.com)
   - Join the conversation in the [#ruby-jss Macadmins Slack Channel](https://macadmins.slack.com/archives/C03C7F563MK)
 
 ### Added
+  
   - `Jamf::JPackage`: The first major migration of a class from the Classic to the Jamf Pro API.
     - Implements the /v1/packages endpoints
     - Support for manifests
@@ -48,6 +49,19 @@ If you have thoughts or comments on this, please reach out:
       - The package must have a manifest
       - The .pkg file must be a "Product Archive", e.g. it must contain a 'Distribution' file, as when created with the `productbuild` command. Component packages created with `pkgbuild` will not work.
       - The .pkg file must be signed.
+
+  - Collection Resource classes from the Jamf Pro API can now define a constant OBJECT_NAME_ATTR, which indicates the attribute that holds the individual object's name, if that isn't "name". 
+
+    For example, Computer and MobileDevice prestage objects, the name is in the "displayName" attribute.  For JPackages via the Jamf Pro API, the package object's name (not its file name) is in the "packageName" object.
+    
+    When the OBJECT_NAME_ATTR is defined, the class can use "name" as a alias of the OBJECT_NAME_ATTR with getters & setters (`name=` is an alias of `displayName=`, etc) and can be used for .fetch and .valid_id:  `Jamf::JPackage.fetch name: 'foo'`  is the same as `Jamf::JPackage.fetch packageName: 'foo'`
+
+    For some objects this isn't relevant, e.g. Inventory Preload Records, but for JPAPI that use variations on the word 'name' for the objects actual name, this will help normalize things, and keep better compatility with objects from the Classic API, which all use 'name'.
+
+  - `Jamf::ManagedSoftwareUpdates` This module replaces the deprecated MacOSManagedUpdates class, giving access to the `v1/managed-software-updates` endpoints for creating and querying Software Update plans and their statuses. This code is preliminary and provides basic access. It will probably be enhanced in the future.
+    
+    See the `Jamf::ManagedSoftwareUpdates.send_managed_sw_update` and `Jamf::ManagedSoftwareUpdates.status` module methods, and the `Jamf::ManagedSoftwareUpdates::Plan` class, 
+
   
 ### Changed
   - `Jamf::JpBuilding` is now known as `Jamf::JBuilding`
@@ -69,17 +83,21 @@ If you have thoughts or comments on this, please reach out:
 
   - Fix to ensure passing correct connection object when fetching.
 
+  - Fix for `CollectionResource.valid_id` for JP API objects, it now works when given an identifier and value, eg `SomeClass.valid_id displayName: 'foobar'`
+
 ### Deprecated
   - `Jamf::Package` and `Jamf::Building` are now deprecated amd will be removed in a future release. Please update your code to use `Jamf::JBuilding` and `Jamf::JPackage`
 
   - Auto-generated OAPISchemas are no longer used _directly_. There's still too much inconsistency and other problems that arise from using them as we were. See the NOTE from the previous release. 
 
-    For the forseeable future we'll keep the overall structure of the class/mixin hierarchy, and will probably use the auto-generated classes for reference, but as new classes are added to ruby-jss via the Jamf Pro API, the `OAPISchemas` classes will be hand-tweaked and hand-maintained as needed, just like APIObject classes always have been for objects in the Classic API. 
+    For the forseeable future we'll keep the overall structure of the class/mixin hierarchy, and will probably use auto-generated classes as a starting point, but as new classes are added to ruby-jss via the Jamf Pro API, the `OAPISchemas` classes will be hand-built and maintained as needed, just like APIObject classes always have been for objects in the Classic API. 
 
-    To start with, we're keeping the ones currently in use (about 40 of them) where they've always lived, in the `lib/jamf/api/jamf_pro/oapi_schemas` directory, and the new bespoke ones will go there also. The other ~550 unused auto-generated classes will be removed from ruby-jss.  
+    To start with, we're keeping the ones currently in use (about 40 of them) where they've always lived, in the `lib/jamf/api/jamf_pro/oapi_schemas` directory, and the new bespoke ones will go there also. The other ~550 unused auto-generated classes have been removed from ruby-jss.  
     
     For details about how the've been auto-generated, see the `generate_object_models` tool in the bin directory.
 
+  - `Jamf::MacOSManagedUpdates` This endpoint has been deprecated by Jamf, and replaced with the more broad, and future-proof `Jamf::ManagedSoftwareUpdates` module.
+
 --------
 ## \[4.1.1] 2024-06-25
 

data/README-2.0.0.md

@@ -34,7 +34,7 @@ These changes have been in mind for some time, but the requirement in late 2022
   - [The valid_id method for Classic API collection classes](#the-valid_id-method-for-classic-api-collection-classes)
 - [Planned deprecations](#planned-deprecations)
   - [Use of the term 'api'](#use-of-the-term-api)
-  - [.map_all_ids_to method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes)
+  - [map_all_ids_to method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes)
   - [Using .make, #create, and #update for Classic API objects](#using-make-create-and-update-for-classic-api-objects)
   - [JSS::CONFIG](#jssconfig)
   - [Jamf::Connection instance methods #next_refresh, #secs_to_refresh, &  #time_to_refresh](#jamfconnection-instance-methods-next_refresh-secs_to_refresh---time_to_refresh)
@@ -76,7 +76,7 @@ The announcement with Jamf Pro 10.35 that the Classic API can use, and will even
 
 #### A single Connection class
 
-There is now one `Jamf::Connection` class, instances of which are connections to a Jamf Pro server. Once connected, the connection instance maintains connections to _both_ APIs and other classes use them as needed. As before, there are low-level methods available for sending HTTP requests manually, which are specific to each API. See the documentation for `Jamf::Connection` (link TBA) for details.
+There is now one `Jamf::Connection` class, instances of which are connections to a Jamf Pro server. Once connected, the connection instance maintains connections to _both_ APIs and other classes use them as needed. As before, there are low-level methods available for sending HTTP requests manually, which are specific to each API. See the documentation for [Jamf::Connection](https://www.rubydoc.info/gems/ruby-jss/Jamf/Connection) for details.
 
 ##### Connecting to the API
 
@@ -91,7 +91,7 @@ Other connection parameters can be passed in as normal.
 
 ###### The default connection
 
-The top-level module methods for accessing the 'default' connection are still available and are now synonyms: `Jamf.cnx` and `JSS.api` both return the current default Jamf::Connection instance. There is also a top-level methods`Jamf.connect` which is the same as `Jamf.cnx.connect`. The top-level methods for changing the default connection are still there. 
+The top-level module methods for accessing the 'default' connection are still available and are now synonyms: `Jamf.cnx` and `JSS.api` both return the current default Jamf::Connection instance. There is also a top-level method`Jamf.connect` which is the same as `Jamf.cnx.connect`. The top-level methods for changing the default connection are still there. 
 
 NOTE: The use of `JSS::API` has been deprecated for years now, and still is (see below).
 
@@ -118,6 +118,13 @@ The `.all` method, and its relatives like `.all_ids`, `.all_names`, etc. exist f
 To confirm which API a class comes from, just look at its `API_SOURCE` constant, e.g. `Jamf::Computer::API_SOURCE`. This constant will return a symbol, either `:classic` or `:jamf_pro`
 
 ### Automatic code generation
+---
+**UPDATE** 
+
+As of version 4.2.0, the auto-generated class definitions will only be used as a starting point for more bespoke, hand-maintained classes. This is due to ongoing inconsistencies across the Jamf Pro API, and occasional name-clashes.
+See the Deprecations section for version 4.2.0 in the [CHANGES](CHANGES.md) file for a longer explaination.
+
+---
 
 While the Classic API classes in ruby-jss are very hand-built and must be manually edited to add access to new data, the Jamf Pro API has an OpenAPI3 specification - a JSON document that fully describes the entire API and what it can do.
 
@@ -133,7 +140,7 @@ If you develop ruby-jss, please see (documentation link will go here) for more i
 
 ### Autoloading with Zeitwerk
 
-Because the classes generated from the OAPI spec number in the hundreds, it's a waste of memory and time to load all of them in every time you `require 'ruby-jss'`, since most of them will never be used for any given application.
+Because ruby-jss implements so many classes and modules, it's a waste of memory and time to load all of them in every time you `require 'ruby-jss'`, since most of them will never be used for any given application.
 
 To deal with this, ruby-jss now uses the wonderfully cool [Zeitwerk gem](https://github.com/fxn/zeitwerk) to automatically load only the files needed for classes and modules as they are used.
 
@@ -172,7 +179,11 @@ The `.all` method will never deliver paged results, however if you give it a `fi
 
 ### API data are no longer cached (?)
 
-**NOTE:** As of this writing, caching has been removed for the objects from the Jamf Pro API, but caching remains in the Classic API. Its removal, or the re-instatement of caching for JP API objects, are pending discussion with other users of ruby-jss.
+---
+**NOTE:** 
+Caching has been removed for the objects from the Jamf Pro API, but remains for those from the Classic API. The re-instatement of caching for JP API objects is pending discussion with other users of ruby-jss.
+
+---
 
 Pre-2.0, methods that would fetch large datasets from the server would always cache that data in the Connection object, and by default use the cache in future calls unless a `refresh` parameter is given. These datasets included:
 
@@ -274,7 +285,7 @@ Here are the things we are planning on removing or changing in the coming months
 
 In ruby-jss < 2.0, the term `api` is used with the Classic API in method names, method parameters, instance variables, attributes, and constants. It is used to pass, access, refer to, or hold instances of JSS::APIConnnection, e.g. so a method that talks to the server would use the passed connection rather than the module-wide default connection.  
 
-The term 'api' is inappropriate because the thing being passed is a 'connection' not an 'api'. Now that there are actually two APIs at play, that usage is even less appropriate.
+The term 'api' is inappropriate because the thing being referred to is a 'connection' not an 'api'. Now that there are actually two APIs at play, that usage is even less appropriate.
 
 Going forward, use `cnx` (simpler to type than 'connection') instead. Example:
 
@@ -384,11 +395,11 @@ Or when you try to set the value of an extension attribute on a Computer object,
 
 This validation happens before you try to send the new data to the server.
 
-This type of pre-validation will be removed over time from objects in the Classic API, for 3 reasons:
+This type of pre-validation will not be use when using the Jamf Pro API, for 3 reasons:
 
 1) The API itself will perform this validation when you send the data, and will return an error if there's a problem.
 2) Removing this validation will simplify the code, and reduce interdependency between objects
-3) Removing this code will make it easier to understand the permissions needed to do things in ruby-jss
+3) Removing this code will make it easier to understand the permissions needed to do things in ruby-jss, removing 'hidden permissions requirements' when interacting with class-specific API endpoints.
 
 The last point is very important.  Right now, in order to be able to manipulate the scope of any scopable object, the account with which you're accessing the API must have at least 'read' permission on all the different kinds of objects that _might_ be in the scope: computers, computer groups, buildings, departments, network segments, and so on. Removing or limiting the validation-based interdependency will make it easier to limit the access needed for API service accounts, and thereby increase overall security.
 

data/README.md

@@ -1,24 +1,6 @@
 # ruby-jss: Working with the Jamf Pro APIs in Ruby
 [![Gem Version](https://badge.fury.io/rb/ruby-jss.svg)](http://badge.fury.io/rb/ruby-jss)
 
-## Version 2.0.0 has been released
-
-Version 2.0.0 has major changes! While we've strived for _mostly_ being backward compatible, and have done lots of testing, YMMV.  Please report any issues.
-
-_NOTE_: ruby-jss 2.0 is not completely backward compatible, please see  [README-2.0.0.md](README-2.0.0.md) for more info
-
-### Highlights
-
-- Support for Ruby 3.x
-  - tested in 3.0 and 3.1
-- Combined access to both the Classic and Jamf Pro APIs
-  - A single namespace module
-  - Connection objects talk to both APIs & automatically handle details like bearer tokens
-- Auto-generated code for Jamf Pro API objects
-- Autoloading of code using [Zeitwerk](https://github.com/fxn/zeitwerk)
-
-For details about the changes, the document [README-2.0.0.md](README-2.0.0.md).
-
 ## _IMPORTANT_: Known Security Issue in v1.5.3 and below
 
 Versions of ruby-jss prior to 1.6.0 contain a known security issue due to how we were using the 'plist' gem.
@@ -35,8 +17,6 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 
 <!-- TOC -->
 
-- [Version 2.0.0 has been released](#version-200-has-been-released)
-  - [Highlights](#highlights)
 - [IMPORTANT: Known Security Issue in v1.5.3 and below](#important-known-security-issue-in-v153-and-below)
 - [DESCRIPTION](#description)
 - [SYNOPSIS](#synopsis)
@@ -50,6 +30,7 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
     - [Updating Objects](#updating-objects)
     - [Deleting Objects](#deleting-objects)
 - [OBJECTS IMPLEMENTED](#objects-implemented)
+    - [Migrating classes from the Classic to the Jamf Pro API](#migrating-classes-from-the-classic-to-the-jamf-pro-api)
     - [Other useful classes & modules:](#other-useful-classes--modules)
 - [Object-related API endpoints](#object-related-api-endpoints)
 - [CONFIGURATION](#configuration)
@@ -64,7 +45,7 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 
 ## DESCRIPTION
 
-ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and
+ruby-jss defines a Ruby module called `Jamf`, which is used for accessing both the 'Classic' and
 'Jamf Pro' APIs of a Jamf Pro server. Jamf Pro is an enterprise-level management tool for Apple
 devices from [Jamf.com](http://www.jamf.com/). ruby-jss is available as a [ruby gem](https://rubygems.org/gems/ruby-jss), and the
 [source is on github](https://github.com/PixarAnimationStudios/ruby-jss).
@@ -74,16 +55,17 @@ Details like authentication tokens, token refreshing, JSON and XML parsing, and
 which API are all handled under-the-hood.
 
 The Jamf module abstracts many API resources as Ruby objects, and provides methods for interacting with those
-resources. It also provides some features that aren't a part of the API itself, but come with other
-Jamf-related tools, such as uploading {Jamf::Package} files to the primary fileshare distribution
-point, and the installation of those objects on client machines. (See [BEYOND THE API](#beyond-the-api))
+resources. It can also provide some features that aren't a part of the API itself, but come with other
+Jamf-related tools.
 
 The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled,
 some only minimally. Of those, some are read-only, some partially writable, some fully read-write.
 We've implemented the things we need in our environment, and as our needs grow, we'll add more.
 Hopefully others will find it useful, and add more to it as well.
 
-[Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
+For some of the major changes that happened with the release of v2.0.0, see [README-2.0.0](README-2.0.0.md)
+
+[Full technical documentation can be found at rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/)
 
 ## SYNOPSIS
 
@@ -173,6 +155,8 @@ Most of the time, you'll only need a single connection to a single server, and t
 you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and
 access, and pass those connection objects into methods using the `cnx:` parameter as appropriate.
 
+This is especially important when creating tools that use threads or fibers to perform different tasks concurrently. In such cases the default connection should never be used, and every task should use its own connection object, preferably closing it when done.
+
 ```ruby
 # Make connections to 2 different Jamf servers.
 # The .new class method accepts the same parameters as the #connect instance method,
@@ -316,27 +300,34 @@ Here's some of what we've implemented so far. See each Class's [documentation(ht
 * {Jamf::AdvancedComputerSearch}
 * {Jamf::AdvancedMobileDeviceSearch}
 * {Jamf::AdvancedUserSearch}
-* {Jamf::Building}
+* {Jamf::APIClient}
+* {Jamf::APIRole}
+* {Jamf::Building} (Classic, deprecated), {Jamf::JBuilding} (Jamf Pro)
 * {Jamf::Category}
 * {Jamf::Computer}
 * {Jamf::ComputerExtensionAttribute}
 * {Jamf::ComputerGroup}
 * {Jamf::ComputerInvitation}
+* {Jamf::ComputerPrestage}
 * {Jamf::Department}
+* {Jamf::DeviceEnrollment}
 * {Jamf::DistributionPoint}
 * {Jamf::DockItem}
 * {Jamf::EBook}
 * {Jamf::IBeacon}
+* {Jamf::InventoryPreloadRecord}
 * {Jamf::LdapServer}
+* {Jamf::MacApplication}
 * {Jamf::MobileDevice}
 * {Jamf::MobileDeviceApplication}
 * {Jamf::MobileDeviceConfigurationProfile}
 * {Jamf::MobileDeviceExtensionAttribute}
 * {Jamf::MobileDeviceGroup}
+* {Jamf::MobileDevicePrestage}
 * {Jamf::NetBootServer}
 * {Jamf::NetworkSegment}
 * {Jamf::OSXConfigurationProfile}
-* {Jamf::Package}
+* {Jamf::Package} (Classic, deprecated), {Jamf::JPackage} (Jamf Pro)
 * {Jamf::PatchTitle}
 * {Jamf::PatchTitle::Version}
 * {Jamf::PatchExternalSource}
@@ -344,7 +335,8 @@ Here's some of what we've implemented so far. See each Class's [documentation(ht
 * {Jamf::PatchPolicy}
 * {Jamf::Peripheral}
 * {Jamf::PeripheralType}
-* {Jamf::Policy} (not fully implemented)
+* {Jamf::Policy} 
+* {Jamf::Printer} 
 * {Jamf::RemovableMacAddress}
 * {Jamf::RestrictedSoftware}
 * {Jamf::Script}
@@ -353,10 +345,28 @@ Here's some of what we've implemented so far. See each Class's [documentation(ht
 * {Jamf::User}
 * {Jamf::UserExtensionAttribute}
 * {Jamf::UserGroup}
+* {Jamf::VPPAccount}
 * {Jamf::WebHook}
 
 **NOTE** Most Computer and MobileDevice data gathered by an Inventory Upate (a.k.a. 'recon') is not editable.
 
+#### Migrating classes from the Classic to the Jamf Pro API
+
+With the release of version 4.2.0, we begin the long process of porting existing classes from the Classic API to the Jamf Pro API where possible, starting with `Jamf::Package`. Before that, our implementation of classes from the Jamf Pro API has been limited to those not already implemented via the Classic API, such as `Jamf::InventoryPreloadRecord`.
+
+However, because of our stated goals for implementing things in the Jamf Pro API (see [README-2.0.0.md](README-2.0.0.md)), we can't just change the existing classes without breaking lots of code. For example, in order to eliminate various 'hidden permissions requirements' and adhere more closely to the actual API, we're [eliminating cross-object validation](README-2.0.0.md#cross-object-validation-in-setters). 
+
+For example, for Packages this means that when setting the categoryId, you must provide an id, not a category name. In Jamf::Package, using the Classic API, you could provide a name, and behind-the-scenes ruby-jss would look at the categories in the API and validate/convert to an id. This required 'undocumented' read-permissions to the categories when working with packages. NOTE: if you do have read-permissions on categories, you can still use the `Jamf::Category.valid_id` method to convert from names to ids yourself. That method is available for all collection classes in both APIs.
+
+In order to move forward with Jamf Pro-based classes, while providing reasonable backward compatibility, here's the plan:
+
+  - For each class being migrated, and new class, prepended with `J` will be created.  So for accessing packages via the Jamf Pro API, we are introducing the class `Jamf::JPackage`.
+  - The original Classic API-based class will be marked as deprecated when the matching J-class is released.
+  - The deprecated classes will exist for at least one year (probably longer) but will get few, if any, updates, mostly limited to security-related fixes.
+  - During the deprecation period, please update all your code to use the new Jamf Pro API-based classes.
+  - When the older Classic API-based class is actually removed, the remaning Jamf Pro API-based class will be aliased back to the original name, without the `J`. So at that point `Jamf::Package` and `Jamf::JPackage` will be the same class. At this time please start updating your code to use the non-J version of the class name.
+  - After some long-ish period of time (2-5 years?), the `J` version of the class name will be removed. Or - maybe not! Aliases are cheap :-)
+
 #### Other useful classes & modules:
 
 These modules either provide stand-alone methods, or are mixed in to other classes to extend their functionality. See their documentation for details
@@ -367,7 +377,7 @@ These modules either provide stand-alone methods, or are mixed in to other class
 
 * {Jamf::Scopable} - a module that handles Scope for those objects that can be scoped. It defines the Scope class used in those objects. Instances of Scope are where you change targets, limitations, and exclusions.
 
-* {Jamf::MDM} - a module that handles sending MDM commands. It is accessed via the Computer and MobileDevice classes and their instances.
+* {Jamf::MDM} - a module that handles sending MDM commands via the Classic API. It is accessed via the Computer and MobileDevice classes and their instances.
 
 ## Object-related API endpoints
 
@@ -398,10 +408,13 @@ The currently known attributes are:
 
 * api_server_name [String] the hostname of the Jamf API server
 * api_server_port [Integer] the port number for the API connection
-* api_verify_cert [Boolean] 'true' or 'false' - if SSL is used, should the certificate be verified? (usually false for a self-signed cert)
+# api_ssl_version [String] the SSL version to use for the connection. Default is TLSv1_2
+* api_verify_cert [Boolean] if SSL is used, should the certificate be verified? (usually false for a self-signed cert)
 * api_username [String] the Jamf username for connecting to the API
 * api_timeout_open [Integer] the number of seconds for the open-connection timeout
 * api_timeout [Integer] the number of seconds for the response timeout
+* package_manifest_base_url [String] Used by JPackage#generate_manifest. 
+  The base-url for downloading a package for installation. The JPackage#fileName is appended to this to create the full URL.
 
 To put a standard server & username on all client machines, and auto-accept the Jamf's self-signed https certificate, create the file /etc/ruby-jss.conf containing three lines like this:
 

data/lib/jamf/api/classic/api_objects/patch_title.rb

@@ -58,7 +58,6 @@ module Jamf
   #
   class PatchTitle < Jamf::APIObject
 
-    include Jamf::Sitable
     include Jamf::Categorizable
     include Jamf::Creatable
     include Jamf::Updatable
@@ -539,7 +538,6 @@ module Jamf
       add_changed_pkg_xml obj unless @changed_pkgs.empty?
 
       add_category_to_xml doc
-      add_site_to_xml doc
 
       doc.to_s
     end # rest_xml

data/lib/jamf/api/jamf_pro/api_objects/api_client.rb

@@ -105,6 +105,9 @@ module Jamf
       id displayName
     ].freeze
 
+    # The attribute holding the object's name
+    OBJECT_NAME_ATTR = :displayName
+
     # Class Methods
     ###############################
 

data/lib/jamf/api/jamf_pro/api_objects/api_role.rb

@@ -121,6 +121,9 @@ module Jamf
       id displayName
     ].freeze
 
+    # The attribute holding the object's name
+    OBJECT_NAME_ATTR = :displayName
+
     # Class Methods
     ###############################