Module: Jamf::ManagementHistory

Included in:
Computer, MobileDevice
Defined in:
lib/jamf/api/classic/api_objects/management_history.rb,
lib/jamf/api/classic/api_objects/management_history/ebook.rb,
lib/jamf/api/classic/api_objects/management_history/hash_like.rb,
lib/jamf/api/classic/api_objects/management_history/policy_log.rb,
lib/jamf/api/classic/api_objects/management_history/audit_event.rb,
lib/jamf/api/classic/api_objects/management_history/mdm_command.rb,
lib/jamf/api/classic/api_objects/management_history/casper_remote_log.rb,
lib/jamf/api/classic/api_objects/management_history/mac_app_store_app.rb,
lib/jamf/api/classic/api_objects/management_history/mobile_device_app.rb,
lib/jamf/api/classic/api_objects/management_history/casper_imaging_log.rb,
lib/jamf/api/classic/api_objects/management_history/computer_usage_log.rb,
lib/jamf/api/classic/api_objects/management_history/screen_sharing_log.rb,
lib/jamf/api/classic/api_objects/management_history/user_location_change.rb

Overview

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 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 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.

Defined Under Namespace

Modules: ClassMethods, HashLike Classes: AuditEvent, CasperImagingLog, CasperRemoteLog, ComputerUsageLog, Ebook, MacAppStoreApp, MdmCommand, MobileDeviceApp, PolicyLog, ScreenSharingLog, UserLocationChange

Constant Summary collapse

HIST_RAW_STATUS_COMPLETED =

Constants

'Completed'.freeze
HIST_RAW_STATUS_INSTALLED = 
'Installed'.freeze
HIST_RAW_STATUS_MANAGED = 
'Managed'.freeze
HIST_RAW_STATUS_UNMANAGED = 
'Unmanaged'.freeze
HIST_RAW_STATUS_FAILED = 
'Failed'.freeze
HIST_RAW_STATUS_PENDING = 
'Pending'.freeze
HIST_STATUS_COMPLETED = 
:completed
HIST_STATUS_PENDING = 
:pending
HIST_STATUS_FAILED = 
:failed
HIST_STATUS_INSTALLED = 
:installed
HIST_RAW_SOURCE_APP_IN_HOUSE = 
:in_house_from_mobile_device_app_catalog
HIST_RAW_SOURCE_APP_STORE = 
:app_store_from_mobile_device_app_catalog
HIST_RAW_SOURCE_EBOOK_IN_HOUSE = 
:inhouse
HIST_RAW_SOURCE_IBOOKSTORE = 
:ibookstore
HIST_RAW_SOURCE_OTHER = 
:other
HIST_SOURCE_IN_HOUSE = 
:in_house
HIST_SOURCE_APP_STORE = 
:app_store
HIST_SOURCE_IBOOKSTORE = 
:ibookstore
HIST_SOURCE_OTHER = 
:other
HIST_MDM_STATUSES = 
[HIST_STATUS_COMPLETED, HIST_STATUS_PENDING, HIST_STATUS_FAILED].freeze
HIST_APP_STATUSES = 
[HIST_STATUS_INSTALLED, HIST_STATUS_PENDING, HIST_STATUS_FAILED].freeze
HIST_COMPUTER_RSRC =

The api resource for each history type

'computerhistory'.freeze
HIST_DEVICE_RSRC = 
'mobiledevicehistory'.freeze
HIST_COMPUTER_KEY =

The top-level hash key for the history data of each type

:computer_history
HIST_DEVICE_KEY = 
:mobile_device_history
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.

%i[
  computer_usage_logs
  audits
  policy_logs
  casper_remote_logs
  screen_sharing_logs
  casper_imaging_logs
  commands
  user_location
  mac_app_store_applications
].freeze
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.

