ruby-jss 0.8.2 → 0.9.0.b1

data/lib/jss/api_object.rb

@@ -108,24 +108,18 @@ module JSS
   # *NOTE* Some API objects have data broken into subsections, in which case the
   # VALID_DATA_KEYS are expected in the section :general.
   #
+  #
+  # === Optional Constants
+  #
+  # ==== OTHER_LOOKUP_KEYS = [Hash{Symbol=>Hash}] Every object can be looked up by
+  # :id and :name, but some have other uniq identifiers that can also be used,
+  # e.g. :serial_number, :mac_address, and so on. This Hash, if defined,
+  # speficies those other keys for the subclass
+  # For more details about this hash, see {APIObject::DEFAULT_LOOKUP_KEYS},
+  # {APIObject.fetch}, and {APIObject#lookup_object_data}
+  #
   class APIObject
 
-    # Mix-Ins
-    #####################################
-
-    # Class Variables
-    #####################################
-
-    # This Hash holds the most recent API query for a list of all items in any subclass,
-    # keyed by the subclass's RSRC_LIST_KEY. See the self.all class method.
-    #
-    # When the .all method is called without an argument, and this hash has
-    # a matching value, the value is returned, rather than requerying the
-    # API. The first time a class calls .all, or whnever refresh is
-    # not false, the API is queried and the value in this hash is updated.
-    #
-    @@all_items = {}
-
     # Class Methods
     #####################################
 
@@ -148,7 +142,7 @@ module JSS
     # class methods for accessing those other values as mapped Arrays,
     # e.g. JSS::Computer.all_udids
     #
-    # The results of the first query for each subclass is stored in @@all_items
+    # The results of the first query for each subclass is stored in JSS.api.object_list_cache
     # and returned at every future call, so as to not requery the server every time.
     #
     # To force requerying to get updated data, provided a non-false argument.
@@ -161,9 +155,9 @@ module JSS
     #
     def self.all(refresh = false)
       raise JSS::UnsupportedError, '.all can only be called on subclasses of JSS::APIObject' if self == JSS::APIObject
-      @@all_items[self::RSRC_LIST_KEY] = nil if refresh
-      return @@all_items[self::RSRC_LIST_KEY] if @@all_items[self::RSRC_LIST_KEY]
-      @@all_items[self::RSRC_LIST_KEY] = JSS::API.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
+      JSS.api.object_list_cache[self::RSRC_LIST_KEY] = nil if refresh
+      return JSS.api.object_list_cache[self::RSRC_LIST_KEY] if JSS.api.object_list_cache[self::RSRC_LIST_KEY]
+      JSS.api.object_list_cache[self::RSRC_LIST_KEY] = JSS.api.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
     end
 
     # Returns an Array of the JSS id numbers of all the members
@@ -174,7 +168,7 @@ module JSS
     #
     # @param refresh[Boolean] should the data be re-queried from the API?
     #
-    # @return [Array<Integer>] the ids of all items of this subclass in the JSS
+    # @return [Array<Integer>] the ids of all it1ems of this subclass in the JSS
     #
     def self.all_ids(refresh = false)
       all(refresh).map { |i| i[:id] }
@@ -238,9 +232,9 @@ module JSS
     # @return [Hash{Integer => Object}] the objects requested
     def self.all_objects(refresh = false)
       objects_key = "#{self::RSRC_LIST_KEY}_objects".to_sym
-      @@all_items[objects_key] = nil if refresh
-      return @@all_items[objects_key] if @@all_items[objects_key]
-      @@all_items[objects_key] = all(refresh).map { |o| new id: o[:id] }
+      JSS.api.object_list_cache[objects_key] = nil if refresh
+      return JSS.api.object_list_cache[objects_key] if JSS.api.object_list_cache[objects_key]
+      JSS.api.object_list_cache[objects_key] = all(refresh).map { |o| new id: o[:id] }
     end
 
     # Return true or false if an object of this subclass
@@ -368,6 +362,44 @@ module JSS
       end
     end
 
+    # What are all the lookup keys available for this class?
+    #
+    # @return [Array<Symbol>] the DEFAULT_LOOKUP_KEYS plus any OTHER_LOOKUP_KEYS
+    #   defined for this class
+    #
+    def self.lookup_keys
+      return DEFAULT_LOOKUP_KEYS.keys unless defined? self::OTHER_LOOKUP_KEYS
+      DEFAULT_LOOKUP_KEYS.keys + self::OTHER_LOOKUP_KEYS.keys
+    end
+
+    # @return [Hash] the available lookup keys mapped to the appropriate
+    #  resource key for building a REST url to retrieve an object.
+    #
+    def self.rsrc_keys
+      hash = {}
+      all_keys = if defined?(self::OTHER_LOOKUP_KEYS)
+                   DEFAULT_LOOKUP_KEYS.merge self::OTHER_LOOKUP_KEYS
+                 else
+                   DEFAULT_LOOKUP_KEYS
+                 end
+      all_keys.each { |key, deets| hash[key] = deets[:rsrc_key]}
+      hash
+    end
+
+    # @return [Hash] the available lookup keys mapped to the appropriate
+    #  list class method (e.g. id: :all_ids )
+    #
+    def self.lookup_key_list_methods
+      hash = {}
+      all_keys = if defined?(self::OTHER_LOOKUP_KEYS)
+                   DEFAULT_LOOKUP_KEYS.merge self::OTHER_LOOKUP_KEYS
+                 else
+                   DEFAULT_LOOKUP_KEYS
+                 end
+      all_keys.each { |key, deets| hash[key] = deets[:list]}
+      hash
+    end
+
     # Retrieve an object from the API.
     #
     # This is the preferred way to retrieve existing objects from the JSS.
@@ -382,11 +414,26 @@ module JSS
     #
     # @return [APIObject] The ruby-instance of a JSS object
     #
