ruby-jss 1.2.4a4 → 1.2.6

data/lib/jamf/api/connection/token.rb

@@ -30,6 +30,8 @@ module Jamf
     # A token used for a JSS connection
     class Token
 
+      JAMF_VERSION_RSRC = 'v1/jamf-pro-version'.freeze
+
       AUTH_RSRC = 'auth'.freeze
 
       NEW_TOKEN_RSRC = "#{AUTH_RSRC}/tokens".freeze
@@ -56,9 +58,22 @@ module Jamf
       # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/uapi
       attr_reader :base_url
 
-      # when was this token created?
+      # @return [Jamf::Timestamp] when was this token created?
       attr_reader :login_time
 
+      # What happened the last time we tried to refresh?
+      #   :expired_refreshed - token was expired, a new token was created with the pw
+      #   :expired_pw_failed - token was expired, pw failed to make a new token
+      #   :expired_no_pw - token was expired, but no pw was given to make a new one
+      #   :refreshed - the token refresh worked with no need for the pw
+      #   :refresh_failed - the token refresh failed, and no pw was given to make a new one
+      #   :refreshed_with_pw - the token refresh failed, pw worked to make a new token
+      #   :refresh_failed_no_pw - the token refresh failed, pw also failed to make a new token
+      #   nil - no refresh has been attempted for this token.
+      #
+      # @return [Symbol, nil] :refreshed, :pw, :expired,:failed, or nil if never refreshed
+      attr_reader :last_refresh_result
+
       def initialize(**params)
         @valid = false
         @user = params[:user]
@@ -90,7 +105,7 @@ module Jamf
           raise Jamf::AuthenticationError, 'Incorrect name or password'
         else
           # TODO: better error reporting here
-          raise 'An error occurred while authenticating'
+          raise Jamf::AuthenticationError, 'An error occurred while authenticating'
         end
       end # init_from_pw
 
@@ -118,8 +133,13 @@ module Jamf
       end
 
       # @return [String]
-      def api_version
-        token_connection(Jamf::Connection::SLASH, token: @auth_token).get.body[:version]
+      def jamf_version
+        raw_jamf_version.split('-').first
+      end
+
+      # @return [String]
+      def jamf_build
+        raw_jamf_version.split('-').last
       end
 
       # @return [Boolean]
@@ -165,18 +185,39 @@ module Jamf
         @account = Jamf::APIAccount.new resp.body
       end
 
-      # Use this token to get a fresh one
-      # TODO: better error reporting
-      def refresh
-        raise 'Token has expired' if expired?
+      # Use this token to get a fresh one. If a pw is provided
+      # try to use it to get a new token if a proper refresh fails.
+      #
+      # @param pw [String] Optional password to use if token refresh fails.
+      #   Must be the correct passwd or the token's user (obviously)
+      #
+      # @return [Jamf::Timestamp] the new expiration time
+      #
+      def refresh(pw = nil)
+        # gotta have a pw if expired
+        if expired?
+          # try the passwd
+          return refresh_with_passwd(pw, :expired_refreshed, :expired_pw_failed) if pw
+
+          # no passwd? no chance!
+          @last_refresh_result = :expired_no_pw
+          raise Jamf::InvalidTokenError, 'Token has expired'
+        end
 
+        # Now try a normal refresh of our non-expired token
         keep_alive_token_resp = token_connection(KEEP_ALIVE_RSRC, token: @auth_token).post
+        if keep_alive_token_resp.success?
+          parse_token_from_response keep_alive_token_resp
+          @last_refresh_result = :refreshed
+          return expires
+        end
 
-        raise 'An error occurred while authenticating' unless keep_alive_token_resp.success?
+        # if we're here, the normal refresh failed, so try the pw
+        return refresh_with_passwd(pw, :refreshed_with_pw, :refresh_failed_no_pw) if pw
 
-        parse_token_from_response keep_alive_token_resp
-        # parse_token_from_response keep_alive_rsrc.post('')
-        expires
+        # if we're here, no pw? no chance!
+        @last_refresh_result = :refresh_failed
+        raise 'An error occurred while refreshing the token' unless pw
       end
       alias keep_alive refresh
 
@@ -190,6 +231,32 @@ module Jamf
       #################################
       private
 
