ruby-jss 3.1.0b2 → 3.2.0b3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bae3e60bf2b0cb08e2bc6a1ead15c1de6b213e667046c90026a803f3549b67da
-  data.tar.gz: a08f8ad25dd5ab4bfd614e2e6b508fd2b408154f2d39bcabfc1a693341a9fedf
+  metadata.gz: 2f0e6a46c0c834feb898c00c2df2f509756a7f84cd346510c6f2502be433258a
+  data.tar.gz: f765f17913f8bf75f8ea9d066845b451150ce893139d089e797fed061a84929d
 SHA512:
-  metadata.gz: 54b0cbe591066ae572f1ae3797afddea5f3f44be35273127798473118b96d014090fc09f39de28be41e96cd19ebac1334cd016d9e97a43b4163791341303ce1a
-  data.tar.gz: 35e189daa832b3a6598725f42d3d0716bb1f95845c70edd86206ab1a35ffb8f0af8680d7c33306d08ad258758c623a3974ba107574dc1dbebd6e6db5c8a65e28
+  metadata.gz: fb2c176af326d5d03e7d2b650c5aa8d2bafd3de420e0a3514af9532a9a68619ec5bdc9888e718ebeec1f355061b5c931ae4663dd43310d7d8c3e8edf99fa121c
+  data.tar.gz: 12c3b89f22ed8e9a9384e8928d7bd4c5f09122276f793cf49e418ded3293e4a741bdfa2fad9ca96d47c6016d97fed63db5aeb447cf46cb4cf59e9b3582641700

data/CHANGES.md

@@ -15,11 +15,44 @@ __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.
 
 --------