-    def self.fetch(**args)
+    def self.fetch(arg)
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
-      raise ArgumentError, 'Use .create to create new JSS objects' if args[:id] == :new
-      new args
-    end
+
+      # if given a hash (or a colletion of named params)
+      # pass to .new
+      if arg.is_a? Hash
+        raise ArgumentError, 'Use .create to create new JSS objects' if arg[:id] == :new
+        return new arg
+      end
+
+      # loop thru the lookup_key list methods for this class
+      # and if it's result includes the desired value,
+      # the pass they key and arg to .new
+      lookup_key_list_methods.each do |key, method_name|
+        return new({key => arg}) if self.send(method_name).include? arg
+      end # each key
+
+      # if we're here, we couldn't find a matching object
+      raise NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found matching '#{arg}'"
+    end # fetch
 
     # Make a ruby instance of a not-yet-existing APIObject.
     #
@@ -404,14 +451,13 @@ module JSS
     #
     # @return [APIObject] The un-created ruby-instance of a JSS object
     #
-    def self.make(**args)
+    def self.make(args = {})
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
       raise ArgumentError, "Use '#{self.class}.fetch id: xx' to retrieve existing JSS objects" if args[:id]
       args[:id] = :new
       new args
     end
 
-
     ### Class Constants
     #####################################
 
@@ -420,13 +466,37 @@ module JSS
     #
     REQUIRED_DATA_KEYS = [:id, :name].freeze
 
-    # By default, these keys are available for object lookups
-    # Others can be added by subclasses using an array of them
-    # as the second argument to super(initialize)
-    # The keys must be Symbols that  match the keyname in the resource url.
-    # e.g. :serialnumber  for JSSResource/computers/serialnumber/xxxxx
+    # All API objects have an id and a name. As such By these keys are available
+    # for object lookups.
     #
-    DEFAULT_LOOKUP_KEYS = [:id, :name].freeze
+    # Others can be defined by subclasses in their OTHER_LOOKUP_KEYS constant
+    # which has the same format, described here:
+    #
+    # The merged Hashes DEFAULT_LOOKUP_KEYS and OTHER_LOOKUP_KEYS
+    # define what unique identifiers can be passed as parameters to the
+    # fetch method for retrieving an object from the API.
+    # They also define the class methods that return a list (Array) of all such
+    # identifiers for the class (e.g. the :all_ids class method returns an array
+    # of all id's for an APIObject subclass)
+    #
+    # Since there's often a discrepency between the name of the identifier as
+    # an attribute (e.g. serial_number) and the REST resource key for
+    # retrieving that object (e.g. ../computers/serialnumber/xxxxx) this hash
+    # also explicitly provides the REST resource key for a given lookup key, so
+    # e.g. both serialnumber and serial_number can be used, and both will have
+    # the resource key 'serialnumber' and the list method ':all_serial_numbers'
+    #
+    # Here's how the Hash is structured, using serialnumber as an example:
+    #
+    # LOOKUP_KEYS = {
+    #      serialnumber: {rsrc_key: :serialnumber, list: :all_serial_numbers},
+    #      serial_number: {rsrc_key: :serialnumber, list: :all_serial_numbers}
+    # }
+    #
+    DEFAULT_LOOKUP_KEYS = {
+      id: {rsrc_key: :id, list: :all_ids},
+      name: {rsrc_key: :name, list: :all_names}
+    }.freeze
 
     # Attributes
     #####################################
@@ -461,20 +531,13 @@ module JSS
     # @option args :name[String] the name to look up
     #
     # @option args :data[Hash] the JSON output of a separate {JSS::APIConnection} query
+    #   NOTE: This arg is deprecated and will be removed in a future release.
     #
-    # @param other_lookup_keys[Array<Symbol>] Hash keys other than :id and :name, by which an API
-    #   lookup may be performed.
     #
-    def initialize(args = {}, other_lookup_keys = [])
-      args[:other_lookup_keys] ||= other_lookup_keys
+    def initialize(args = {})
 
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
 
-      ### what lookup key are we using, if any?
-      lookup_keys = DEFAULT_LOOKUP_KEYS
-      lookup_keys += self.class::OTHER_LOOKUP_KEYS if defined? self.class::OTHER_LOOKUP_KEYS
-      lookup_key = (lookup_keys & args.keys)[0]
-
       ####### Previously looked-up JSON data
       # DEPRECATED: pre-lookedup data is never used
       # and support for it will be going away.
@@ -486,9 +549,9 @@ module JSS
 
       ###### Make a new one in the JSS, but only if we've included the Creatable module
       elsif args[:id] == :new
-
         validate_init_for_creation(args)
         setup_object_for_creation(args)
+
         return
 
       ###### Look up the data via the API
@@ -496,6 +559,7 @@ module JSS
         @init_data = look_up_object_data(args)
       end ## end arg parsing
 
+
       parse_init_data
       @need_to_update = false
     end # init
@@ -596,7 +660,7 @@ module JSS
     #
     def delete
       return nil unless @in_jss
-      JSS::API.delete_rsrc @rest_rsrc
+      JSS.api.delete_rsrc @rest_rsrc
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape @name}"
       @id = nil
       @in_jss = false
@@ -668,16 +732,20 @@ module JSS
     #
     def look_up_object_data(args)
       # what lookup key are we using?
-      combined_lookup_keys = self.class::DEFAULT_LOOKUP_KEYS + args[:other_lookup_keys]
-      lookup_key = (combined_lookup_keys & args.keys)[0]
+      lookup_keys = self.class.lookup_keys
+      lookup_key = (self.class.lookup_keys & args.keys)[0]
+      raise JSS::MissingDataError, "Args must include a lookup key, one of: :#{lookup_keys.join(', :')}" unless lookup_key
+      rsrc_key = self.class.rsrc_keys[lookup_key]
 
-      raise JSS::MissingDataError, "Args must include a lookup key, one of: :#{combined_lookup_keys.join(', :')}" unless lookup_key
+      rsrc = "#{self.class::RSRC_BASE}/#{rsrc_key}/#{args[lookup_key]}"
 
