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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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}


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

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