+      # refresh a token using a password, return a result
+      # @param pw[String] the password to use
+      # @return [JamfTimestamp] the new expiration
+      def refresh_with_passwd(pw, success, failure)
+        init_from_pw(pw)
+        @last_refresh_result = success
+        expires
+      rescue => e
+        @last_refresh_result = failure
+        raise e, "#{e}. Status: :#{failure}"
+      end
+
+      # @return [String]
+      def raw_jamf_version
+        # TODO: Remove this once we require Jamf Pro 10.19 and up
+        # the rsrc for getting the version used to be nothing (the
+        # base url itself returnedit) but now its JAMF_VERSION_RSRC
+        resp = token_connection(Jamf::BLANK, token: @auth_token).get # .body # [:version]
+        return resp.body[:version] if resp.success?
+
+        resp = token_connection(JAMF_VERSION_RSRC, token: @auth_token).get
+        return resp.body[:version] if resp.success?
+
+        raise Jamf::InvalidConnectionError, 'Unable to read Jamf version from the API'
+      end
+
       # a generic, one-time Faraday connection for token
       # acquision & manipulation
       #

data/lib/jamf/api/resources/collection_resources/inventory_preload_record.rb

@@ -224,7 +224,7 @@ module Jamf
       extensionAttributes: {
         class: Jamf::InventoryPreloadExtensionAttribute,
         multi: true,
-        aliases: %i[ext_attrs eas]
+        aliases: %i[eas]
       }
 
     }.freeze
@@ -251,6 +251,13 @@ module Jamf
       extensionAttributes_delete_at idx if idx
     end
 
+    # a Hash of ea name => ea_value for all eas currently set.
+    def ext_attrs
+      eas = {}
+      extensionAttributes.each { |ea| eas[ea.name] = ea.value }
+      eas
+    end
+
     # clear all values for this record except id, serialNumber, and deviceType
     def clear
       OBJECT_MODEL.keys.each do |attr|

data/lib/jamf/exceptions.rb

@@ -82,6 +82,11 @@ module Jamf
   #
   class AuthenticationError < RuntimeError; end
 
+  # InvalidTokenError - raise this when a connection token is
+  # expired or otherwise invalid
+  #
+  class InvalidTokenError < RuntimeError; end
+
   # ConflictError - raise this when
   # attempts to PUT or PUSH to the API
   # result in a 409 Conflict http error.

data/lib/jamf/version.rb

@@ -27,6 +27,6 @@
 module Jamf
 
   ### The version of the Jamf module
-  VERSION = '0.0.0a3'.freeze
+  VERSION = '0.0.1'.freeze
 
 end # module

data/lib/jss.rb

@@ -194,8 +194,9 @@ module JSS
   class Category < JSS::APIObject; end
   class Computer < JSS::APIObject; end
   class Department < JSS::APIObject; end
-  class EBook < JSS::APIObject; end
   class DistributionPoint < JSS::APIObject; end
+  class EBook < JSS::APIObject; end
+  class IBeacon < JSS::APIObject; end
   class LDAPServer < JSS::APIObject; end
   class MacApplication < JSS::APIObject; end
   class MobileDevice < JSS::APIObject; end

data/lib/jss/api_object/criteriable.rb

@@ -152,21 +152,26 @@ module JSS
     # @return [void]
     #
     def parse_criteria
-      @criteria = (JSS::Criteriable::Criteria.new @init_data[:criteria].map { |c| JSS::Criteriable::Criterion.new c } if @init_data[:criteria])
-      @criteria.container = self if @criteria
+      @criteria = JSS::Criteriable::Criteria.new
+      @criteria.criteria = @init_data[:criteria].map { |c| JSS::Criteriable::Criterion.new c } if @init_data[:criteria]
+
+      @criteria.container = self
     end
 
     #
     # Change the criteria, it must be a JSS::Criteriable::Criteria instance
     #
-    # @param new_criteria[JSS::Criteriable::Criteria] the new criteria
+    # @param new_criteria[JSS::Criteriable::Criteria, nil] the new criteria. An
+    #   empty criteria object is used if nil is passed.
     #
     # @return [void]
     #
     def criteria=(new_criteria)
+      new_criteria ||= JSS::Criteriable::Criteria.new
       raise JSS::InvalidDataError, 'JSS::Criteriable::Criteria instance required' unless new_criteria.is_a?(JSS::Criteriable::Criteria)