-      rsrc = "#{self.class::RSRC_BASE}/#{lookup_key}/#{args[lookup_key]}"
+      # if needed, a non-standard object key can be passed by a subclass.
+      # e.g. User when loookup is by email.
+      rsrc_object_key = args[:rsrc_object_key] ? args[:rsrc_object_key] : self.class::RSRC_OBJECT_KEY
 
-      return JSS::API.get_rsrc(rsrc)[self.class::RSRC_OBJECT_KEY]
+      return JSS.api.get_rsrc(rsrc)[rsrc_object_key]
     rescue RestClient::ResourceNotFound
-      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching: #{lookup_key}/#{args[lookup_key]}"
+      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching: #{rsrc_key}/#{args[lookup_key]}"
     end
 
     # Start examining the @init_data recieved from the API
@@ -685,6 +753,7 @@ module JSS
     # @return [void]
     #
     def parse_init_data
+      @init_data ||= {}
       # set empty strings to nil
       @init_data.jss_nillify! '', :recurse
 
@@ -802,7 +871,7 @@ module JSS
     def setup_object_for_creation(args)
       # NOTE: subclasses may want to pre-populate more keys in @init_data when :id == :new
       # then parse them into attributes later.
-      @init_data = { name: args[:name] }
+      @init_data = args
       @name = args[:name]
       @in_jss = false
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape @name}"

data/lib/jss/api_object/account.rb

@@ -61,7 +61,12 @@ module JSS
     RSRC_OBJECT_KEY = :account
 
     # these keys,  as well as :id and :name, can be used to look up objects of this class in the JSS
-    OTHER_LOOKUP_KEYS = [:userid, :username, :groupid, :groupname].freeze
+    OTHER_LOOKUP_KEYS = {
+      userid: {rsrc_key: :userid, list: :all_user_ids},
+      username: {rsrc_key: :username, list: :all_user_names},
+      groupid: {rsrc_key: :groupid, list: :all_group_ids},
+      groupname: {rsrc_key: :groupname, list: :all_group_names}
+    }.freeze
 
     # Class Methods
     #####################################

data/lib/jss/api_object/advanced_search.rb

@@ -167,11 +167,11 @@ module JSS
       raise JSS::InvalidDataError, 'JSS::Criteriable::Criteria instance required' unless @criteria.is_a? JSS::Criteriable::Criteria
       raise JSS::InvalidDataError, 'display_fields must be an Array.' unless @display_fields.is_a? Array
 
-      orig_timeout = JSS::API.cnx.options[:timeout]
-      JSS::API.timeout = 1800
+      orig_timeout = JSS.api_connection.cnx.options[:timeout]
+      JSS.api_connection.timeout = 1800
       super()
       requery_search_results if get_results
-      JSS::API.timeout = orig_timeout
+      JSS.api_connection.timeout = orig_timeout
 
       @id # remember to return the id
     end
@@ -185,11 +185,11 @@ module JSS
     # @return [Integer] the id of the updated search
     #
     def update(get_results = false)
-      orig_timeout = JSS::API.cnx.options[:timeout]
-      JSS::API.timeout = 1800
+      orig_timeout = JSS.api_connection.cnx.options[:timeout]
+      JSS.api_connection.timeout = 1800
       super()
       requery_search_results if get_results
-      JSS::API.timeout = orig_timeout
+      JSS.api_connection.timeout = orig_timeout
 
       @id # remember to return the id
     end
@@ -201,17 +201,17 @@ module JSS
     # @return [Array<Hash>] the new search results
     #
     def requery_search_results
-      orig_open_timeout = JSS::API.cnx.options[:open_timeout]
-      orig_timeout = JSS::API.cnx.options[:timeout]
-      JSS::API.timeout = 1800
-      JSS::API.open_timeout = 1800
+      orig_open_timeout = JSS.api_connection.cnx.options[:open_timeout]
+      orig_timeout = JSS.api_connection.cnx.options[:timeout]
+      JSS.api_connection.timeout = 1800
+      JSS.api_connection.open_timeout = 1800
       begin
         requery = self.class.new(id: @id)
         @search_results = requery.search_results
         @result_display_keys = requery.result_display_keys
       ensure
-        JSS::API.timeout = orig_timeout
-        JSS::API.open_timeout = orig_open_timeout
+        JSS.api_connection.timeout = orig_timeout
+        JSS.api_connection.open_timeout = orig_open_timeout
       end
     end
 

data/lib/jss/api_object/computer.rb

@@ -26,24 +26,14 @@
 ###
 module JSS
 
-  # Module Constants
-  #####################################
-
-  # Module Variables
-  #####################################
-
-  # Module Methods
-  #####################################
-
   # This class represents a Computer in the JSS.
   #
-  # ===Adding Computers to the JSS
+  # === Adding Computers to the JSS
   #
-  # This class cannot be used to add new Computers to the JSS. Please use other
-  # Casper methods (like the Recon App or QuickAdd package)
+  # At the moment, this class cannot be used to add new Computers to the JSS.
+  # Please use other methods (like the Recon App or QuickAdd package)
   #
-  # ---
-  # ===Editing values
+  # === Editing values
   #
   # Any data that arrives in the JSS via an "inventory update"
   # (a.k.a. 'recon') cannot be modified through this class, or the API.
@@ -66,27 +56,91 @@ module JSS
   # After making any changes, you must call #update to send those
   # changes to the server.
   #
-  # ---
   # === MDM Commands
   #
