Module: JSS::ManagementHistory

Included in:
Computer, MobileDevice
Defined in:
lib/jss/api_object/management_history.rb,
lib/jss.rb,
lib/jss/api_object/management_history/ebook.rb,
lib/jss/api_object/management_history/hashlike.rb,
lib/jss/api_object/management_history/policy_log.rb,
lib/jss/api_object/management_history/audit_event.rb,
lib/jss/api_object/management_history/mdm_command.rb,
lib/jss/api_object/management_history/casper_remote_log.rb,
lib/jss/api_object/management_history/mac_app_store_app.rb,
lib/jss/api_object/management_history/mobile_device_app.rb,
lib/jss/api_object/management_history/casper_imaging_log.rb,
lib/jss/api_object/management_history/computer_usage_log.rb,
lib/jss/api_object/management_history/screen_sharing_log.rb,
lib/jss/api_object/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 JSS::MobileDevice.audit_history method returns an Array of JSS::ManagementHistory::AuditEvent instances, and the 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 - 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, MDMCommand, MacAppStoreApp, 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:

  • {JSS{JSS::ManagementHistory{JSS::ManagementHistory::ClassMethods}


666
667
668
 
# File 'lib/jss/api_object/management_history.rb', line 666

def self.included(klass)
  klass.extend JSS::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 {JSS::ManagementHistory::ClassMethods}


767
768
769
 
# File 'lib/jss/api_object/management_history.rb', line 767

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

#audit_history ⇒ Object Also known as: audits

The audit_history for this object

See Also:

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


689
690
691
 
# File 'lib/jss/api_object/management_history.rb', line 689

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

#casper_imaging_logs ⇒ Object

The casper_imaging_logs for this computer

See Also:

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


803
804
805
 
# File 'lib/jss/api_object/management_history.rb', line 803

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

#casper_remote_logs ⇒ Object

The casper_remote_logs for this computer

See Also:

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


811
812
813
 
# File 'lib/jss/api_object/management_history.rb', line 811

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

#completed_mdm_commands ⇒ Object Also known as: completed_commands

The completed_mdm_commands for this object

See Also:

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


716
717
718
 
# File 'lib/jss/api_object/management_history.rb', line 716

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

#completed_policies ⇒ Object

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

See Also:

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


844
845
846
 
# File 'lib/jss/api_object/management_history.rb', line 844

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

#computer_usage_logs ⇒ Object Also known as: usage_logs

The computer_usage_logs for this computer

See Also:

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


819
820
821
 
# File 'lib/jss/api_object/management_history.rb', line 819

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

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

The ebook_history for this mobile device

See Also:

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


860
861
862
 
# File 'lib/jss/api_object/management_history.rb', line 860

def ebook_history(status = nil)
  self.class.ebook_history(@id, status, api: @api)
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 {JSS::ManagementHistory::ClassMethods}


794
795
796
 
# File 'lib/jss/api_object/management_history.rb', line 794

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

#failed_ebooks ⇒ Object Also known as: failed_managed_ebooks

shortcut for ebook_history where status = :failed

See Also:

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


887
888
889
 
# File 'lib/jss/api_object/management_history.rb', line 887

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

#failed_mdm_commands ⇒ Object Also known as: failed_commands

The failed_mdm_commands for this object

See Also:

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


742
743
744
 
# File 'lib/jss/api_object/management_history.rb', line 742

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

#failed_policies ⇒ Object

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

See Also:

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


852
853
854
 
# File 'lib/jss/api_object/management_history.rb', line 852

def failed_policies
  self.class.failed_policies(@id, api: @api)
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 {JSS::ManagementHistory::ClassMethods}


776
777
778
 
# File 'lib/jss/api_object/management_history.rb', line 776

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

#installed_ebooks ⇒ Object Also known as: installed_managed_ebooks

shortcut for ebook_history where status = :installed

See Also:

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


869
870
871
 
# File 'lib/jss/api_object/management_history.rb', line 869

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

#last_mdm_contact ⇒ Object

The time of the last completed mdm command for this object

See Also:

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


725
726
727
 
# File 'lib/jss/api_object/management_history.rb', line 725

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

#mac_app_store_app_history(status = nil) ⇒ Object

The mac_app_store_app_history for this computer

See Also:

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


751
752
753
 
# File 'lib/jss/api_object/management_history.rb', line 751

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

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

The raw management history data for this object

See Also:

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


680
681
682
 
# File 'lib/jss/api_object/management_history.rb', line 680

def management_history(subset = nil)
  self.class.management_history(@id, subset, api: @api)
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 {JSS::ManagementHistory::ClassMethods}


706
707
708
 
# File 'lib/jss/api_object/management_history.rb', line 706

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

#mobile_device_app_history(status = nil) ⇒ Object

The mobile_device_app_history for this mobile device

See Also:

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


759
760
761
 
# File 'lib/jss/api_object/management_history.rb', line 759

def mobile_device_app_history(status = nil)
  self.class.mobile_device_app_history(@id, status, api: @api)
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 {JSS::ManagementHistory::ClassMethods}


785
786
787
 
# File 'lib/jss/api_object/management_history.rb', line 785

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

#pending_ebooks ⇒ Object Also known as: pending_managed_ebooks

shortcut for ebook_history where status = :pending

See Also:

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


878
879
880
 
# File 'lib/jss/api_object/management_history.rb', line 878

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

#pending_mdm_commands ⇒ Object Also known as: pending_commands

The pending_mdm_commands for this object

See Also:

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


733
734
735
 
# File 'lib/jss/api_object/management_history.rb', line 733

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

#policy_logs ⇒ Object

The policy_logs for this computer

See Also:

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


836
837
838
 
# File 'lib/jss/api_object/management_history.rb', line 836

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

#screen_sharing_logs ⇒ Object

The screen_sharing_logs for this computer

See Also:

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


828
829
830
 
# File 'lib/jss/api_object/management_history.rb', line 828

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

#user_location_history ⇒ Object

The user_location_history for this object

See Also:

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


698
699
700
 
# File 'lib/jss/api_object/management_history.rb', line 698

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