+
       @criteria = new_criteria
-      @criteria.container = self
+      @criteria.container = self unless new_criteria.nil?
       @need_to_update = true
     end
 

data/lib/jss/api_object/criteriable/criteria.rb

@@ -72,21 +72,18 @@ module JSS
       attr_reader :criteria
 
       ### @return [JSS::APIObject subclass] a reference to the object containing these Criteria
-      attr_reader :container
+      attr_writer :container
 
       ###
       ### @param new_criteria[Array<JSS::Criteriable::Criterion>]
       ###
-      def initialize(new_criteria)
+      def initialize(new_criteria = [])
         @criteria = []
+
+        # validates the param and fills @criteria
         self.criteria = new_criteria
       end # init
 
-      ### set the object we belong to, so we can set its @should_update value
-      def container= (a_thing)
-        @container = a_thing
-      end
-
       ###
       ### Provide a whole new array of JSS::Criteriable::Criterion instances for this Criteria
       ###
@@ -94,7 +91,7 @@ module JSS
       ###
       ### @return [void]
       ###
-      def criteria= (new_criteria)
+      def criteria=(new_criteria)
         unless new_criteria.is_a?(Array) && new_criteria.reject { |c| c.is_a?(JSS::Criteriable::Criterion) }.empty?
           raise JSS::InvalidDataError, 'Argument must be an Array of JSS::Criteriable::Criterion instances.'
         end
@@ -104,6 +101,14 @@ module JSS
         @container.should_update if @container
       end
 
+      # Remove all criterion objects
+      #
+      # @return [void]
+      def clear
+        @criteria = []
+        @container.should_update if @container
+      end
+
       ###
       ### Add a new criterion to the end of the criteria
       ###
@@ -192,6 +197,18 @@ module JSS
         @criteria.each_index { |ci| @criteria[ci].priority = ci }
       end
 
+      # Remove the various cached data
+      # from the instance_variables used to create
+      # pretty-print (pp) output.
+      #
+      # @return [Array] the desired instance_variables
+      #
+      def pretty_print_instance_variables
+        vars = instance_variables.sort
+        vars.delete :@container
+        vars
+      end
+
       ###
       ### @return [REXML::Element] the xml element for the criteria
       ###
@@ -200,7 +217,6 @@ module JSS
       ### @api private
       ###
       def rest_xml
-        raise JSS::MissingDataError, "Criteria can't be empty" if @criteria.empty?
         cr = REXML::Element.new 'criteria'
         @criteria.each { |c| cr << c.rest_xml }
         cr

data/lib/jss/api_object/management_history.rb

@@ -293,27 +293,6 @@ module JSS
       end # completed_mdm_commands
       alias completed_commands completed_mdm_commands
 
-      # The time of the most recently completed MDM command.
-      #
-      # For Mobile Devices, this seems to be the best indicator of the real
-      # last-contact time, since the last_inventory_update is changed when
-      # changes are made via the API.
-      #
-      # @param ident [Type] The identifier for the object - id, name, sn, udid, etc.
-      #
-      # @param api [JSS::APIConnection] The API connection to use for the query
-      #   defaults to the currently active connection
-      #
-      # @return [Time, nil] An array of completed MDMCommands
-      #
-      def last_mdm_contact(ident, api: JSS.api)
-        cmds = completed_mdm_commands(ident, api: api)
-        return nil if cmds.empty?
-
-        JSS.epoch_to_time cmds.map{|cmd| cmd.completed_epoch }.max
-      end
-
-
       # The history of pending mdm commands for a target
       #
       # @param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@@ -342,6 +321,28 @@ module JSS
       end # completed_mdm_commands
       alias failed_commands failed_mdm_commands
 
+      # The time of the most recently completed or failed MDM command.
+      # (knowledge of a failure means the device communicated with us)
+      #
+      # For Mobile Devices, this seems to be the best indicator of the real
+      # last-contact time, since the last_inventory_update is changed when
+      # changes are made via the API.
+      #
+      # @param ident [Type] The identifier for the object - id, name, sn, udid, etc.
+      #
+      # @param api [JSS::APIConnection] The API connection to use for the query
+      #   defaults to the currently active connection
+      #
+      # @return [Time, nil] An array of completed MDMCommands
+      #
+      def last_mdm_contact(ident, api: JSS.api)
+        epochs = completed_mdm_commands(ident, api: api).map { |cmd| cmd.completed_epoch }
+        epochs += failed_mdm_commands(ident, api: api).map { |cmd| cmd.failed_epoch }
+        epoch = epochs.max
+        epoch ? JSS.epoch_to_time(epoch) : nil
+      end
+
+
       # The history of app store apps  for a computer
       #
       # @param ident [Type] The identifier for the object - id, name, sn, udid, etc.