-  # ==== MDM Commands are Not Yet Supported!
-  # *Hopefully they will be soon*
+  # The following methods can be used to send an APNS command to the
+  # computer represented by an instance of JSS::Computer, equivalent to
+  # clicking one of the buttons on the Management Commands section of the
+  # Management tab of the Computer details page in the JSS UI.
+  #
+  # - {#blank_push}  (aliases blank, noop, send_blank_push)
+  # - {#device_lock} (aliases lock, lock_device)
+  # - {#erase_device} (aliases wipe)
+  # - {#remove_mdm_profile}
+  #
+  # To send an MDM command without making a Computer instance, use the class
+  # {JSS::Computer.send_mdm_command} which can take multiple computer
+  # identifiers at once.
+  #
+  # NOTE: the poorly named 'UnmanageDevice' command via the API is implemented
+  # as the {#remove_mdm_profile} method (which is its name in the webUI).
+  # Calling that method will NOT unmanage the machine from the JSS's point
+  # of view, it will just remove the mdm management profile from the machine
+  # and all configuration profiles that were installed via the JSS. Those
+  # profiles may be re-installed automatically later if the computer is still in
+  # scope for them
+  #
+  # The {#make_unmanaged} method also removes the mdm profile, but actually
+  # does make the machine unmanged by the JSS, setting the management acct to
+  # nil, and requring re-enrollment.
+  #
+  # === Computer History
+  #
+  # Computer instances can now retrieve their management history from the JSS.
+  #
+  # The full history data is available from the {#history} method, but beware that
+  # it is very large.
+  #
+  # Subsets of that history have their own methods, which are faster and only retrieve
+  # the subset requested. See {#usage_logs}, {#audits}, {#policy_los},
+  # {#completed_policies}, {#failed_polices}, {#casper_remote_logs},
+  # {#screen_sharing_logs}, {#casper_imaging_logs}, {#commands},
+  # {#user_location_history},and {#app_store_app_history}
+  #
+  # When any of the history methods is used the first time, the data is read
+  # from the API and cached internally, and that data is
+  # used for all future calls.. To re-read the data from the API and re-cache it,
+  # provide any non-false parameter to the subset methods , or `refresh: true`
+  # to the main {#history} method.
+  #
+  # === Appication Usage History
+  #
+  # Computer Instances now have access to their Application Usage history
+  # via the {#application_usage} method.
+  # Call the method with a start-date value (either a String or a Time object)
+  # and an optional end-date value. If you omite the end-date, the start-date
+  # is used and you'll see usage for just that day.
+  #
+  # See {#application_usage} for details about the data returned.
   #
-  # The following methods will be used to send an APNS command to the computer represented by an
-  # instance of JSS::Computer, equivalent to clicking one of the buttons on
-  # the Management Commands section of the Management tab of the Computer details page in the JSS UI.
+  # NOTE: your JSS must be gathering Appication Usage data in order
+  # for any data to be returned, and the usage history will only go back as
+  # far as your setting for flushing of Application Usage Logs.
   #
-  # The methods supported will be:
-  # - #blank_push  (aliases blank, noop, send_blank_push)
-  # - #device_lock (aliases lock, lock_device)
-  # - #erase_device (aliases wipe)
+  # === Management Data
   #
-  # To send an MDM command without making an instance, use the class method {.send_mdm_command}
+  # The computers 'manamgement data', as presented on the 'Management' tab of
+  # the computer's detail page in the JSS web UI, is available from the
+  # {#management_data} method. That method may return a large dataset,
+  # unless a subset is requested.
   #
-  # Each returns true if the command as sent.
+  # Subsets of management data have their own methods, which are faster and
+  # only retrieve the subset requested. See {#smart_groups}, {#static_groups},
+  # {#policies}, {#configuration_profiles}, {#ebooks}, {#app_store_apps},
+  # {#restricted_software}, and {#patch_titles}
   #
-  # ---
-  # ===Other Methods
+  # The subset methods can take an 'only:' parameter, which is a symbol specifying
+  # the value you care to see. For example {#smart_groups} returns an array
+  # of hashes, one for each smart_group the computer is in. Those hashes
+  # have two keys, :name, and :id. However if you only want an array of
+  # names, you can call `smart_groups only: :name`
+  #
+  # When any of the manamgement data methods are used the first time, the data
+  # is read from the API and cached internally, the cache is then
+  # used for all future calls. To re-read the data from the API and re-cache it,
+  # provide `refresh: true` to any of the manamgement data methods.
+  #
+  # === Other Methods
   #
   # - {#set_management_to} change the management acct and passwd for this computer, aliased to #make_managed
   #   - requires calling #update to push changes to the server
@@ -118,14 +172,185 @@ module JSS
 
     extend JSS::Matchable
 
-    # Class Variables
+    # Class Constants
     #####################################
 
