module Jamf::ManagementHistory
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 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.
It is not the same as ‘object history’ which are the changes made to a JSS
object in the database, e.g. edits & notes by admins or automated processes in the JSS
web UI or via the API. Object
history is visble in the Web UI by clicking the ‘History’ button at the bottom of a machine’s details page.
Class & Instance Methods¶ ↑
This module provides both class methods, which can be used to retrieve history data without instantiating a full Computer
or MobileDevice
, and 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 (defaulting to the currently active connection).
Raw data versus processed data & event object classes¶ ↑
The primary data-retrieval method for management history data is {Jamf::ManagementHistory.management_history}. This method returns the raw 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 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 {Jamf::MobileDevice.audit_history} method returns an Array
of Jamf::ManagementHistory::AuditEvent
instances, and the {Jamf::Computer.completed_policies} gives an Array
of Jamf::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 - 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.
Constants
- HIST_APP_STATUSES
- HIST_COMPUTER_KEY
The top-level hash key for the history data of each type
- HIST_COMPUTER_RSRC
The api resource for each history type
- HIST_COMPUTER_SUBSETS
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.
- HIST_DEVICE_KEY
- HIST_DEVICE_RSRC
- HIST_DEVICE_SUBSETS
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.
- HIST_MDM_STATUSES
- HIST_RAW_SOURCE_APP_IN_HOUSE
- HIST_RAW_SOURCE_APP_STORE
- HIST_RAW_SOURCE_EBOOK_IN_HOUSE
- HIST_RAW_SOURCE_IBOOKSTORE
- HIST_RAW_SOURCE_OTHER
- HIST_RAW_STATUS_COMPLETED
- HIST_RAW_STATUS_FAILED
- HIST_RAW_STATUS_INSTALLED
- HIST_RAW_STATUS_MANAGED
- HIST_RAW_STATUS_PENDING
- HIST_RAW_STATUS_UNMANAGED
- HIST_SOURCE_APP_STORE
- HIST_SOURCE_IBOOKSTORE
- HIST_SOURCE_IN_HOUSE
- HIST_SOURCE_OTHER
- HIST_STATUS_COMPLETED
- HIST_STATUS_FAILED
- HIST_STATUS_INSTALLED
- HIST_STATUS_PENDING
Public Class Methods
Extend ourself when included @see {Jamf::ManagementHistory::ClassMethods}
See codereview.stackexchange.com/questions/23637/mixin-both-instance-and-class-methods-in-ruby for discussion of this technique for mixing in both Class and Instance methods when including a module.
# File lib/jamf/api/classic/api_objects/management_history.rb 716 def self.included(klass) 717 klass.extend Jamf::ManagementHistory::ClassMethods 718 end
Public Instance Methods
Wrapper for app store history for both computers and mobile devices
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 817 def app_store_app_history(status = nil) 818 self.class.app_store_app_history(@id, status, cnx: @cnx) 819 end
The audit_history
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 739 def audit_history 740 self.class.audit_history(@id, cnx: @cnx) 741 end
The casper_imaging_logs
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 853 def casper_imaging_logs 854 self.class.casper_imaging_logs(@id, cnx: @cnx) 855 end
The casper_remote_logs
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 861 def casper_remote_logs 862 self.class.casper_remote_logs(@id, cnx: @cnx) 863 end
The completed_mdm_commands
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 766 def completed_mdm_commands 767 self.class.completed_mdm_commands(@id, cnx: @cnx) 768 end
The array from .policy_logs, limited to status = :completed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 894 def completed_policies 895 self.class.completed_policies(@id, cnx: @cnx) 896 end
The computer_usage_logs
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 869 def computer_usage_logs 870 self.class.computer_usage_logs(@id, cnx: @cnx) 871 end
The ebook_history
for this mobile device
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 910 def ebook_history(status = nil) 911 self.class.ebook_history(@id, status, cnx: @cnx) 912 end
shortcut for app_store_app_history
where status = :failed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 844 def failed_app_store_apps 845 self.class.failed_app_store_apps(@id, cnx: @cnx) 846 end
shortcut for ebook_history
where status = :failed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 937 def failed_ebooks 938 self.class.failed_ebooks(@id, cnx: @cnx) 939 end
The failed_mdm_commands
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 792 def failed_mdm_commands 793 self.class.failed_mdm_commands(@id, cnx: @cnx) 794 end
The array from .policy_logs, limited to status = :failed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 902 def failed_policies 903 self.class.failed_policies(@id, cnx: @cnx) 904 end
shortcut for app_store_app_history
where status = :installed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 826 def installed_app_store_apps 827 self.class.installed_app_store_apps(@id, cnx: @cnx) 828 end
shortcut for ebook_history
where status = :installed
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 919 def installed_ebooks 920 self.class.installed_ebooks(@id, cnx: @cnx) 921 end
The time of the last completed mdm command for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 775 def last_mdm_contact 776 self.class.last_mdm_contact(@id, cnx: @cnx) 777 end
The mac_app_store_app_history
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 801 def mac_app_store_app_history(status = nil) 802 self.class.mac_app_store_app_history(@id, status, cnx: @cnx) 803 end
The raw management history data for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 730 def management_history(subset = nil) 731 self.class.management_history(@id, subset, cnx: @cnx) 732 end
The mdm_command_history
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 756 def mdm_command_history(status = nil) 757 self.class.mdm_command_history(@id, status, cnx: @cnx) 758 end
The mobile_device_app_history
for this mobile device
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 809 def mobile_device_app_history(status = nil) 810 self.class.mobile_device_app_history(@id, status, cnx: @cnx) 811 end
shortcut for app_store_app_history
where status = :pending
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 835 def pending_app_store_apps 836 self.class.pending_app_store_apps(@id, cnx: @cnx) 837 end
shortcut for ebook_history
where status = :pending
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 928 def pending_ebooks 929 self.class.pending_ebooks(@id, cnx: @cnx) 930 end
The pending_mdm_commands
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 783 def pending_mdm_commands 784 self.class.pending_mdm_commands(@id, cnx: @cnx) 785 end
The policy_logs
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 886 def policy_logs 887 self.class.policy_logs(@id, cnx: @cnx) 888 end
The screen_sharing_logs
for this computer
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 878 def screen_sharing_logs 879 self.class.screen_sharing_logs(@id, cnx: @cnx) 880 end
The user_location_history
for this object
@see the matching method in {Jamf::ManagementHistory::ClassMethods}
# File lib/jamf/api/classic/api_objects/management_history.rb 748 def user_location_history 749 self.class.user_location_history(@id, cnx: @cnx) 750 end