data/lib/jss/api_object/mobile_device.rb

@@ -126,6 +126,10 @@ module JSS
       }
     }.freeze
 
+    HW_PREFIX_TV = 'AppleTV'.freeze
+    HW_PREFIX_IPAD = 'iPad'.freeze
+    HW_PREFIX_IPHONE = 'iPhone'.freeze
+
     NON_UNIQUE_NAMES = true
 
     # This class lets us seach for computers
@@ -489,6 +493,19 @@ module JSS
       end
     end # initialize
 
+    def tv?
+      model_identifier.start_with? HW_PREFIX_TV
+    end
+    alias apple_tv? tv?
+
+    def ipad?
+      model_identifier.start_with? HW_PREFIX_IPAD
+    end
+
+    def iphone?
+      model_identifier.start_with? HW_PREFIX_IPHONE
+    end
+
     def name=(new_name)
       super
       @needs_mdm_name_change = true if managed? && supervised?

data/lib/jss/api_object/scopable/scope.rb

@@ -41,6 +41,85 @@ module JSS
     # This class provides methods for adding, removing, or fully replacing the
     # various items in scope's realms: targets, limitations, and exclusions.
     #
+    # IMPORTANT:
+    # 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.
+    #
+    # Targets/Inclusions
+    #  - 'Users' can only be JSS::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' can only be JSS::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.
+    #
+    # 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
+    #
+    # Exclusions, combines the behavior of Inclusions & Limitations
+    #  - 'Users' can only be JSS::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' can only be JSS::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)
+    #
+    #
+    # How ruby-jss handles this:
+    #
+    #   - Methods #set_targets and #add_target will not accept the keys
+    #     :user, :users, :user_group, :user_groups.
+    #
+    #   - Method #remove_target will ignore them.
+    #
+    #   - 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 JSS::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.
+    #
+    #   - 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 JSS::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.
+    #
+    #  Internally in the Scope instance:
+    #
+    #  - The limitations and exclusions that match the WebUI's 'LDAP/Local Users'
+    #    are in @limitations[:jamf_ldap_users]  and @exclusions[:jamf_ldap_users]
+    #
+    #  - The  limitations and exclusions that match the WebUI's 'LDAP User Groups'
+    #    are in @limitations[:ldap_user_groups]  and @exclusions[:ldap_user_groups]
+    #
+    #
     # @see JSS::Scopable
     #
     class Scope
@@ -50,6 +129,8 @@ module JSS
 
       # 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
+      # JSS::User or JSS::UserGroup. See IMPORTANT discussion above.
       SCOPING_CLASSES = {
         computers: JSS::Computer,
         computer: JSS::Computer,
@@ -65,16 +146,37 @@ module JSS
         department: JSS::Department,
         network_segments: JSS::NetworkSegment,
         network_segment: JSS::NetworkSegment,
-        users: JSS::User,
-        user: JSS::User,
-        user_groups: JSS::UserGroup,
-        user_group: JSS::UserGroup
+        ibeacon: JSS::IBeacon,
+        ibeacons: JSS::IBeacon,
+        user: nil,
+        users: nil,
+        ldap_user: nil,
+        ldap_users: nil,
+        jamf_ldap_user: nil,
+        jamf_ldap_users: nil,
+        user_group: nil,
+        user_groups: nil,
+        ldap_user_group: nil,
+        ldap_user_groups: nil
       }.freeze
 