-    @@all_computers = nil
+    # The base for REST resources of this class
+    RSRC_BASE = 'computers'.freeze
+
+    # The (temporary?) list-resource
+    LIST_RSRC = "#{RSRC_BASE}/subset/basic".freeze
+
+    # the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :computers
+
+    # The hash key used for the JSON object output.
+    # It's also used in various error messages
+    RSRC_OBJECT_KEY = :computer
+
+    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
+    #   DEPRECATED, with be removed in a future release.
+    VALID_DATA_KEYS = %i[sus distribution_point alt_mac_address].freeze
+
+    # these keys,  as well as :id and :name, can be used to look up objects of this class in the JSS
+    OTHER_LOOKUP_KEYS = {
+      udid: { rsrc_key: :udid, list: :all_udids },
+      serialnumber: { rsrc_key: :serialnumber, list: :all_serial_numbers },
+      serial_number: { rsrc_key: :serialnumber, list: :all_serial_numbers },
+      macaddress: { rsrc_key: :macaddress, list: :all_mac_addresses },
+      mac_address: { rsrc_key: :macaddress, list: :all_mac_addresses }
+    }.freeze
+
+    # This class lets us seach for computers
+    SEARCH_CLASS = JSS::AdvancedComputerSearch
+
+    # This is the class for relevant Extension Attributes
+    EXT_ATTRIB_CLASS = JSS::ComputerExtensionAttribute
+
+    # Boot partitions are noted with the string "(Boot Partition)" at the end
+    BOOT_FLAG = ' (Boot Partition)'.freeze
+
+    # file uploads can send attachments to the JSS using :computers as the sub-resource.
+    UPLOAD_TYPES = { attachment: :computers }.freeze
+
+    # The base REST resource for sending computer MDM commands
+    COMPUTER_MDM_RSRC = 'computercommands/command'.freeze
+
+    # A mapping of Symbols available to the send_mdm_command class method, to
+    # the String commands actuallly sent via the API.
+    COMPUTER_MDM_COMMANDS = {
+      blank_push: 'BlankPush',
+      blankpush: 'BlankPush',
+      send_blank_push: 'BlankPush',
+      blank: 'BlankPush',
+      noop: 'BlankPush',
+      device_lock: 'DeviceLock',
+      devicelock: 'DeviceLock',
+      lock: 'DeviceLock',
+      lock_device: 'DeviceLock',
+      erase_device: 'EraseDevice',
+      erasedevice: 'EraseDevice',
+      erase: 'EraseDevice',
+      wipe: 'EraseDevice',
+      unmanage_device: 'UnmanageDevice',
+      unmanagedevice: 'UnmanageDevice',
+      unmanage: 'UnmanageDevice'
+    }.freeze
+
+    # these MDM commands require a passcode
+    COMPUTER_MDM_COMMANDS_NEEDING_PASSCODE = %w[DeviceLock EraseDevice].freeze
+
+    # The API resource for app usage
+    APPLICATION_USAGE_RSRC = 'computerapplicationusage'.freeze
+
+    # The date format for retrieving usage data
+    APPLICATION_USAGE_DATE_FMT = '%Y-%m-%d'.freeze
+
+    # The classes that can be used with the date format
+    APPLICATION_USAGE_DATE_CLASSES = [Time, DateTime, Date].freeze
+
+    # The top-level hash key of the raw app usage data
+    APPLICATION_USAGE_KEY = :computer_application_usage
+
+    # The API resource for computer_management data
+    MGMT_DATA_RSRC = 'computermanagement'.freeze
+
+    # The top-level hash key of the computer_management data
+    MGMT_DATA_KEY = :computer_management
+
+    # Thes are both the subset names in the resrouce URLS (when
+    # converted to strings) and the second-level hash key of the
+    # returned subset data.
+    MGMT_DATA_SUBSETS = %i[
+      smart_groups
+      static_groups
+      mac_app_store_apps
+      policies
+      ebooks
+      os_x_configuration_profiles
+      restricted_software
+      patch_reporting_software_titles
+    ].freeze
+
+    # The API Resource for the computer checkin settings
+    CHECKIN_RSRC = 'computercheckin'.freeze
+
+    # The top-level hash key for the checkin settings
+    CHECKIN_KEY = :computer_check_in
+
+    # The API Resource for the computer inventory collection settings
+    INV_COLLECTION_RSRC = 'computerinventorycollection'.freeze
+
+    # The top-level hash key for the inventory collection settings
+    INV_COLLECTION_KEY = :computer_inventory_collection
+
+    # The API Resource for the computer history data
+    HISTORY_RSRC = 'computerhistory'.freeze
+
+    # The top-level hash key for the history data
+    HISTORY_KEY = :computer_history
+
+    # The keys are both the subset names in the resrouce URLS (when
+    # converted to strings) and the second-level hash key of the
+    # returned subset data.
+    #
+    # The values are the key within each history item that contains the
+    # 'epoch' timestamp, for conver
+    HISTORY_SUBSETS = %i[
+      computer_usage_logs
+      audits
+      policy_logs
+      casper_remote_logs
+      screen_sharing_logs
+      casper_imaging_logs
+      commands
+      user_location
+      mac_app_store_applications
+    ].freeze
+
+    # HISTORY_SUBSETS = %i(
+    #   computer_usage_logs date_time_epoch
+    #   audits
+    #   policy_logs date_completed_epoch
+    #   casper_remote_logs date_time_epoch
+    #   screen_sharing_logs date_time_epoch
+    #   casper_imaging_logs
+    #   commands completed_epoch
+    #   user_location
+    #   mac_app_store_applications
+    # ).freeze
+
+    POLICY_STATUS_COMPLETED = 'Completed'.freeze
+
+    POLICY_STATUS_FAILED = 'Failed'.freeze
+
+    POLICY_STATUS_PENDING = 'Pending'.freeze
 
     # Class Methods
     #####################################
 
+    # Display the current Computer CheckIn settings in the JSS.
+    # Currently this is read-only in ruby-jss, even tho the API
+    # allows updating.
+    #
+    # @return [Hash] the Computer Checkin Settings from the
+    #   currently connected JSS.
+    #
+    def self.checkin_settings
+      JSS.api_connection.get_rsrc(CHECKIN_RSRC)[CHECKIN_KEY]
+    end
+
+    # Display the current Computer Inventory Collection settings in the JSS.
+    # Currently this is read-only in ruby-jss, even tho the API
+    # allows updating.
+    #
+    # @return [Hash] the Computer Inventpry Collection Settings from the
+    #   currently connected JSS.
+    #
+    def self.inventory_collection_settings
+      JSS.api_connection.get_rsrc(INV_COLLECTION_RSRC)[INV_COLLECTION_KEY]
+    end
+
     # A larger set of info about the computers in the JSS.
     #
     # Casper 9.4 introduced the API Resource /computers/subset/basic
@@ -143,9 +368,9 @@ module JSS
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
     def self.all(refresh = false)
-      @@all_computers = nil if refresh
-      return @@all_computers if @@all_computers
-      @@all_computers = JSS::API.get_rsrc(self::LIST_RSRC)[self::RSRC_LIST_KEY]
+      JSS.api.object_list_cache[RSRC_LIST_KEY] = nil if refresh
+      return JSS.api.object_list_cache[RSRC_LIST_KEY] if JSS.api.object_list_cache[RSRC_LIST_KEY]
+      JSS.api.object_list_cache[RSRC_LIST_KEY] = JSS.api_connection.get_rsrc(self::LIST_RSRC)[self::RSRC_LIST_KEY]
     end
 
     # @return [Array<String>] all computer serial numbers in the jss
@@ -170,7 +395,7 @@ module JSS
 
     # @return [Array<Hash>] all unmanaged computers in the jss
     def self.all_unmanaged(refresh = false)
