ruby-jss 0.11.0a5 → 0.11.0a6

data/lib/jss.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_connection.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss/api_object.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/account.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/advanced_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/advanced_search/advanced_computer_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/advanced_search/advanced_user_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/building.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/categorizable.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/category.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/computer.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -82,24 +82,12 @@ module JSS
   # which removes the mdm profile, but also makes the machine unmanged by the
   # JSS, setting the management acct to nil, and requring re-enrollment.
   #
-  # === Computer History
+  # === Management History & Logs
   #
-  # 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.
+  # Computer Management History and logs can now be retrieved both from a
+  # Computer instance, and directly via class methods without fetching an
+  # instance. This is handled by the mixed-in {JSS::ManagementHistory} module,
+  # Q.V. for details.
   #
   # === Appication Usage History
   #

data/lib/jss/api_object/computer_invitation.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/creatable.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/criteriable.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/department.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/distribution_point.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/extendable.rb

@@ -1,4 +1,4 @@
-# Copyright 2017 Pixar
+# Copyright 2018 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/extension_attribute.rb

@@ -1,4 +1,4 @@
-# Copyright 2017 Pixar
+# Copyright 2018 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/extension_attribute/computer_extension_attribute.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/extension_attribute/mobile_device_extension_attribute.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/extension_attribute/user_extension_attribute.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/group.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/group/computer_group.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/group/mobile_device_group.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/group/user_group.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/ldap_server.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/locatable.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/management_history.rb

@@ -1,4 +1,4 @@
-### Copyright 2017 Pixar
+### Copyright 2018 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -32,9 +32,9 @@ module JSS
   # Objects mixing in this module have 'management history' in the JSS, which at
   # this point is Computers and MobileDevices
   #
-  # *Important:* this is 'management history', i.e. the history
-  # of mdm commands, locations, apps, and other events that are part of
-  # management and inventory collection.
+  # *Important:* this is 'management history', i.e. the history and logs
+  # of mdm commands, locations, apps, policies, and other events that are part
+  # of management and inventory collection.
   #
   # When viewing the details page for a computer or mobile device in the
   # Web UI, this is the data visible in the 'History' pane of the page.
@@ -52,31 +52,42 @@ module JSS
   # instance methods that are wrappers around the class methods. The methods
   # have the same names, but of course the class methods require arguments
   # specifying the target for which to retrieve data, and which API connection
-  # to use.
+  # to use (defaulting to the currently active connection).
   #
   # == Raw data versus processed data & event object classes
   #
   # The primary data-retrieval method for management history data is
   # {JSS::ManagementHistory.management_history}. This method returns the raw
-  # JSON data from the API, parsed into a ruby Hash.
+  # JSON data from the API, parsed into a Ruby Hash. If you don't specify a
+  # subset, the data returned can be very large.
   #
-  # This data is somewhat inconsistent in it's structure and content across the
-  # different types of history events, but you're welcome to use it if needed.
+  # This data is somewhat inconsistent in its structure and content across the
+  # different subsets of history events, but you're welcome to use it if needed.
   #
   # To provide a more consistent and ruby-like interface to the history events,
   # the remaining methods, which only return subsets of the full dataset, will
   # return Arrays of instances of the classes defined in this module.
   #
-  # For example, the {JSS::ManagementHistory.audit_history} method returns an
-  # Array of JSS::ManagementHistory::AuditEvent instances,  and the
-  # {JSS::ManagementHistory.completed_policies} gives an Array of
-  # JSS::ManagementHistory::PolicyLog objects. These objects are read-only
-  # and provide access to their values via attribute-style methods.
+  # For example, the {JSS::MobileDevice.audit_history} method returns an Array
+  # of JSS::ManagementHistory::AuditEvent instances,  and the
+  # {JSS::Computer.completed_policies} gives an Array of
+  # JSS::ManagementHistory::PolicyLog objects.
+  #
+  # These objects are read-only and provide access to their values via both
+  # attribute-style methods, and hash-like keys, similar to how OpenStruct
+  # objects do.
+  # This means that
+  #    `some_log_event.date_time`
+  # and
+  #    `some_log_event[:date_time]`
+  # are identical.
+  # This *may* help with some backward-compatibility issues.
+  #
   #
   # NOTE: History queries from the API are *not* cached in ruby-jss, like the
