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}


644
645
646
 
# File 'lib/jss/api_object/management_history.rb', line 644

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}


737
738
739
 
# File 'lib/jss/api_object/management_history.rb', line 737

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}


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

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}


773
774
775
 
# File 'lib/jss/api_object/management_history.rb', line 773

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}


781
782
783
 
# File 'lib/jss/api_object/management_history.rb', line 781

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}


694
695
696
 
# File 'lib/jss/api_object/management_history.rb', line 694

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}


814
815
816
 
# File 'lib/jss/api_object/management_history.rb', line 814

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}


789
790
791
 
# File 'lib/jss/api_object/management_history.rb', line 789

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}


830
831
832
 
# File 'lib/jss/api_object/management_history.rb', line 830

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}


764
765
766
 
# File 'lib/jss/api_object/management_history.rb', line 764

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}


857
858
859
 
# File 'lib/jss/api_object/management_history.rb', line 857

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}


712
713
714
 
# File 'lib/jss/api_object/management_history.rb', line 712

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}


822
823
824
 
# File 'lib/jss/api_object/management_history.rb', line 822

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}


746
747
748
 
# File 'lib/jss/api_object/management_history.rb', line 746

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}


839
840
841
 
# File 'lib/jss/api_object/management_history.rb', line 839

def installed_ebooks
  self.class.installed_ebooks(@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}


721
722
723
 
# File 'lib/jss/api_object/management_history.rb', line 721

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}


658
659
660
 
# File 'lib/jss/api_object/management_history.rb', line 658

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}


684
685
686
 
# File 'lib/jss/api_object/management_history.rb', line 684

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}


729
730
731
 
# File 'lib/jss/api_object/management_history.rb', line 729

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}


755
756
757
 
# File 'lib/jss/api_object/management_history.rb', line 755

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}


848
849
850
 
# File 'lib/jss/api_object/management_history.rb', line 848

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}


703
704
705
 
# File 'lib/jss/api_object/management_history.rb', line 703

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}


806
807
808
 
# File 'lib/jss/api_object/management_history.rb', line 806

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}


798
799
800
 
# File 'lib/jss/api_object/management_history.rb', line 798

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}


676
677
678
 
# File 'lib/jss/api_object/management_history.rb', line 676

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