-      all(refresh).select { |d| !(d[:managed]) }
+      all(refresh).reject { |d| d[:managed] }
     end
 
     # @return [Array<Hash>] all laptop computers in the jss
@@ -200,7 +425,7 @@ module JSS
 
     # @return [Array<Hash>] all desktop macs in the jss
     def self.all_desktops(refresh = false)
-      all(refresh).select { |d| d[:model] !~ /serve|book/i }
+      all(refresh).reject { |d| d[:model] =~ /serve|book/i }
     end
 
     # @return [Array<Hash>] all imacs in the jss
@@ -218,88 +443,53 @@ module JSS
       all(refresh).select { |d| d[:model] =~ /^macpro/i }
     end
 
-    # Send an MDM command to a managed computer by id or name
-    #
-    # @param computer[String,Integer] the name or id of the computer to recieve the command
-    # @param command[Symbol] the command to send, one of the keys of COMPUTER_MDM_COMMANDS
-    #
-    # @return [true] if the command was sent
-    #
-
-    # Not functional until I get more docs from JAMF
+    # Send an MDM command to one or more managed computers by id or name
     #
-    #     def self.send_mdm_command(computer,command)
     #
-    #       raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless COMPUTER_MDM_COMMANDS.keys.include? command
+    # @param targets[String,Integer,Array<String,Integer>]
+    #   the name or id of the computer to receive the command, or
+    #   an array of such names or ids, or a comma-separated string
+    #   of them.
+    # @param command[Symbol] the command to send, one of the keys
+    #   of COMPUTER_MDM_COMMANDS
     #
-    #       command_xml ="#{JSS::APIConnection::XML_HEADER}<computer><command>#{COMPUTER_MDM_COMMANDS[command]}</command></computer>"
-    #       the_id = nil
+    # @param passcode[String] some commands require a 6-character passcode
     #
-    #       if computer.to_s =~ /^\d+$/
-    #         the_id = computer
-    #       else
-    #         the_id = self.map_all_ids_to(:name).invert[computer]
-    #       end
+    # @return [String] The uuid of the MDM command sent, if applicable
+    #  (blank pushes do not generate uuids)
     #
-    #       if the_id
-    #         response = JSS::API.put_rsrc("#{RSRC_BASE}/id/#{the_id}", command_xml)
-    #         response =~ %r{<notification_sent>(.+)</notification_sent>}
-    #         return ($1 and $1 == "true")
-    #       end
-    #       raise JSS::UnmanagedError, "Cannot send command to unknown/unmanaged computer '#{computer}'"
-    #     end
+    def self.send_mdm_command(targets, command, passcode = nil)
+      raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless COMPUTER_MDM_COMMANDS.keys.include? command
 
-    # Class Constants
-    #####################################
+      command = COMPUTER_MDM_COMMANDS[command]
+      cmd_rsrc = "#{COMPUTER_MDM_RSRC}/#{command}"
 
-    # The base for REST resources of this class
-    RSRC_BASE = 'computers'.freeze
-
-    # The (temporary?) list-resource
-    LIST_RSRC = "#{RSRC_BASE}/subset/basic".freeze
-
-    # the hash key used for the JSON list output of all objects in the JSS
-    RSRC_LIST_KEY = :computers
-
-    # The hash key used for the JSON object output.
-    # It's also used in various error messages
-    RSRC_OBJECT_KEY = :computer
+      if COMPUTER_MDM_COMMANDS_NEEDING_PASSCODE.include? command
+        unless passcode && passcode.is_a?(String) && passcode.length == 6
+          raise JSS::MissingDataError, "Command '#{command}' requires a 6-character passcode"
+        end
+        cmd_rsrc << "/passcode/#{passcode}"
+      end
 
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    #   DEPRECATED, with be removed in a future release.
-    VALID_DATA_KEYS = [:sus, :distribution_point, :alt_mac_address].freeze
+      targets = JSS.to_s_and_a(targets.to_s)[:arrayform] unless targets.is_a? Array
 
-    # these keys,  as well as :id and :name, can be used to look up objects of this class in the JSS
-    OTHER_LOOKUP_KEYS = [:udid, :serialnumber, :mac_address].freeze
+      # make sure its an array of ids
+      targets.map! do |comp|
+        if all_ids.include? comp.to_i
+          comp.to_i
+        elsif all_names.include? comp
+          map_all_ids_to(:name).invert[comp]
+        else
+          raise JSS::NoSuchItemError, "No computer found matching '#{comp}'"
+        end # if
+      end # map!
 
-    # This class lets us seach for computers
-    SEARCH_CLASS = JSS::AdvancedComputerSearch
+      cmd_rsrc << "/id/#{targets.join ','}"
 
-    # This is the class for relevant Extension Attributes
-    EXT_ATTRIB_CLASS = JSS::ComputerExtensionAttribute
-
-    # Boot partitions are noted with the string "(Boot Partition)" at the end
-    BOOT_FLAG = ' (Boot Partition)'.freeze
-
-    # file uploads can send attachments to the JSS using :computers as the sub-resource.
-    UPLOAD_TYPES = { attachment: :computers }.freeze
-
-    # A mapping of Symbols available to the send_mdm_command class method, to
-    # the String commands actuallly sent via the API.
-    COMPUTER_MDM_COMMANDS = {
-      blank_push: 'BlankPush',
-      send_blank_push: 'BlankPush',
-      blank: 'BlankPush',
-      noop: 'BlankPush',
-      device_lock: 'DeviceLock',
-      lock: 'DeviceLock',
-      lock_device: 'DeviceLock',
-      erase_device: 'EraseDevice',
-      erase: 'EraseDevice',
-      wipe: 'EraseDevice',
-      unmanage_device: 'UnmanageDevice',
-      unmanage: 'UnmanageDevice'
-    }.freeze
+      result = JSS::API.post_rsrc cmd_rsrc, nil
+      result =~ %r{<command_uuid>(.*)</command_uuid>}
+      Regexp.last_match(1)
+    end # send mdm command
 
     # Attributes
     #####################################