-  # APIObject.all data is - it is queried anew every time. For this reason, you
-  # are encouraged to store the results of these methods in variables for later
-  # use if needed.
+  # APIObject.all data is - instead it is queried anew every time. For this reason,
+  # you are encouraged to store the results of these methods in variables for
+  # later use if needed.
   #
   module ManagementHistory
 
@@ -177,7 +188,7 @@ module JSS
       #
       def management_history(ident, subset = nil, api: JSS.api)
         id = valid_id ident, api: api
-        raise JSS::NoSuchItemError, "No #{RSRC_OBJECT_KEY} matches identifier: #{ident}" unless id
+        raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} matches identifier: #{ident}" unless id
 
         if self == JSS::Computer
           @hist_subsets ||= HIST_COMPUTER_SUBSETS
@@ -852,6 +863,7 @@ module JSS
 
 end # module JSS
 
+require 'jss/api_object/management_history/hashlike'
 require 'jss/api_object/management_history/audit_event'
 require 'jss/api_object/management_history/casper_imaging_log'
 require 'jss/api_object/management_history/casper_remote_log'

data/lib/jss/api_object/management_history/audit_event.rb

@@ -17,6 +17,7 @@ module JSS
       :username,
       :date_time_epoch
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] event
       #  @return [String] The description of the event.

data/lib/jss/api_object/management_history/casper_imaging_log.rb

@@ -16,6 +16,7 @@ module JSS
       :status,
       :date_time_epoch
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] status
       #  @return [String] The status of the event.

data/lib/jss/api_object/management_history/casper_remote_log.rb

@@ -16,6 +16,7 @@ module JSS
       :status,
       :date_time_epoch
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] status
       #  @return [String] The status of the event.

data/lib/jss/api_object/management_history/computer_usage_log.rb

@@ -17,6 +17,7 @@ module JSS
       :username,
       :date_time_epoch
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] event
       #  @return [String] The description of the event.

data/lib/jss/api_object/management_history/ebook.rb

@@ -23,6 +23,7 @@ module JSS
       :management_status,
       :source
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] title
       #  @return [String] The name of the ebook.

data/lib/jss/api_object/management_history/hashlike.rb

@@ -0,0 +1,24 @@
+#
+module JSS
+
+  #
+  module ManagementHistory
+
+    # This is mixed in to the history event classes to
+    # provide hash-like access to their attributes, so that
+    #    `some_event[:date_time]`
+    # works the same as
+    #     `some_event.date_time`
+    # just as with OpenStruct objects
+    #
+    module HashLike
+
+      def [](attr)
+        self.send attr.to_sym
+      end
+
+    end # HashLike
+
+  end # module ManagementHistory
+
+end # module JSS

data/lib/jss/api_object/management_history/mac_app_store_app.rb

@@ -23,6 +23,7 @@ module JSS
       :last_update_epoch,
       :size_mb
     )
+      include JSS::ManagementHistory::HashLike
 
       # @!attribute [r] name
       #   @return [String] the name of the app.

data/lib/jss/api_object/management_history/mdm_command.rb

@@ -25,6 +25,7 @@ module JSS
       :completed_epoch,
       :last_push_epoch
     )
+      include JSS::ManagementHistory::HashLike
 
       def initialize(args = {})
         args[:completed_epoch] ||= args[:date_time_completed_epoch]

data/lib/jss/api_object/management_history/mobile_device_app.rb

@@ -25,6 +25,8 @@ module JSS
       :dynamic_size
     )
 
+      include JSS::ManagementHistory::HashLike
+
       # @!attribute [r] name
       #   @return [String] the name of the app.
 

data/lib/jss/api_object/management_history/policy_log.rb

@@ -19,6 +19,7 @@ module JSS
       :date_completed_epoch,
       :status
     )
+      include JSS::ManagementHistory::HashLike
 
       def initialize(args = {})
         # we want the status as a Symbol