-      # Some things get checked in LDAP as well as the JSS
-      LDAP_USER_KEYS = %i[user users].freeze
-      LDAP_GROUP_KEYS = %i[user_groups user_group].freeze
-      CHECK_LDAP_KEYS = LDAP_USER_KEYS + LDAP_GROUP_KEYS
+      # These keys always mean :jamf_ldap_users
+      LDAP_JAMF_USER_KEYS = %i[
+        user
+        users
+        ldap_user
+        ldap_users
+        jamf_ldap_user
+        jamf_ldap_users
+      ].freeze
+
+      # These keys always mean :ldap_user_groups
+      LDAP_GROUP_KEYS = %i[
+        user_group
+        user_groups
+        ldap_user_group
+        ldap_user_groups
+      ].freeze
 
       # This hash maps the availble Scope Target keys from SCOPING_CLASSES to
       # their corresponding target group keys from SCOPING_CLASSES.
@@ -88,7 +190,16 @@ module JSS
       INCLUSIONS = %i[buildings departments].freeze
 
       # These can limit the inclusion list
-      LIMITATIONS = %i[network_segments users user_groups].freeze
+      # These are the keys that come from the API
+      # 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 = %i[
+        ibeacons
+        network_segments
+        jamf_ldap_users
+        ldap_user_groups
+      ].freeze
 
       # any of them can be excluded
       EXCLUSIONS = INCLUSIONS + LIMITATIONS
@@ -179,7 +290,9 @@ module JSS
       #
       def initialize(target_key, raw_scope = nil)
         raw_scope ||= DEFAULT_SCOPE.dup
-        raise JSS::InvalidDataError, "The target class of a Scope must be one of the symbols :#{TARGETS_AND_GROUPS.keys.join(', :')}" unless TARGETS_AND_GROUPS.key?(target_key)
+        unless TARGETS_AND_GROUPS.key?(target_key)
+          raise JSS::InvalidDataError, "The target class of a Scope must be one of the symbols :#{TARGETS_AND_GROUPS.keys.join(', :')}"
+        end
 
         @target_key = target_key
         @target_class = SCOPING_CLASSES[@target_key]
@@ -197,24 +310,64 @@ module JSS
         @inclusions = {}
         @inclusion_keys.each do |k|
           raw_scope[k] ||= []
-          @inclusions[k] = raw_scope[k].compact.map { |n| n[:id].to_i  }
+          @inclusions[k] = raw_scope[k].compact.map { |n| n[:id].to_i }
         end # @inclusion_keys.each do |k|
 
+        # 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 = {}
         if raw_scope[:limitations]
+
           LIMITATIONS.each do |k|
-            raw_scope[:limitations][k] ||= []
-            @limitations[k] = raw_scope[:limitations][k].compact.map { |n| n[:id].to_i }
+            # :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]
 
+        # 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.
         @exclusions = {}
         if raw_scope[:exclusions]
+
           @exclusion_keys.each do |k|
-            raw_scope[:exclusions][k] ||= []
-            @exclusions[k] = raw_scope[:exclusions][k].compact.map { |n| n[:id].to_i }
-          end
-        end
+            # :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 }
+            end # if ...elsif... else
+          end # @exclusion_keys.each
+        end # if raw_scope[:exclusions]
 
         @container = nil
       end # init
@@ -239,7 +392,7 @@ module JSS
           @exclusions = {}
           @exclusion_keys.each { |k| @exclusions[k] = [] }
         end
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # Replace a list of item names for as targets in this scope.
@@ -266,10 +419,12 @@ module JSS
         # check the idents
         list.map! do |ident|
           item_id = validate_item(:target, key, ident)
-          if @exclusions[key] && @exclusions[key].include?(item_id)
+
+          if @exclusions[key]&.include?(item_id)
             raise JSS::AlreadyExistsError, \
-              "Can't set #{key} target to '#{ident}' because it's already an explicit exclusion."
+                  "Can't set #{key} target to '#{ident}' because it's already an explicit exclusion."
           end
+
           item_id
         end # each
 
@@ -277,7 +432,7 @@ module JSS
 
         @inclusions[key] = list
         @all_targets = false
-        @container.should_update if @container
+        @container&.should_update
       end # sinclude_in_scope
       alias set_target set_targets
       alias set_inclusion set_targets
@@ -303,13 +458,13 @@ module JSS
       def add_target(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:target, key, item)
-        return if @inclusions[key] && @inclusions[key].include?(item_id)
+        return if @inclusions[key]&.include?(item_id)
 
-        raise JSS::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key] && @exclusions[key].include?(item_id)
+        raise JSS::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key]&.include?(item_id)
 
         @inclusions[key] << item_id
         @all_targets = false