@@ -526,7 +716,7 @@ module JSS
     # As well as :id and :name, computers can be queried using :udid, :serialnumber, and :mac_address
     #
     def initialize(args = {})
-      super args, [:udid, :serialnumber, :mac_address]
+      super args
 
       # now we have raw @init_data with something in it, so fill out the instance vars
       @alt_mac_address = @init_data[:general][:alt_mac_address]
@@ -621,6 +811,234 @@ module JSS
       @software[:licensed_software]
     end
 
+    # Get application usage data for this computer
+    # for a given date range.
+    #
+    # @param start_date [String,Date,DateTime,Time]
+    #
+    # @param end_date [String,Date,DateTime,Time] Defaults to start_date
+    #
+    # @return [Hash{Date=>Array<Hash>}] For each day in the range, an Array
+    #   with one Hash per application used. The hash keys are:
+    #   :name => String, the name of the app
+    #   :version => String ,the version of the app
+    #   :foreground => Integer, the minutes it was in the foreground
+    #   :open => Integer, the minutes it was running.
+    #
+    def application_usage(start_date, end_date = nil)
+      end_date ||= start_date
+      start_date = Time.parse start_date if start_date.is_a? String
+      end_date = Time.parse end_date if end_date.is_a? String
+      unless ([start_date.class, end_date.class] - APPLICATION_USAGE_DATE_CLASSES).empty?
+        raise JSS::InvalidDataError, 'Invalid Start or End Date'
+      end
+      start_date = start_date.strftime APPLICATION_USAGE_DATE_FMT
+      end_date = end_date.strftime APPLICATION_USAGE_DATE_FMT
+      data = JSS.api_connection.get_rsrc(APPLICATION_USAGE_RSRC + "/id/#{@id}/#{start_date}_#{end_date}")
+      parsed_data = {}
+      data[APPLICATION_USAGE_KEY].each do |day_hash|
+        date = Date.parse day_hash[:date]
+        parsed_data[date] = day_hash[:apps]
+      end
+      parsed_data
+    end # app usage
+
+    # The 'computer management' data for this computer, looked up on the fly.
+    #
+    # Without specifying a subset:, the entire dataset is returned as a hash of
+    # arrays, one per  subset
+    # If a subset is given then only that array is returned, and it contains
+    # hashes with data about each item (usually :name and :id)
+    #
+    # If the only: param is provided with a subset, it is used as a hash-key to
+    # map the array to just those values, so subset: :smart_groups, only: :name
+    # will return an array of names of smartgroups that contain this computer.
+    #
+    # @param subset[Symbol] Fetch only a subset of data, as an array.
+    #    must be one of the symbols in MGMT_DATA_SUBSETS
+    #
+    # @param only[Symbol] When fetching a subset, only return one value
+    #   per item in the array. meaningless without a subset.
+    #
+    # @param refresh[Boolean] should the data be re-cached from the API?
+    #
+    # @return [Hash] Without a subset:, a hash of all subsets, each of which is
+    #   an Array
+    #
+    # @return [Array] With a subset:, an array of items in that subset.
+    #
+    def management_data(subset: nil, only: nil, refresh: false)
+      @management_data ||= {}
+      if subset
+        management_data_subset(subset: subset, only: only, refresh: refresh)
+      else
+        full_management_data refresh
+      end
+    end
+
+    def full_management_data(refresh = false)
+      @management_data[:full] = nil if refresh
+      return @management_data[:full] if @management_data[:full]
+      mgmt_rsrc = MGMT_DATA_RSRC + "/id/#{@id}"
+      @management_data[:full] = JSS.api.get_rsrc(mgmt_rsrc)[MGMT_DATA_KEY]
+      @management_data[:full]
+    end
+    private :full_management_data
+
+    def management_data_subset(subset: nil, only: nil, refresh: false)
+      raise "Subset must be one of :#{MGMT_DATA_SUBSETS.join ', :'}" unless MGMT_DATA_SUBSETS.include? subset
+      @management_data[subset] = nil if refresh
+      return @management_data[subset] if @management_data[subset]
+      subset_rsrc = MGMT_DATA_RSRC + "/id/#{@id}/subset/#{subset}"
+      @management_data[subset] = JSS.api.get_rsrc(subset_rsrc)[MGMT_DATA_KEY]
+      return @management_data[subset] unless only
+      @management_data[subset].map { |d| d[only] }
+    end
+    private :management_data_subset
+
+    # A shortcut for 'management_data subset: :smart_groups'
+    #
+    def smart_groups(only: nil, refresh: false)
+      management_data subset: :smart_groups, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :static_groups'
+    #
+    def static_groups(only: nil, refresh: false)
+      management_data subset: :static_groups, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :policies'
+    #
+    def policies(only: nil, refresh: false)
+      management_data subset: :policies, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :os_x_configuration_profiles'
+    #
+    def configuration_profiles(only: nil, refresh: false)
+      management_data subset: :os_x_configuration_profiles, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :ebooks'
+    #
+    def ebooks(only: nil, refresh: false)
+      management_data subset: :ebooks, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :mac_app_store_apps'
+    #
+    def app_store_apps(only: nil, refresh: false)
+      management_data subset: :mac_app_store_apps, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :restricted_software'
+    #
+    def restricted_software(only: nil, refresh: false)
+      management_data subset: :restricted_software, only: only, refresh: refresh
+    end
+
+    # A shortcut for 'management_data subset: :patch_reporting_software_titles'
+    #
+    def patch_titles(only: nil, refresh: false)
+      management_data subset: :patch_reporting_software_titles, only: only, refresh: refresh
+    end
+
+    # Return this computer's history.
+    # WARNING! Its huge, better to use a subset a
+    # nd one of the shortcut methods.
+    #
+    # @param subset[Symbol] the subset to return, rather than full history.
+    #
+    # @param refresh[Boolean] should we re-cache the data from the API?
+    #
+    # @return [Hash] The full history
+    #
+    # @return [Array] The history subset requested
+    #
+    def history(subset: nil, refresh: false)
+      @history ||= {}
+      if subset
+        history_subset(subset: subset, refresh: refresh)
+      else
+        full_history refresh
+      end
+    end
+
+    def full_history(refresh = false)
+      @history[:full] = nil if refresh
+      return @history[:full] if @history[:full]
+      history_rsrc = HISTORY_RSRC + "/id/#{@id}"
+      @history[:full] = JSS.api.get_rsrc(history_rsrc)[HISTORY_KEY]
+      @history[:full]
+    end
+    private :full_history
+
+    def history_subset(subset: nil, refresh: false)
+      raise "Subset must be one of :#{HISTORY_SUBSETS.join ', :'}" unless HISTORY_SUBSETS.include? subset
+      @history[subset] = nil if refresh
+      return @history[subset] if @history[subset]
+      subset_rsrc = HISTORY_RSRC + "/id/#{@id}/subset/#{subset}"
+      @history[subset] = JSS.api.get_rsrc(subset_rsrc)[HISTORY_KEY]
+      @history[subset]
+    end
+    private :history_subset
+
+    # Shortcut for history(:computer_usage_logs)
+    def usage_logs(refresh = false)
+      history(subset: :computer_usage_logs, refresh: refresh)
+    end
+
+    # Shortcut for history(:audits)
+    def audits(refresh = false)
+      history(subset: :audits, refresh: refresh)
+    end
+
+    # Shortcut for history(:policy_logs)
+    def policy_logs(refresh = false)
+      history(subset: :policy_logs, refresh: refresh)
+    end
+
+    # Shortcut for history(:policy_logs), but just the completed policies
+    def completed_policies(refresh = false)
+      policy_logs(refresh).select { |pl| pl[:status] == POLICY_STATUS_COMPLETED }
+    end
+
+    # Shortcut for history(:policy_logs), but just the failes policies
+    def failed_policies(refresh = false)
+      policy_log(refresh).select { |pl| pl[:status] == POLICY_STATUS_FAILED }
+    end
+
+    # Shortcut for history(:casper_remote_logs)
+    def casper_remote_logs(refresh = false)
+      history(subset: :casper_remote_logs, refresh: refresh)
+    end
+
+    # Shortcut for history(:screen_sharing_logs)
+    def screen_sharing_logs(refresh = false)
+      history(subset: :screen_sharing_logs, refresh: refresh)
+    end
+
+    # Shortcut for history(:casper_imaging_logs)
+    def casper_imaging_logs(refresh = false)
+      history(subset: :casper_imaging_logs, refresh: refresh)
+    end
+
+    # Shortcut for history(:commands)
+    def commands(refresh = false)
+      history(subset: :commands, refresh: refresh)
+    end
+
+    # Shortcut for history(:user_location)
+    def user_location_history(refresh = false)
+      history(subset: :user_location, refresh: refresh)
+    end
+
+    # Shortcut for history(:mac_app_store_applications)
+    def app_store_app_history(refresh = false)
+      history(subset: :mac_app_store_applications, refresh: refresh)
+    end
+
     # Set or unset management acct and password for this computer
     #
     # @param name[String] the name of the management acct.