-## \[3.1.0] 2023-06-05
+## \[UNRELEASED] 
+
+### Changed
+  - Improved handling of known API bug in Jamf::Scopable::Scope.  
+
+    There is a long-standing bug in working with 'scope' via the Classic API, which can cause data-loss when you have 'Users' and 'User Groups' (known in the api data as `jss_users` and `jss_user_groups`) defined in the targets or exclusions. Thanks to @yanniks on GitHub, I recently learned that the bug only affects a few API objects, namely Policies and PatchPolicies.  
+
+    This release of ruby-jss will properly handle jss_users and jss_user_groups in all scopes where the API can handle them. In Policy and PatchPolicy objects, those values aren't allowed, since the API can't deal with them. If you edit any other aspect of the scope of one of those obects in ruby-jss, you'll get a warning that saving your changes may cause data-loss - deleting any defined Users and User Groups in the targets or exclusions. If the scope really doesn't use any Users or User Groups, you should be OK saving your changes. To prevent the warnings, call `Jamf::Scopable::Scope.do_not_warn_about_policy_scope_bugs` before changing any scopes.  
+
+    For more details, see the discussion in the comments/docs for the Jamf::Scopeable::Scope class in lib/jamf/api/classic/api_objects/scopable/scope.rb or in the [rubydocs page for the Scope class](https://www.rubydoc.info/gems/ruby-jss/Jamf/Scopable/Scope).  
+
+    Many thanks to @yanniks for bringing to my attention that the bug doesn't occur in all scopes.
+
+  - Warn of API bug when using jss_user_groups as scope targets of OSXConfigurationProfiles
+
+    We discovered a new (to us) isolated occurrance of the long-standing XML Array => JSON Hash bug
+    (which can cause data loss). If you have more that one jss_user_groups defined as scope targets
+    of a OSXConfigurationProfile, the API will only return the last of those groups in the JSON data, 
+    and saving changes to the profile via ruby-jss will remove the other groups from the Profile in 
+    Jamf. 
+    
+    This seems to only affect scope targets of OSXConfigurationProfiles - groups used in exclusions
+    seem to be fine, as do other scopable objects that uses jss_user_groups anywhere in their scope.
+
+    When you edit the scope of a scopable object and ruby-jss notices this API bug applies, you'll see a warning that saving changes to the scope may cause data loss. To disable these warnings, call `Jamf::Scopable::Scope.do_not_warn_about_array_hash_scope_bugs` before changing any scopes.  
+
+    For more details, see the discussion in the comments/docs for the Jamf::Scopeable::Scope class in lib/jamf/api/classic/api_objects/scopable/scope.rb or in the [rubydocs page for the Scope class](https://www.rubydoc.info/gems/ruby-jss/Jamf/Scopable/Scope).  
+
+
+### Fixed
+  - Jamf::DeviceEnrollment.device no longer uses String#upcase!, which fails on frozen strings. Instead just use String#casecmp?
+
+## \[3.1.0] 2023-06-06
 
 ### Added
   - Jamf::Computer.filevault_info and Jamf::Computer#filevault_info can retrieve FileVault info from v1/computer-inventory/filevault and related endpoints
   - Jamf::Computer.recovery_lock_password and Jamf::Computer#recovery_lock_password can retrieve stored recovery lock passwords
+  - Jamf::Pager#last_fetched_page - Integer, the last page returned by #fetch_next_page
   - There are now several ways to set scopes to all targets.
     - The original #include_all has been renamed #set_all_targets, and #include_all is an alias to it
     - The symbol :all can be passed to the #set_targets, and #add_target methods as they 'key' parameter, and they will just call #set_all_targets
@@ -35,7 +68,7 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
   - Fixed a bug in Jamf::Pager#initialize when constructing the query-path of the paged resource URL
   - Fixed a bug in Jamf::Pager#initialize: The instantiate: parameter takes a class, not a boolean
   - Fixed a bug in Jamf::CollectionResource.pager: The instantiate: parameter takes a boolean, but must pass a class to Jamf::Pager#initialize
-  - Jamf::OAPIObject base-class: can now instantiate objects that hold a single value
+  - Jamf::OAPIObject (base-class) can now instantiate objects that hold a single value
 
 ### Changed
   - Auto-generated OAPISchemas have been refreshed from Jamf Pro 10.46.0
@@ -96,13 +129,38 @@ Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as
 
 Here are the high-level changes and there are many many others. For more details, see [CHANGES-2.0.0.md](CHANGES-2.0.0.md)
 
-- 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
+### Added
+
+  - 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)
+  - Auto-generated code for Jamf Pro API objects
+  - Autoloading of code using [Zeitwerk](https://github.com/fxn/zeitwerk)
+
+### Changed
+
+These things are notably different in v2.0.0
+  - Paged queries to the Jamf Pro API
+  - API data are no longer cached for the JP API, possibly eventually for the classic
+  - No Attribute aliases for Jamf Pro API objects
+  - Class/Mixin hierarchy for Jamf Pro API objects
+  - Support for 'Sticky Sessions' in Jamf Cloud
+  - The valid_id method for Classic API collection classes
+
+### Deprecated
+
+These things will go away in some future version of ruby-jss, please update your code sooner than later.
+
+  - Use of the term 'api'
+  - .map_all_ids_to method for Classic API collection classes
+  - Using .make, #create, and #update for Classic API objects
+  - JSS::CONFIG
+  - Jamf::Connection instance methods #next_refresh, #secs_to_refresh, &  #time_to_refresh
+  - Cross-object validation in setters
+  - fetch :random
+
 
 ## \[1.6.7] - 2022-02-22
 
@@ -170,10 +228,6 @@ Here are the high-level changes and there are many many others. For more details
 
 ### 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.
@@ -184,6 +238,11 @@ Here are the high-level changes and there are many many others. For more details
 
   - 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.
 
+### Security
+
+  - 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.
 
 ## \[1.5.3] - 2020-12-28
 

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

@@ -408,7 +408,6 @@ module Jamf
       @grace_period_message = grace[:message]
       @grace_period_message = DFT_GRACE_PERIOD_MESSAGE if @grace_period_message.to_s.empty?
 
-
       # read-only values, they come from the version.
       @release_date = JSS.epoch_to_time gen[:release_date]
       @incremental_update = gen[:incremental_update]
@@ -432,6 +431,7 @@ module Jamf
     #
     def patch_title_name
       return @patch_title.name if @patch_title
+
       Jamf::PatchTitle.map_all_ids_to(:name)[software_title_configuration_id]
     end
 
@@ -439,6 +439,7 @@ module Jamf
     #
     def target_version=(new_tgt_vers)
       return if new_tgt_vers == target_version
+
       @target_version = validate_target_version new_tgt_vers
       @need_to_update = true
       @refetch_for_new_version = true
@@ -450,6 +451,7 @@ module Jamf
     #
     def enable
       return if enabled
+
       @enabled = true
       @need_to_update = true
     end
@@ -460,6 +462,7 @@ module Jamf
     #
     def disable
       return unless enabled
+
       @enabled = false
       @need_to_update = true
     end
@@ -468,6 +471,7 @@ module Jamf
     #
     def allow_downgrade=(new_val)
       return if new_val == allow_downgrade
+
       @allow_downgrade = Jamf::Validate.boolean new_val
       @need_to_update = true
     end
@@ -476,6 +480,7 @@ module Jamf
     #
     def patch_unknown=(new_val)
       return if new_val == patch_unknown
+
       @patch_unknown = Jamf::Validate.boolean new_val
       @need_to_update = true
     end
@@ -488,6 +493,7 @@ module Jamf
         days = NO_DEADLINE unless days.positive?
       end
       return if days == deadline
+
       @deadline = days
       @need_to_update = true
     end
@@ -498,6 +504,7 @@ module Jamf
       mins = Jamf::Validate.integer(mins)
       mins = 0 if mins.negative?
       return if mins == grace_period
+
       @grace_period = mins
       @need_to_update = true
     end
@@ -506,6 +513,7 @@ module Jamf
     #
     def grace_period_subject=(subj)
       return if grace_period_subject == subj.to_s
+
       @grace_period_subject = subj.to_s
       @need_to_update = true
     end
@@ -514,6 +522,7 @@ module Jamf
     #
     def grace_period_message=(msg)
       return if grace_period_message == msg
+
       @grace_period_message = msg
       @need_to_update = true
     end
@@ -563,8 +572,10 @@ module Jamf
         return a_title.id
       end
       raise Jamf::MissingDataError, ':patch_title is required' unless a_title
+
       title_id = Jamf::PatchTitle.valid_id a_title
       return title_id if title_id
+
       raise Jamf::NoSuchItemError, "No Patch Title matches '#{a_title}'"
     end
 
@@ -613,7 +624,7 @@ module Jamf
       general.add_element('allow_downgrade').text = allow_downgrade
       general.add_element('patch_unknown').text = patch_unknown
 
-      obj << scope.scope_xml
+      obj << scope.scope_xml if scope.should_update?
 
       add_self_service_xml doc
 

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

@@ -2111,7 +2111,7 @@ module Jamf
       activation = @server_side_limitations[:activation]
       date_time_limitations.add_element('activation_date_epoch').text = activation.to_jss_epoch if activation
 
-      obj << @scope.scope_xml
+      obj << @scope.scope_xml if @scope.should_update?
 
       reboot = obj.add_element 'reboot'
       JSS.hash_to_rexml_array(@reboot_options).each { |elem| reboot << elem }

data/lib/jamf/api/classic/api_objects/scopable/scope.rb

@@ -35,7 +35,7 @@ module Jamf
     #
     # Scope data comes from the API as a hash within the overall object data.
     # The main keys of the hash define the included targets of the scope. A
-    # sub-hash defines limitations on those inclusions, and another sub-hash
+    # sub-hash defines limitations on those targets, and another sub-hash
     # defines explicit exclusions.
     #
     # This class provides methods for adding, removing, or fully replacing the
@@ -44,85 +44,143 @@ module Jamf
     # This class also provides a way to see if a machine will be included in
     # this scope.
     #
-    # IMPORTANT - Users & User Groups in Targets and Exclusions:
+    # = Discussion: Users & User Groups in Scopes:
+    #######################################
+    # The Classic API has bugs, as well as non-obvious/historical oddness,
+    # regarding the use of Users, UserGroups, Directory Service/Local Users,
+    # and Directory Service User Groups in scopes.
+    # Here's a discussion of those issues, and how ruby-jss handles them.
     #
-    # The classic API has bugs regarding the use of Users, UserGroups,
-    # LDAP/Local Users, & LDAP User Groups in scopes. Here's a discussion
-    # of those bugs and how ruby-jss handles them.
+    # == Historical Oddness
     #
-    # Targets/Inclusions
-    #  - 'Users' in the Scope UI can only be Jamf::Users - No LDAP
-    #    - BUG: They do not appear in API data (XML or JSON) and are
-    #      NOT SUPPORTED in ruby-jss.
-    #    - You must use the Web UI to work with them in a Scope.
-    #  - 'User Groups' in the Scope UI can only be Jamf::UserGroups - No LDAP
-    #    - BUG: They do not appear in API data (XML or JSON) and are
-    #      NOT SUPPORTED in ruby-jss.
-    #    - You must use the Web UI to work with them in a Scope.
+    # Because the concept of 'scope' existed before Jamf Pro had 'Users'
+    # and 'User Groups' (Jamf::User and Jamf::UserGroup classes in ruby-jss)
+    # there is non-obvious inconsistency between the labels for API data, and
+    # the labels for that data in the web UI:
     #
-    # Limitations
-    #  - 'LDAP/Local Users' can be any string
-    #    - The Web UI accepts any string, even if no matching Local or LDAP user.
-    #    - The data shows up in API data in scope=>limitations=>users
-    #      by name only (the string provided), no IDs
-    #  - 'LDAP User Groups' can only be LDAP groups that actually exist
-    #    - The Web UI won't let you add a group that doesn't exist in ldap
-    #    - The data shows up in API data in scope=>limitations=>user_groups
-    #      by name and LDAP ID (which may be empty)
-    #    - The data ALSO shows up in API data in scope=>limit_to_users=>user_groups
-    #      by name only, no LDAP IDs. ruby-jss ignores this and looks at
-    #      scope=>limitations=>user_groups
+    # === Users
     #
-    # Exclusions, combines the behavior of Inclusions & Limitations
-    #  - 'Users' in the Scope UI can only be Jamf::Users - No LDAP
-    #    - BUG: They do not appear in API data (XML or JSON) and are
-    #      NOT SUPPORTED in ruby-jss.
-    #    - You must use the Web UI to work with them in a Scope.
-    #  - 'User Groups' in the Scope UI can only be Jamf::UserGroups - No LDAP
-    #    - BUG: They do not appear in API data (XML or JSON) and are
-    #      NOT SUPPORTED in ruby-jss.
-    #    - You must use the Web UI to work with them in a Scope.
-    #  - 'LDAP/Local Users' can be any string
-    #    - The Web UI accepts any string, even if no matching Local or LDAP user.
-    #    - The data shows up in API data in scope=>exclusions=>users
-    #      by name only (the string provided), no IDs
-    #  - 'LDAP User Groups' can only be LDAP groups that actually exist
-    #    - The Web UI won't let you add a group that doesn't exist in ldap
-    #    - The data shows up in API data in scope=>exclusions=>user_groups
-    #      by name and LDAP ID (which may be empty)
+    # What appears in the UI as 'Users' are User objects in Jamf pro, which in ruby-jss
+    # are Jamf::User instances.
     #
+    # These will appear in the API data as \<jss_users> element with \<user> sub-elements (XML)
+    # or the 'jss_users' array (JSON). These are available as Targets or Exclusions.
     #
-    # How ruby-jss handles this:
+    # In this class, they are also referred to as 'jss_users'
     #
-    #   - Methods #set_targets and #add_target will not accept the keys
-    #     :user, :users, :user_group, :user_groups.
+    # === Directory Service/Local Users
     #
-    #   - Method #remove_target will ignore them.
+    # When editing a scope in the UI, in Limitations and Exclusions, you can
+    # add arbitrary strings that will be matched to the users assigned to machines,
+    # or that appear in any of the defined LDAP servers.
+    # These scope items are called 'Directory Service/Local Users' but
+    # used to be called 'LDAP/Local Users'
     #
-    #   - Methods #set_limitations, #add_limitation & #remove_limitation will accept:
-    #     - :user, :ldap_user, or :jamf_ldap_user (and their plurals) for working
-    #       with 'LDAP/Local Users'. When setting or adding, the provided
-    #       string(s) must exist as either a Jamf::User or an LDAP user
-    #     - :user_group or :ldap_user_group (and their plurals) for working with
-    #       'LDAP User Groups'. When setting or adding, the provided string
-    #       must exist as a group in LDAP.
+    # In the API data for scopes, these items appear in the \<users> element
+    # with \<user> sub-elements (XML) or 'users' array (JSON) of the limitations
+    # and exclusions data
     #
-    #   - Methods #set_exclusions, #add_exclusion & #remove_exclusion will accept:
-    #     - :user, :ldap_user, or :jamf_ldap_user (and their plurals) for working
-    #       with 'LDAP/Local Users'. When setting or adding, the provided string(s)
-    #       must exist as either a Jamf::User or an LDAP user.
-    #     - :user_group or :ldap_user_group (and their plurals) for working with
-    #       'LDAP User Groups''. When setting or adding, the provided string
-    #       must exist as a group in LDAP.
+    # In this class, these items ultimately use the same names they have in the API data:
+    # 'users' but when specifying that you are setting that value, you can use any of
+    # these synonyms, plural or singular:
+    #     ldap_users, jamf_ldap_users, directory_service_local_users
     #
-    #  Internally in the Scope instance:
+    # === User Groups
     #
-    #  - The limitations and exclusions that match the WebUI's 'LDAP/Local Users'
-    #    are in @limitations[:jamf_ldap_users]  and @exclusions[:jamf_ldap_users]
+    # What appears in the UI as 'User Groups' are User Group objects in Jamf Pro, both
+    # static and smart. In ruby-jss, these are Jamf::UserGroup instances.
     #
-    #  - The  limitations and exclusions that match the WebUI's 'LDAP User Groups'
-    #    are in @limitations[:ldap_user_groups]  and @exclusions[:ldap_user_groups]
+    # They will appear in the API data as \<jss_user_groups> element with \<user_group>
+    # sub-elements (XML) or the 'jss_user_groups' array (JSON). These are available as
+    # Targets or Exclusions.
     #
+    # In this class they are also referred to as 'jss_user_groups'
+    #
+    # === Directory Service User Groups
+    #
+    # When editing a scope in the UI, in Limitations and Exclusions, you can
+    # look up and add groups from any of the defined LDAP servers.
+    # These scope items are called 'Directory Service User Groups' but
+    # used to be called 'LDAP User Groups'
+    #
+    # In the API data for scopes, these items appear in the \<user_groups> element
+    # with \<user_group> sub-elements (XML) or 'user_groups' array (JSON) of the limitations
+    # and exclusions data
+    #
+    # In this class, these items ultimately use the same names they have in the API data:
+    # 'user_groups' but when specifying that you are setting that value, you can use any of
+    # these synonyms, singular or plural:
+    #     ldap_user_groups, directory_service_user_groups
+    #
+    ###################################
+    # = IMPORTANT: API BUG IN POLICY AND PATCH POLICY SCOPES - CAN CAUSE DATA LOSS
+    ###################################
+    #
+    # When you GET the data for policies and patch policies from the Classic API
+    # the scope data returned will NOT include the 'jss_users' and 'jss_user_groups'
+    # data in the targets or the exclusions, even if they are defined in the web UI.
+    #
+    # More importantly, if you try to include those in the XML when you PUT a policy
+    # back to make a change via the API, you'll get an error because the API endpoint
+    # doesn't know what <jss_users> or <jss_user_groups> elements are.
+    #
+    # Even more importanly, since you cannot include those elements in your PUT body,
+    # if they actually exist in the scope, THEY WILL BE ERASED from the actual scope,
+    # because they weren't in the PUT data.
+    # This will always happen if you include the <scope> element in your
+    # PUT data, even if you didn't change the scope.
+    #
+    # - How ruby-jss handles this bug:
+    #
+    # Fortunately the Classic API, or at least this part of it, doesn't fully adhere
+    # to the REST standards for PUT, and if you don't include the <scope> element in
+    # the XML, the server will just ignore the scope entirely, and nothing will change.
+    #
+    # We make use of that here to allow for editing Policies without fear of erasing
+    # those parts of the scope. As long as you don't change anything about the scope,
+    # there will be no <scope> element in the XML sent with a PUT, and the scope is
+    # safe from harm.
+    #
+    # If you DO change the scope of a policy, this bug cannot be avoided, and you'll
+    # delete any "User"/jss_user and "User Groups/jss_user_groups" defined in the
+    # targets or exclusions.
+    #
+    # By default, if you try to change the scope of a Policy of PatchPolicy, you'll
+    # get a warning about the possibility of losing data when you save.
+    #
+    # You can supress those warnings either by supressing all ruby warnings, or
+    # by calling Jamf::Scopable::Scope.do_not_warn_about_policy_scope_bugs
+    #
+    ###################################
+    # = IMPORTANT: API BUG IN OSX CONFIG PROFILE SCOPES - CAN CAUSE DATA LOSS
+    ###################################
+    #
+    # When fetching the data for OSX Configuration Profiles using JSON (which ruby-jss does)
+    # and the scope of the profile contains more than one `jss_user_groups` as a target, then
+    # only the last one will be returned. If you have more than one such group as a target, and
+    # use ruby-jss to make changes to the scope, all but the last jss_user_groups used as targets will
+    # be removed.
+    #
+    # This only appears to affect scope targets, not exclusions, and only for
+    # OSX Config Profiles. Other scopable objects that use jss_user_groups in their API data
+    # seem to be OK.
+    #
+    # This is due to a long-standing API bug regarding how Arrays in XML are incorrectly
+    # translated into Hashes of a single Hash when returning the data as JSON - they shoud be
+    # Arrays of Hashes in JSON - one hash for each item.
+    #
+    # Even though this bug was first reported to jamf in 2009, it still appears in many places throughout
+    # the Classic API.  ruby-jss works around some of the worst instances of the bug, but such workarounds
+    # are complex requiring re-fetching the data in XML and parsing it manually. At the moment there are no
+    # plans to do that for this specific scope bug.
+    #
+    # By default, if you try to change the scope of an object affected by this bug, you'll
+    # get a warning about the possibility of losing data when you save.
+    #
+    # You can supress those warnings either by supressing all ruby warnings, or
+    # by calling Jamf::Scopable::Scope.do_not_warn_about_array_hash_scope_bugs
+    #
+    ########################
     #
     # @see Jamf::Scopable
     #
@@ -133,38 +191,93 @@ module Jamf
 
       # These are the classes that Scopes can use for defining a scope,
       # keyed by appropriate symbols.
-      # NOTE: All the user and group ones don't actually refer to
-      # Jamf::User or Jamf::UserGroup. See IMPORTANT discussion above.
+      #
+      # synonyms, including singular/plural forms, are used to allow for
+      # more natural language when specifying these scope entities. The
+      # key used in the actual API data is usually the plural.
+      #
+      # NOTE: user[s] and user_group[s] in Scope data refer to
+      # 'Directory Service/Local User' and 'Directory Service User Group'
+      # as labeled in the web-ui. These were formerly labeled
+      # as 'LDAP/Local User' and 'LDAP User Group'.
+      #
       SCOPING_CLASSES = {
         computers: Jamf::Computer,
         computer: Jamf::Computer,
+
         computer_groups: Jamf::ComputerGroup,
         computer_group: Jamf::ComputerGroup,
+
         mobile_devices: Jamf::MobileDevice,
         mobile_device: Jamf::MobileDevice,
+
         mobile_device_groups: Jamf::MobileDeviceGroup,
         mobile_device_group: Jamf::MobileDeviceGroup,
+
         buildings: Jamf::Building,
         building: Jamf::Building,
+
         departments: Jamf::Department,
         department: Jamf::Department,
+
         network_segments: Jamf::NetworkSegment,
         network_segment: Jamf::NetworkSegment,
-        ibeacon: Jamf::IBeacon,
+
         ibeacons: Jamf::IBeacon,
-        user: nil,
+        ibeacon: Jamf::IBeacon,
+
+        jss_users: Jamf::User,
+        jss_user: Jamf::User,
+
+        jss_user_groups: Jamf::UserGroup,
+        jss_user_group: Jamf::UserGroup,
+
         users: nil,
-        ldap_user: nil,
+        user: nil,
         ldap_users: nil,
-        jamf_ldap_user: nil,
+        ldap_user: nil,
         jamf_ldap_users: nil,
-        user_group: nil,
+        jamf_ldap_user: nil,
+        directory_service_local_users: nil,
+        directory_service_local_user: nil,
+
         user_groups: nil,
+        user_group: nil,
+        ldap_user_groups: nil,
         ldap_user_group: nil,
-        ldap_user_groups: nil
+        directory_service_user_groups: nil,
+        directory_service_user_group: nil
       }.freeze
 
-      # These keys always mean :jamf_ldap_users
+      # These classes are affected by the jss_users/jss_user_groups bug.
+      #
+      # They do not accept jss_users or jss_user_groups in their targets or
+      # exclusions, and editing their scope via the API will always delete those
+      # items from the scope if they exist.
+      #
+      # See discussion in the Scope class comments.
+      JAMF_DATA_LOSS_BUG_CLASSES = [
+        Jamf::Policy,
+        Jamf::PatchPolicy
+      ].freeze
+
+      # The classes affected by the jss_users/jss_user_groups bug do not
+      # include these items in their Target or Exclusion API data, even if
+      # the scope has such items defined in the JSS
+      #
+      # See discussion in the Scope class comments.
+      JAMF_DATA_LOSS_BUG_KEYS = %i[jss_users jss_user_groups].freeze
+
+      # In the API data for limitations and exclusions
+      # 'users' is what appears as Directory Service/Local Users in the web UI
+      # and 'user_groups' appears as 'Directory Service User Groups'.
+      #
+      # Contrasted with 'jss_users' and 'jss_user_groups' in the API data for
+      # targets and exlcusions, which are Jamf::User and Jamf::UserGroup objects.
+      #
+      LDAP_BASED_KEYS = %i[users user_groups].freeze
+
+      # These keys always mean :users
       LDAP_JAMF_USER_KEYS = %i[
         user
         users
@@ -172,14 +285,18 @@ module Jamf
         ldap_users
         jamf_ldap_user
         jamf_ldap_users
+        directory_service_local_user
+        directory_service_local_users
       ].freeze
 
-      # These keys always mean :ldap_user_groups
+      # These keys always mean :user_groups
       LDAP_GROUP_KEYS = %i[
         user_group
         user_groups
         ldap_user_group
         ldap_user_groups
+        directory_service_user_group
+        directory_service_user_groups
       ].freeze
 
       # This hash maps the availble Scope Target keys from SCOPING_CLASSES to
@@ -189,9 +306,12 @@ module Jamf
       # added to the ends of singular key names if needed, e.g. computer_group => computer_groups
       ESS = 's'.freeze
 
-      # These can be part of the base inclusion list of the scope,
+      # These can be part of the base target list of the scope,
       # along with the appropriate target and target group keys
-      INCLUSIONS = %i[buildings departments].freeze
+      TARGETS = %i[buildings departments jss_users jss_user_groups].freeze
+
+      # Backward Compatibility
+      INCLUSIONS = TARGETS
 
       # These can limit the inclusion list
       # These are the keys that come from the API
@@ -201,21 +321,47 @@ module Jamf
       LIMITATIONS = %i[
         ibeacons
         network_segments
-        jamf_ldap_users
-        ldap_user_groups
+        users
+        user_groups
       ].freeze
 
       # any of them can be excluded
-      EXCLUSIONS = INCLUSIONS + LIMITATIONS
+      EXCLUSIONS = TARGETS + LIMITATIONS
 
       # Here's a default scope as it might come from the API.
       DEFAULT_SCOPE = {
-        all_computers: true,
-        all_mobile_devices: true,
+        all_computers: false,
+        all_mobile_devices: false,
         limitations: {},
         exclusions: {}
       }.freeze
 
+      # Class Methods
+      ######################
+
+      # call this to suppress warnings about data loss bug in
+      # Policy and Patch Policy scopes
+      def self.do_not_warn_about_policy_scope_bugs
+        @do_not_warn_about_policy_scope_bugs = true
+      end
+
+      # Has do_not_warn_about_policy_scope_bugs been set?
+      def self.do_not_warn_about_policy_scope_bugs?
+        @do_not_warn_about_policy_scope_bugs
+      end
+
+      # call this to suppress warnings about data loss bug in
+      # OSXConfigurationProfile scopes when there are jss_user_groups
+      # used as targets
+      def self.do_not_warn_about_array_hash_scope_bugs
+        @do_not_warn_about_array_hash_scope_bugs = true
+      end
+
+      # Has do_not_warn_about_policy_scope_bugs been set?
+      def self.do_not_warn_about_array_hash_scope_bugs?
+        @do_not_warn_about_array_hash_scope_bugs
+      end
+
       # Attributes
       ######################
 
@@ -257,6 +403,9 @@ module Jamf
       # - :group_targets - a synonym for :computer_groups or :mobile_device_groups
       # - :departments
       # - :buildings
+      # - :jss_users
+      # - :jss_user_groups
+      #
       # and the values are Arrays of names of those things.
       #
       # @return [Hash{Symbol: Array<Integer>}]
@@ -268,8 +417,9 @@ module Jamf
       #
       # The arrays of ids are:
       # - :network_segments
-      # - :jamf_ldap_users
+      # - :users
       # - :user_groups
+      # - :ibeacons
       #
       # @return [Hash{Symbol: Array<Integer, String>}]
       attr_reader :limitations
@@ -284,37 +434,64 @@ module Jamf
       # - :departments
       # - :buildings
       # - :network_segments
+      # - :jss_users
+      # - :jss_user_groups
       # - :users
-      # - :user_groups
-      #
+      # - :user_groups      #
       # @return [Hash{Symbol: Array<Integer, String>}]
       attr_reader :exclusions
 
+      # @return [Boolean] Have changes been made to the scope, that need
+      #   to be sent to the server?
+      attr_accessor :should_update
+      alias should_update? should_update
+
       # Public Instance Methods
       #####################################
 
-      # If raw_scope is empty, a default scope, scoped to all targets, is created, and can be modified
+      # If raw_scope is empty, a default scope, scoped to no targets, is created, and can be modified
       # as needed.
       #
-      # @param target_key[Symbol] the kind of thing we're scoping, one of {TARGETS_AND_GROUPS}
+      # @param target_key[Symbol] the kind of thing we're scoping, a key from {TARGETS_AND_GROUPS}
       #
       # @param raw_scope[Hash] the JSON :scope data from an API query that is scopable, e.g. a Policy.
       #
-      def initialize(target_key, raw_scope = nil)
+      # @param container[Jamf::APIObject] The scopable object to which this scope belongs, e,g, an
+      #   instance of Jamf::Policy, Jamf::MobileDeviceApplication, etc.. If not provided, will be
+      #   set automatically after initialization
+      #
+      ###########################
+      def initialize(target_key, raw_scope = nil, container: nil)
         raw_scope ||= DEFAULT_SCOPE.dup
         unless TARGETS_AND_GROUPS.key?(target_key)
           raise Jamf::InvalidDataError, "The target class of a Scope must be one of the symbols :#{TARGETS_AND_GROUPS.keys.join(', :')}"
         end
 
+        @should_update = false
+        @container = container
+
         @target_key = target_key
         @target_class = SCOPING_CLASSES[@target_key]
         @group_key = TARGETS_AND_GROUPS[@target_key]
         @group_class = SCOPING_CLASSES[@group_key]
 
-        @target_keys = [@target_key, @group_key] + INCLUSIONS
+        @target_keys = [@target_key, @group_key] + TARGETS
         @exclusion_keys = [@target_key, @group_key] + EXCLUSIONS
 
-        @all_key = "all_#{target_key}".to_sym
+        if JAMF_DATA_LOSS_BUG_CLASSES.include?(@container.class)
+          @target_keys -= JAMF_DATA_LOSS_BUG_KEYS
+          @exclusion_keys -= JAMF_DATA_LOSS_BUG_KEYS
+        end
+
+        parse_targets(raw_scope)
+        parse_limitations(raw_scope)
+        parse_exclusions(raw_scope)
+      end # init
+
+      # parse the targets from the init data
+      ###########################
+      def parse_targets(raw_scope)
+        @all_key = "all_#{@target_key}".to_sym
         @all_targets = raw_scope[@all_key]
 
         # Everything gets mapped from an Array of Hashes to
@@ -322,73 +499,64 @@ module Jamf
         @targets = {}
         @target_keys.each do |k|
           raw_scope[k] ||= []
-          @targets[k] = raw_scope[k].compact.map { |n| n[:id].to_i }
+          @targets[k] =
+            if raw_scope[k].is_a? Array
+              # the data should be an array of hashes with :id and :name
+              raw_scope[k].compact.map { |n| n[:id].to_i }
+
+            elsif raw_scope[k].is_a? Hash
+              # its a hash of hashes, it suffers the 2009 XML->JSON Array bug and
+              # there will be data loss of any more than one item.
+              # We know this to be the case for OSXConfigProfiles using
+              # jss_user_groups as targets. When used as exclusions, they are
+              # the correct array of hashes
+              @array_hash_bug_target_key = k unless raw_scope[k].empty?
+              raw_scope[k].values.compact.map { |n| n[:id].to_i }
+            else
+              []
+            end
           @targets[:direct_targets] = @targets[k] if k == @target_key
           @targets[:group_targets] = @targets[k] if k == @group_key
         end # @target_keys.each do |k|
+      end
+      private :parse_targets
 
-        # the  :users key from the API is what we call :jamf_ldap_users
-        # and the :user_groups key from the API we call :ldap_user_groups
-        # See the IMPORTANT discussion above.
+      # parse the limitations from the init data
+      ###########################
+      def parse_limitations(raw_scope)
         @limitations = {}
-        if raw_scope[:limitations]
-
-          LIMITATIONS.each do |k|
-            # :jamf_ldap_users comes from :users in the API data
-            if k == :jamf_ldap_users
-              api_data = raw_scope[:limitations][:users]
-              api_data ||= []
-              @limitations[k] = api_data.compact.map { |n| n[:name].to_s }
-
-            # :ldap_user_groups comes from :user_groups in the API data
-            elsif k == :ldap_user_groups
-              api_data = raw_scope[:limitations][:user_groups]
-              api_data ||= []
-              @limitations[k] = api_data.compact.map { |n| n[:name].to_s }
-
-            # others handled normally.
-            else
-              api_data = raw_scope[:limitations][k]
-              api_data ||= []
-              @limitations[k] = api_data.compact.map { |n| n[:id].to_i }
-            end
-          end # LIMITATIONS.each do |k|
-        end # if raw_scope[:limitations]
+        return unless raw_scope[:limitations]
 
-        # the  :users key from the API is what we call :jamf_ldap_users
-        # and the :user_groups key from the API we call :ldap_user_groups
-        # See the IMPORTANT discussion above.
+        LIMITATIONS.each do |k|
+          api_data = raw_scope[:limitations][k]
+          api_data ||= []
+          @limitations[k] = api_data.compact.map do |n|
+            LDAP_BASED_KEYS.include?(k) ? n[:name].to_s : n[:id].to_i
+          end
+        end # LIMITATIONS.each do |k|
+      end
+      private :parse_limitations
+
+      # parse the limitations from the init data
+      ###########################
+      def parse_exclusions(raw_scope)
         @exclusions = {}
-        if raw_scope[:exclusions]
-
-          @exclusion_keys.each do |k|
-            # :jamf_ldap_users comes from :users in the API data
-            if k == :jamf_ldap_users
-              api_data = raw_scope[:exclusions][:users]
-              api_data ||= []
-              @exclusions[k] = api_data.compact.map { |n| n[:name].to_s }
-
-            # :ldap_user_groups comes from :user_groups in the API data
-            elsif k == :ldap_user_groups
-              api_data = raw_scope[:exclusions][:user_groups]
-              api_data ||= []
-              @exclusions[k] = api_data.compact.map { |n| n[:name].to_s }
-
-            # others handled normally.
-            else
-              api_data = raw_scope[:exclusions][k]
-              api_data ||= []
-              @exclusions[k] = api_data.compact.map { |n| n[:id].to_i }
-              @exclusions[:direct_exclusions] = @exclusions[k] if k == @target_key
-              @exclusions[:group_exclusions] = @exclusions[k] if k == @group_key
-            end # if ...elsif... else
-          end # @exclusion_keys.each
-        end # if raw_scope[:exclusions]
-
-        @container = nil
-      end # init
+        return unless raw_scope[:exclusions]
 
-      # Set the scope's inclusions to all targets.
+        @exclusion_keys.each do |k|
+          api_data = raw_scope[:exclusions][k]
+          api_data ||= []
+          @exclusions[k] = api_data.compact.map do |n|
+            LDAP_BASED_KEYS.include?(k) ? n[:name].to_s : n[:id].to_i
+          end
+
+          @exclusions[:direct_exclusions] = @exclusions[k] if k == @target_key
+          @exclusions[:group_exclusions] = @exclusions[k] if k == @group_key
+        end # @exclusion_keys.each
+      end
+      private :parse_exclusions
+
+      # Set the scope's targets to all.
       #
       # By default, the limitations and exclusions remain.
       # If a non-false parameter is provided, they will be removed also.
@@ -408,7 +576,7 @@ module Jamf
           @exclusions = {}
           @exclusion_keys.each { |k| @exclusions[k] = [] }
         end
-        @container&.should_update
+        note_pending_changes
       end
       alias include_all set_all_targets
 
@@ -455,7 +623,7 @@ module Jamf
 
         @targets[key] = list
         @all_targets = false
-        @container&.should_update
+        note_pending_changes
       end # sinclude_in_scope
       alias set_target set_targets
       alias set_inclusion set_targets
@@ -472,7 +640,7 @@ module Jamf
           set_all_targets
         else
           @all_targets = false
-          @container&.should_update
+          note_pending_changes
         end
       end
 
@@ -511,7 +679,7 @@ module Jamf
 
         @targets[key] << item_id
         @all_targets = false
-        @container&.should_update
+        note_pending_changes
       end
       alias add_inclusion add_target
 
@@ -533,7 +701,7 @@ module Jamf
         return unless @targets[key]&.include?(item_id)
 
         @targets[key].delete item_id
-        @container&.should_update
+        note_pending_changes
       end
       alias remove_inclusion remove_target
 
@@ -553,7 +721,7 @@ module Jamf
       #
       # @todo  handle ldap user group lookups
       #
-      def set_limitation(key, list)
+      def set_limitations(key, list)
         key = pluralize_key(key)
         raise Jamf::InvalidDataError, "List must be an Array of #{key} identifiers, it may be empty." unless list.is_a? Array
 
@@ -570,9 +738,9 @@ module Jamf
         return nil if list.sort == @limitations[key].sort
 
         @limitations[key] = list
-        @container&.should_update
+        note_pending_changes
       end # set_limitation
-      alias set_limitations set_limitation
+      alias set_limitation set_limitations
 
       # Add a single item for limiting this scope.
       #
@@ -599,7 +767,7 @@ module Jamf
         end
 
         @limitations[key] << item_id
-        @container&.should_update
+        note_pending_changes
       end
 
       # Remove a single item for limiting this scope.
@@ -622,7 +790,7 @@ module Jamf
         return unless @limitations[key]&.include?(item_id)
 
         @limitations[key].delete item_id
-        @container&.should_update
+        note_pending_changes
       end ###
 
       # Replace an exclusion list for this scope
@@ -639,7 +807,7 @@ module Jamf
       #
       # @return [void]
       #
-      def set_exclusion(key, list)
+      def set_exclusions(key, list)
         key = pluralize_key(key)
         raise Jamf::InvalidDataError, "List must be an Array of #{key} identifiers, it may be empty." unless list.is_a? Array
 
@@ -662,8 +830,9 @@ module Jamf
         return nil if list.sort == @exclusions[key].sort
 
         @exclusions[key] = list
-        @container&.should_update
-      end # limit scope
+        note_pending_changes
+      end # set_exclusion
+      alias set_exclusion set_exclusions
 
       # Add a single item for exclusions of this scope.
       #
@@ -688,7 +857,7 @@ module Jamf
         raise Jamf::AlreadyExistsError, "Can't exclude #{key} '#{item}' because it's already an explicit limitation." if @limitations[key]&.include?(item)
 
         @exclusions[key] << item_id
-        @container&.should_update
+        note_pending_changes
       end
 
       # Remove a single item for exclusions of this scope
@@ -708,7 +877,7 @@ module Jamf
         return unless @exclusions[key]&.include?(item_id)
 
         @exclusions[key].delete item_id
-        @container&.should_update
+        note_pending_changes
       end
 
       # @api private
@@ -726,20 +895,24 @@ module Jamf
           list.compact!
           list.delete 0
           list_as_hashes = list.map { |i| { id: i } }
-          scope << SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+
+          xml_list = SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+          xml_list.name = 'jss_users' if SCOPING_CLASSES[klass] == Jamf::User
+          xml_list.name = 'jss_user_groups' if SCOPING_CLASSES[klass] == Jamf::UserGroup
+          scope << xml_list
         end
 
         limitations = scope.add_element('limitations')
         @limitations.each do |klass, list|
           list.compact!
           list.delete 0
-          if klass == :jamf_ldap_users
+          if klass == :users
             users_xml = limitations.add_element 'users'
             list.each do |name|
               user_xml = users_xml.add_element 'user'
               user_xml.add_element('name').text = name
             end
-          elsif klass == :ldap_user_groups
+          elsif klass == :user_groups
             user_groups_xml = limitations.add_element 'user_groups'
             list.each do |name|
               user_group_xml = user_groups_xml.add_element 'user_group'
@@ -756,13 +929,13 @@ module Jamf
           list = @exclusions[klass]
           list.compact!
           list.delete 0
-          if klass == :jamf_ldap_users
+          if klass == :users
             users_xml = exclusions.add_element 'users'
             list.each do |name|
               user_xml = users_xml.add_element 'user'
               user_xml.add_element('name').text = name
             end
-          elsif klass == :ldap_user_groups
+          elsif klass == :user_groups
             user_groups_xml = exclusions.add_element 'user_groups'
             list.each do |name|
               user_group_xml = user_groups_xml.add_element 'user_group'
@@ -770,13 +943,18 @@ module Jamf
             end
           else
             list_as_hashes = list.map { |i| { id: i } }
-            exclusions << SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+
+            xml_list = SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+            xml_list.name = 'jss_users' if SCOPING_CLASSES[klass] == Jamf::User
+            xml_list.name = 'jss_user_groups' if SCOPING_CLASSES[klass] == Jamf::UserGroup
+            exclusions << xml_list
+
           end
         end
         scope
       end # scope_xml
 
-      # Remove the init_data and api object from
+      # Remove large or redundant data structures from
       # the instance_variables used to create
       # pretty-print (pp) output.
       #
@@ -869,28 +1047,41 @@ module Jamf
       #
       def validate_item(realm, key, ident, error_if_not_found: true)
         # which keys allowed depends on how the item is used...
+        # Classes susceptible to the Data Loss Bug have JAMF_DATA_LOSS_BUG_KEYS
+        # removed from the possible keys.
         possible_keys =
           case realm
-          when :target then @target_keys
-          when :limitation then LIMITATIONS
-          when :exclusion then @exclusion_keys
+          when :target
+            JAMF_DATA_LOSS_BUG_CLASSES.include?(@container.class) ? (@target_keys - JAMF_DATA_LOSS_BUG_KEYS) : @target_keys
+          when :limitation
+            LIMITATIONS
+          when :exclusion
+            JAMF_DATA_LOSS_BUG_CLASSES.include?(@container.class) ? (@exclusion_keys - JAMF_DATA_LOSS_BUG_KEYS) : @exclusion_keys
           else
             raise ArgumentError, 'Unknown realm, must be :target, :limitation, or :exclusion'
           end
 
         key = pluralize_key(key)
 
-        raise Jamf::InvalidDataError, "#{realm} key must be one of :#{possible_keys.join(', :')}" \
-          unless possible_keys.include? key
+        unless possible_keys.include? key
+          msg = "#{realm} key must be one of :#{possible_keys.join(', :')}."
+          if JAMF_DATA_LOSS_BUG_CLASSES.include?(@container.class) && JAMF_DATA_LOSS_BUG_KEYS.include?(key)
+            msg = "#{msg}\nJAMF BUG WARNING: The API cannot handle :jss_users or :jss_user_groups in scope targets or exclusions of Policies or Patch Policies. If any exist in the scope they will be deleted when you save any changes to the policy via the API."
+          end
+          raise Jamf::InvalidDataError, msg
+        end
 
         id = nil
 
         # id will be a string
-        if key == :jamf_ldap_users
-          id = ident if Jamf::User.all_names(:refresh, cnx: container.cnx).include?(ident) || Jamf::LdapServer.user_in_ldap?(ident)
+        if key == :users
+          id = ident
+        # the web UI doesn't validate this data, it accepts any string, so we do too
+        # id = ident if Jamf::User.all_names(:refresh, cnx: container.cnx).include?(ident) || Jamf::LdapServer.user_in_ldap?(ident)
 
         # id will be a string
-        elsif key == :ldap_user_groups
+        elsif key == :user_groups
+          # The web UI does validate that the group exists in LDAP
           id = ident if Jamf::LdapServer.group_in_ldap? ident, cnx: container.cnx
 
         # id will be an integer
@@ -905,11 +1096,12 @@ module Jamf
 
       # the symbols used in the API data are plural, e.g. 'network_segments'
       # this will pluralize them, allowing us to use singulars as well.
+      # This also handles the synonyms for users and user_groups
       def pluralize_key(key)
         if LDAP_JAMF_USER_KEYS.include? key
-          :jamf_ldap_users
+          :users
         elsif LDAP_GROUP_KEYS.include? key
-          :ldap_user_groups
+          :user_groups
         else
           key.to_s.end_with?(ESS) ? key : "#{key}s".to_sym
         end
@@ -1161,8 +1353,39 @@ module Jamf
         false
       end
 
+      # make a note both in this instance and in our container
+      # that a change has been made and an update is needed
+      def note_pending_changes
+        warn_about_data_loss_bug
+        warn_about_array_hash_bug
+        @should_update = true
+        @container&.should_update
+      end
+
+      # display data loss warning.
+      def warn_about_data_loss_bug
+        return unless JAMF_DATA_LOSS_BUG_CLASSES.include?(@container.class)
+        return if Jamf::Scopable::Scope.do_not_warn_about_policy_scope_bugs?
+        return if @warn_about_data_loss_bug_has_run
+
+        warn "WARNING: Saving changes to this scope may cause data loss!\nDue to a bug in the Classic API, if the scope uses Jamf Users or User Groups in the Targets or Exclusions, they will be deleted from the scope when you save!"
+
+        @warn_about_data_loss_bug_has_run = true
+      end
+
+      # display warning about array-hash bug data loss
+      def warn_about_array_hash_bug
+        return unless @array_hash_bug_target_key
+        return if Jamf::Scopable::Scope.do_not_warn_about_array_hash_scope_bugs?
+        return if @warn_about_array_hash_bug_has_run
+
+        warn "WARNING: At least one #{@array_hash_bug_target_key} is used as a scope target.\nDue to a bug in the Classic API, if you save changes to this scope, all but the last #{@array_hash_bug_target_key} will be deleted from the scope targets when you save!"
+
+        @warn_about_array_hash_bug_has_run = true
+      end
+
     end # class Scope
 
   end # module Scopable
 
-end # module
+end # moduleß

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

@@ -75,8 +75,8 @@ module Jamf
     ### @return [void]
     ###
     def parse_scope
-      @scope = Jamf::Scopable::Scope.new self.class::SCOPE_TARGET_KEY, @init_data[:scope]
-      @scope.container = self
+      @scope = Jamf::Scopable::Scope.new self.class::SCOPE_TARGET_KEY, @init_data[:scope], container: self
+      @scope.container ||= self
     end
 
     ### Change the scope
@@ -85,9 +85,14 @@ module Jamf
     ###
     ### @return [void]
     ###
-    def scope= (new_scope)
-      raise Jamf::InvalidDataError, "Jamf::Scopable::Scope instance required" unless new_criteria.kind_of?(Jamf::Scopable::Scope)
-      raise Jamf::InvalidDataError, "Scope object must have target_key of :#{self.class::SCOPE_TARGET_KEY}" unless self.class::SCOPE_TARGET_KEY == new_scope.target_key
+    def scope=(new_scope)
+      raise Jamf::InvalidDataError, 'Jamf::Scopable::Scope instance required' unless new_criteria.is_a?(Jamf::Scopable::Scope)
+
+      unless self.class::SCOPE_TARGET_KEY == new_scope.target_key
+        raise Jamf::InvalidDataError,
+              "Scope object must have target_key of :#{self.class::SCOPE_TARGET_KEY}"
+      end
+
       @scope = new_scope
       @need_to_update = true
     end
@@ -105,13 +110,13 @@ module Jamf
     #
     def update
       super
-    rescue Jamf::ConflictError => conflict
-      if scope.unable_to_verify_ldap_entries == true
-        raise Jamf::InvalidDataError, "Potentially non-existant LDAP user or group in new scope values."
-      else
-        raise conflict
-      end
+      @scope.should_update = false
+    rescue Jamf::ConflictError => e
+      raise Jamf::InvalidDataError, 'Potentially non-existant LDAP user or group in new scope values.' if scope.unable_to_verify_ldap_entries == true
+
+      raise e
     end # update
 
   end # module Scopable
+
 end # module Jamf

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

@@ -222,9 +222,8 @@ module Jamf
     # @return [Jamf::DeviceEnrollmentDevice, nil] the device as known to DEP
     #
     def self.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx)
-      sn.upcase! # SNs from apple are always uppercase
       devs = devices(instance, refresh: refresh, cnx: cnx)
-      devs.select { |d| d.serialNumber == sn }.first
+      devs.select { |d| d.serialNumber.casecmp? sn }.first
     end
 
     # The history of sync operations between Apple and a given DeviceEnrollment

data/lib/jamf/version.rb

@@ -27,6 +27,6 @@
 module Jamf
 
   ### The version of ruby-jss
-  VERSION = '3.1.0b2'.freeze
+  VERSION = '3.2.0b3'.freeze
 
 end # module

data/test/tests/policy.rb

@@ -38,20 +38,6 @@ module JamfTest
     def run_class_tests
       # policies are special so we define all the object tests here
       run_collection_tests do_object_tests: false
-
-      create_new
-
-      add_data_to_new
-
-      # save_new
-      # fetch_new
-      # validate_fetched
-      # modify_fetched
-      # re_save_fetched
-      # re_fetch
-      # validate_changes
-      # delete
-      # confirm_deleted
     end
 
     #################

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 3.1.0b2
+  version: 3.2.0b3
 platform: ruby
 authors:
 - Chris Lasell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-02 00:00:00.000000000 Z
+date: 2023-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: CFPropertyList