-        @container.should_update if @container
+        @container&.should_update
       end
       alias add_inclusion add_target
 
@@ -328,9 +483,10 @@ module JSS
         key = pluralize_key(key)
         item_id = validate_item :target, key, item, error_if_not_found: false
         return unless item_id
-        return unless @inclusions[key] && @inclusions[key].include?(item_id)
+        return unless @inclusions[key]&.include?(item_id)
+
         @inclusions[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end
       alias remove_inclusion remove_target
 
@@ -357,14 +513,17 @@ module JSS
         # check the idents
         list.map! do |ident|
           item_id = validate_item(:limitation, key, ident)
-          raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion." if @exclusions[key] && @exclusions[key].include?(item_id)
+          if @exclusions[key]&.include?(item_id)
+            raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion."
+          end
+
           item_id
         end # each
 
         return nil if list.sort == @limitations[key].sort
 
         @limitations[key] = list
-        @container.should_update if @container
+        @container&.should_update
       end # set_limitation
       alias set_limitations set_limitation
 
@@ -386,12 +545,14 @@ module JSS
       def add_limitation(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:limitation, key, item)
-        return nil if @limitations[key] && @limitations[key].include?(item_id)
+        return nil if @limitations[key]&.include?(item_id)
 
-        raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion." if @exclusions[key] && @exclusions[key].include?(item_id)
+        if @exclusions[key]&.include?(item_id)
+          raise JSS::AlreadyExistsError, "Can't set #{key} limitation for '#{name}' because it's already an explicit exclusion."
+        end
 
         @limitations[key] << item_id
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # Remove a single item for limiting this scope.
@@ -411,9 +572,10 @@ module JSS
         key = pluralize_key(key)
         item_id = validate_item :limitation, key, item, error_if_not_found: false
         return unless item_id
-        return unless @limitations[key] && @limitations[key].include?(item_id)
+        return unless @limitations[key]&.include?(item_id)
+
         @limitations[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end ###
 
       # Replace an exclusion list for this scope
@@ -439,9 +601,11 @@ module JSS
           item_id = validate_item(:exclusion, key, ident)
           case key
           when *@inclusion_keys
-            raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already explicitly included." if @inclusions[key] && @inclusions[key].include?(item_id)
+            raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already explicitly included." if @inclusions[key]&.include?(item_id)
           when *LIMITATIONS
-            raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already an explicit limitation." if @limitations[key] && @limitations[key].include?(item_id)
+            if @limitations[key]&.include?(item_id)
+              raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{ident}' because it's already an explicit limitation."
+            end
           end
           item_id
         end # each
@@ -449,7 +613,7 @@ module JSS
         return nil if list.sort == @exclusions[key].sort
 
         @exclusions[key] = list
-        @container.should_update if @container
+        @container&.should_update
       end # limit scope
 
       # Add a single item for exclusions of this scope.
@@ -468,12 +632,14 @@ module JSS
       def add_exclusion(key, item)
         key = pluralize_key(key)
         item_id = validate_item(:exclusion, key, item)
-        return if @exclusions[key] && @exclusions[key].include?(item_id)
-        raise JSS::AlreadyExistsError, "Can't exclude #{key} scope to '#{item}' because it's already explicitly included." if @inclusions[key] && @inclusions[key].include?(item)
-        raise JSS::AlreadyExistsError, "Can't exclude #{key} '#{item}' because it's already an explicit limitation." if @limitations[key] && @limitations[key].include?(item)
+        return if @exclusions[key]&.include?(item_id)
+
+        raise JSS::AlreadyExistsError, "Can't exclude #{key} scope to '#{item}' because it's already explicitly included." if @inclusions[key]&.include?(item)
+
+        raise JSS::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 if @container
+        @container&.should_update
       end
 
       # Remove a single item for exclusions of this scope
@@ -490,9 +656,10 @@ module JSS
       def remove_exclusion(key, item)
         key = pluralize_key(key)
         item_id = validate_item :exclusion, key, item, error_if_not_found: false
-        return unless @exclusions[key] && @exclusions[key].include?(item_id)
+        return unless @exclusions[key]&.include?(item_id)
+
         @exclusions[key].delete item_id
-        @container.should_update if @container
+        @container&.should_update
       end
 
       # @api private
@@ -508,24 +675,52 @@ module JSS
         @inclusions.each do |klass, list|
           list.compact!
           list.delete 0
-          list_as_hash = list.map { |i| { id: i } }
-          scope << SCOPING_CLASSES[klass].xml_list(list_as_hash, :id)
+          list_as_hashes = list.map { |i| { id: i } }
+          scope << SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
         end
 
         limitations = scope.add_element('limitations')
         @limitations.each do |klass, list|
           list.compact!
           list.delete 0
-          list_as_hash = list.map { |i| { id: i } }
-          limitations << SCOPING_CLASSES[klass].xml_list(list_as_hash, :id)
+          if klass == :jamf_ldap_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
+            user_groups_xml = limitations.add_element 'user_groups'
+            list.each do |name|
+              user_group_xml = user_groups_xml.add_element 'user_group'
+              user_group_xml.add_element('name').text = name
+            end
+          else
+            list_as_hashes = list.map { |i| { id: i } }
+            limitations << SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+          end
         end
 
         exclusions = scope.add_element('exclusions')
         @exclusions.each do |klass, list|
           list.compact!
           list.delete 0
-          list_as_hash = list.map { |i| { id: i } }
-          exclusions << SCOPING_CLASSES[klass].xml_list(list_as_hash, :id)
+          if klass == :jamf_ldap_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
+            user_groups_xml = exclusions.add_element 'user_groups'
+            list.each do |name|
+              user_group_xml = user_groups_xml.add_element 'user_group'
+              user_group_xml.add_element('name').text = name
+            end
+          else
+            list_as_hashes = list.map { |i| { id: i } }
+            exclusions << SCOPING_CLASSES[klass].xml_list(list_as_hashes, :id)
+          end
         end
         scope
       end # scope_xml
@@ -551,6 +746,7 @@ module JSS
       private
 
       # look up a valid id or nil, for use in a scope type
+      # Raise an error if not found, unless error_if_not_found is falsey
       #
       # @param realm [Symbol] How is this key being used in the scope?
       #   :target, :limitation, or :exclusion
@@ -561,7 +757,9 @@ module JSS
       # @param ident [String, Integer] A unique identifier for the item being
       #   validated, jss id, name, serial number, etc.
       #
-      # @return [Integer, nil] the valid id for the item, or nil if not found
+      # @param error_if_not_found [Boolean] raise an error if no match for the ident
+      #
+      # @return [Integer, String, nil] the valid id or string for the item, or nil if not found
       #
       def validate_item(realm, key, ident, error_if_not_found: true)
         # which keys allowed depends on how the item is used...
@@ -573,20 +771,42 @@ module JSS
           else
             raise ArgumentError, 'Unknown realm, must be :target, :limitation, or :exclusion'
           end
+
         key = pluralize_key(key)
+
         raise JSS::InvalidDataError, "#{realm} key must be one of :#{possible_keys.join(', :')}" \
           unless possible_keys.include? key
 
-        # return nil or a valid id
-        id = SCOPING_CLASSES[key].valid_id ident
+        id = nil
+
+        # id will be a string
+        if key == :jamf_ldap_users
+          id = ident if JSS::User.all_names(:refresh).include?(ident) || JSS::LDAPServer.user_in_ldap?(ident)
+
+        # id will be a string
+        elsif key == :ldap_user_groups
+          id = ident if JSS::LDAPServer.group_in_ldap? ident
+
+        # id will be an integer
+        else
+          id = SCOPING_CLASSES[key].valid_id ident
+        end
+
         raise JSS::NoSuchItemError, "No existing #{key} matching '#{ident}'" if error_if_not_found && id.nil?
+
         id
       end # validate_item(type, key, ident)
 
       # the symbols used in the API data are plural, e.g. 'network_segments'
       # this will pluralize them, allowing us to use singulars as well.
       def pluralize_key(key)
-        key.to_s.end_with?(ESS) ? key : "#{key}s".to_sym
+        if LDAP_JAMF_USER_KEYS.include? key
+          :jamf_ldap_users
+        elsif LDAP_GROUP_KEYS.include? key
+          :ldap_user_groups
+        else
+          key.to_s.end_with?(ESS) ? key : "#{key}s".to_sym
+        end
       end
 
     end # class Scope