@@ -629,7 +1047,7 @@ module JSS
     #
     # @return [void]
     #
-    # The changes will need to be pushed to the server with #update
+    # The changes will need to be pushed to the server with {#update}
     # before they take effect.
     #
     # CAUTION: this does nothing to confirm the name and password
@@ -656,10 +1074,8 @@ module JSS
     def make_unmanaged
       return nil unless managed?
       set_management_to(nil, nil)
-      begin
-        self.class.send_mdm_command(@id, :unmanage_device)
-      rescue
-      end
+      return unless mdm_capable
+      self.class.send_mdm_command(@id, :unmanage_device)
     end
 
     #
@@ -751,34 +1167,47 @@ module JSS
       @software = nil
     end # delete
 
-    # Not Functional until I get more docs from JAMF
-    #
-    #     #
-    #     # Send a blank_push MDM command
-    #     #
-    #     def blank_push
-    #       self.class.send_mdm_command @id, :blank_push
-    #     end
-    #     alias noop blank_push
-    #     alias send_blank_push blank_push
-    #
-    #     #
-    #     # Send a device_lock MDM command
-    #     #
-    #     def device_lock
-    #       self.class.send_mdm_command @id, :device_lock
-    #     end
-    #     alias lock device_lock
-    #     alias lock_device device_lock
-    #
-    #     #
-    #     # Send an erase_device MDM command
-    #     #
-    #     def erase_device
-    #       self.class.send_mdm_command @id, :erase_device
-    #     end
-    #     alias erase erase_device
-    #     alias wipe erase_device
+    # Send a blank_push MDM command
+    #
+    # See JSS::Computer.send_mdm_command
+    #
+    def blank_push
+      self.class.send_mdm_command @id, :blank_push
+    end
+    alias noop blank_push
+    alias send_blank_push blank_push
+
+    # Send a device_lock MDM command
+    #
+    # See JSS::Computer.send_mdm_command
+    #
+    def device_lock(passcode)
+      self.class.send_mdm_command @id, :device_lock, passcode
+    end
+    alias lock device_lock
+    alias lock_device device_lock
+
+    # Send an erase_device MDM command
+    #
+    # See JSS::Computer.send_mdm_command
+    #
+    def erase_device(passcode)
+      self.class.send_mdm_command @id, :erase_device, passcode
+    end
+    alias erase erase_device
+    alias wipe erase_device
+
+    # Remove MDM management profile without
+    # un-enrolling from the JSS or
+    # resetting the JSS management acct.
+    #
+    # To do those things as well, see {#make_unmanaged}
+    #
+    # See JSS::Computer.send_mdm_command
+    #
+    def remove_mdm_profile
+      self.class.send_mdm_command(@id, :unmanage_device)
+    end
 
     # aliases
     alias alt_macaddress alt_mac_address
@@ -830,7 +1259,7 @@ module JSS
       computer << purchasing_xml if has_purchasing?
 
       doc.to_s
-    end
+    end # rest_xml
 
   end # class Computer