%i[
  management_commands
  user_location
  audits
  applications
  ebooks
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(klass) ⇒ Object

Extend ourself when included 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.

See Also:

  • {Jamf{Jamf::ManagementHistory{Jamf::ManagementHistory::ClassMethods}


716
717
718
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 716

def self.included(klass)
  klass.extend Jamf::ManagementHistory::ClassMethods
end

Instance Method Details

#app_store_app_history(status = nil) ⇒ Object Also known as: managed_app_history

Wrapper for app store history for both computers and mobile devices

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


817
818
819
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 817

def app_store_app_history(status = nil)
  self.class.app_store_app_history(@id, status, cnx: @cnx)
end

#audit_history ⇒ Object Also known as: audits

The audit_history for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


739
740
741
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 739

def audit_history
  self.class.audit_history(@id, cnx: @cnx)
end

#casper_imaging_logs ⇒ Object

The casper_imaging_logs for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


853
854
855
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 853

def casper_imaging_logs
  self.class.casper_imaging_logs(@id, cnx: @cnx)
end

#casper_remote_logs ⇒ Object

The casper_remote_logs for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


861
862
863
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 861

def casper_remote_logs
  self.class.casper_remote_logs(@id, cnx: @cnx)
end

#completed_mdm_commands ⇒ Object Also known as: completed_commands

The completed_mdm_commands for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


766
767
768
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 766

def completed_mdm_commands
  self.class.completed_mdm_commands(@id, cnx: @cnx)
end

#completed_policies ⇒ Object

The array from .policy_logs, limited to status = :completed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


894
895
896
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 894

def completed_policies
  self.class.completed_policies(@id, cnx: @cnx)
end

#computer_usage_logs ⇒ Object Also known as: usage_logs

The computer_usage_logs for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


869
870
871
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 869

def computer_usage_logs
  self.class.computer_usage_logs(@id, cnx: @cnx)
end

#ebook_history(status = nil) ⇒ Object Also known as: managed_ebook_history

The ebook_history for this mobile device

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


910
911
912
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 910

def ebook_history(status = nil)
  self.class.ebook_history(@id, status, cnx: @cnx)
end

#failed_app_store_apps ⇒ Object Also known as: failed_managed_apps

shortcut for app_store_app_history where status = :failed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


844
845
846
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 844

def failed_app_store_apps
  self.class.failed_app_store_apps(@id, cnx: @cnx)
end

#failed_ebooks ⇒ Object Also known as: failed_managed_ebooks

shortcut for ebook_history where status = :failed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


937
938
939
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 937

def failed_ebooks
  self.class.failed_ebooks(@id, cnx: @cnx)
end

#failed_mdm_commands ⇒ Object Also known as: failed_commands

The failed_mdm_commands for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


792
793
794
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 792

def failed_mdm_commands
  self.class.failed_mdm_commands(@id, cnx: @cnx)
end

#failed_policies ⇒ Object

The array from .policy_logs, limited to status = :failed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


902
903
904
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 902

def failed_policies
  self.class.failed_policies(@id, cnx: @cnx)
end

#installed_app_store_apps ⇒ Object Also known as: installed_managed_apps

shortcut for app_store_app_history where status = :installed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


826
827
828
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 826

def installed_app_store_apps
  self.class.installed_app_store_apps(@id, cnx: @cnx)
end

#installed_ebooks ⇒ Object Also known as: installed_managed_ebooks

shortcut for ebook_history where status = :installed

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


919
920
921
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 919

def installed_ebooks
  self.class.installed_ebooks(@id, cnx: @cnx)
end

#last_mdm_contact ⇒ Object

The time of the last completed mdm command for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


775
776
777
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 775

def last_mdm_contact
  self.class.last_mdm_contact(@id, cnx: @cnx)
end

#mac_app_store_app_history(status = nil) ⇒ Object

The mac_app_store_app_history for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


801
802
803
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 801

def mac_app_store_app_history(status = nil)
  self.class.mac_app_store_app_history(@id, status, cnx: @cnx)
end

#management_history(subset = nil) ⇒ Object Also known as: history

The raw management history data for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


730
731
732
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 730

def management_history(subset = nil)
  self.class.management_history(@id, subset, cnx: @cnx)
end

#mdm_command_history(status = nil) ⇒ Object Also known as: commands, management_command_history

The mdm_command_history for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


756
757
758
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 756

def mdm_command_history(status = nil)
  self.class.mdm_command_history(@id, status, cnx: @cnx)
end

#mobile_device_app_history(status = nil) ⇒ Object

The mobile_device_app_history for this mobile device

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


809
810
811
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 809

def mobile_device_app_history(status = nil)
  self.class.mobile_device_app_history(@id, status, cnx: @cnx)
end

#pending_app_store_apps ⇒ Object Also known as: pending_managed_apps

shortcut for app_store_app_history where status = :pending

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


835
836
837
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 835

def pending_app_store_apps
  self.class.pending_app_store_apps(@id, cnx: @cnx)
end

#pending_ebooks ⇒ Object Also known as: pending_managed_ebooks

shortcut for ebook_history where status = :pending

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


928
929
930
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 928

def pending_ebooks
  self.class.pending_ebooks(@id, cnx: @cnx)
end

#pending_mdm_commands ⇒ Object Also known as: pending_commands

The pending_mdm_commands for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


783
784
785
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 783

def pending_mdm_commands
  self.class.pending_mdm_commands(@id, cnx: @cnx)
end

#policy_logs ⇒ Object

The policy_logs for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


886
887
888
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 886

def policy_logs
  self.class.policy_logs(@id, cnx: @cnx)
end

#screen_sharing_logs ⇒ Object

The screen_sharing_logs for this computer

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


878
879
880
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 878

def screen_sharing_logs
  self.class.screen_sharing_logs(@id, cnx: @cnx)
end

#user_location_history ⇒ Object

The user_location_history for this object

See Also:

  • matching method in {Jamf::ManagementHistory::ClassMethods}


748
749
750
 
# File 'lib/jamf/api/classic/api_objects/management_history.rb', line 748

def user_location_history
  self.class.user_location_history(@id, cnx: @cnx)
end