module 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.
Public Instance Methods
Wrapper for app store history for both computers and mobile devices
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param status [Symbol] Return only the :installed, :pending, or :failed apps
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array] An array of MacAppStoreApp
or MobileDeviceApp
# File lib/jamf/api/classic/api_objects/management_history.rb 468 def app_store_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) 469 cnx = api if api 470 471 if self == Jamf::MobileDevice 472 mobile_device_app_history(ident, status, cnx: cnx) 473 else 474 mac_app_store_app_history(ident, status, cnx: cnx) 475 end 476 end
The history of Audit events for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::AuditEvent>] An array of audit events
# File lib/jamf/api/classic/api_objects/management_history.rb 224 def audit_history(ident, api: nil, cnx: Jamf.cnx) 225 cnx = api if api 226 227 hist = management_history(ident, :audits, cnx: cnx) 228 hist.map! { |aud| Jamf::ManagementHistory::AuditEvent.new aud } 229 end
The history of Casper Imaging events for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::CasperImagingLog>] An array of CasperImagingLog
events
# File lib/jamf/api/classic/api_objects/management_history.rb 521 def casper_imaging_logs(ident, api: nil, cnx: Jamf.cnx) 522 cnx = api if api 523 524 raise Jamf::UnsupportedError, 'Only computers have casper imaging logs' unless self == Jamf::Computer 525 hist = management_history(ident, :casper_imaging_logs, cnx: cnx) 526 hist.map! { |evt| Jamf::ManagementHistory::CasperImagingLog.new evt } 527 end
The history of Casper Remote events for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::CasperRemoteLog>] An array of CasperRemoteLog
events
# File lib/jamf/api/classic/api_objects/management_history.rb 538 def casper_remote_logs(ident, api: nil, cnx: Jamf.cnx) 539 cnx = api if api 540 541 raise Jamf::UnsupportedError, 'Only computers have casper remote logs' unless self == Jamf::Computer 542 hist = management_history(ident, :casper_remote_logs, cnx: cnx) 543 hist.map! { |evt| Jamf::ManagementHistory::CasperRemoteLog.new evt } 544 end
The history of completed mdm commands for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MdmCommand>] An array of completed MdmCommands
# File lib/jamf/api/classic/api_objects/management_history.rb 299 def completed_mdm_commands(ident, api: nil, cnx: Jamf.cnx) 300 cnx = api if api 301 302 mdm_command_history(ident, :completed, cnx: cnx) 303 end
The array from .policy_logs, limited to status = :completed @see ManagementHistory::ClassMethods.policy_logs
# File lib/jamf/api/classic/api_objects/management_history.rb 601 def completed_policies(ident, api: nil, cnx: Jamf.cnx) 602 cnx = api if api 603 604 policy_logs(ident, cnx: cnx).select { |pl| pl.status == :completed } 605 end
The history of usage events for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::ComputerUsageLog>] An array of ComputerUsageLog
events
# File lib/jamf/api/classic/api_objects/management_history.rb 555 def computer_usage_logs(ident, api: nil, cnx: Jamf.cnx) 556 cnx = api if api 557 558 raise Jamf::UnsupportedError, 'Only computers have usage logs' unless self == Jamf::Computer 559 hist = management_history(ident, :computer_usage_logs, cnx: cnx) 560 hist.map! { |evt| Jamf::ManagementHistory::ComputerUsageLog.new evt } 561 end
The history of ebooks for a mobile device
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param status [Symbol] Return only the :installed, :pending, or :failed apps
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::Ebook>] An array of Ebook
# File lib/jamf/api/classic/api_objects/management_history.rb 627 def ebook_history(ident, status = nil, api: nil, cnx: Jamf.cnx) 628 cnx = api if api 629 630 raise Jamf::UnsupportedError, 'Only mobile devices have ebooks' unless self == Jamf::MobileDevice 631 632 hist = management_history(ident, :ebooks, cnx: cnx) 633 if status 634 raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status 635 statuses_to_do = [status] 636 else 637 statuses_to_do = HIST_APP_STATUSES 638 end # if status 639 640 result = [] 641 642 statuses_to_do.each do |a_status| 643 # merge the sources of installed apps into their hashes 644 books = 645 if a_status == :installed 646 instbooks = [] 647 hist[a_status].each do |src, books_from_src| 648 real_src = 649 case src 650 when HIST_RAW_SOURCE_EBOOK_IN_HOUSE then HIST_SOURCE_IN_HOUSE 651 when HIST_RAW_SOURCE_IBOOKSTORE then HIST_SOURCE_IBOOKSTORE 652 else HIST_SOURCE_OTHER 653 end # case src 654 instbooks += books_from_src.map! { |book| book[:source] = real_src } 655 end 656 instbooks 657 else 658 hist[a_status] 659 end 660 # now 'books' is an array of hashes of books with the same status 661 # and if they are :installed, their source is in the hash 662 663 # merge the statuses of the books into their hashes 664 result += books.map! do |book| 665 # set the :status in the hash 666 book[:status] = a_status 667 Jamf::ManagementHistory::Ebook.new book 668 end # map do |books| 669 end # statuses_to_do.each do |a_status| 670 671 result 672 end
shortcut for app_store_app_history
where status = :failed
# File lib/jamf/api/classic/api_objects/management_history.rb 505 def failed_app_store_apps(ident, api: nil, cnx: Jamf.cnx) 506 cnx = api if api 507 508 app_store_app_history(ident, :failed, cnx: cnx) 509 end
shortcut for ebook_history
where status = :failed
@see ebook_history
# File lib/jamf/api/classic/api_objects/management_history.rb 701 def failed_ebooks(ident, api: nil, cnx: Jamf.cnx) 702 cnx = api if api 703 704 ebook_history(ident, :failed, cnx: cnx) 705 end
The history of failed mdm commands for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MdmCommand>] An array of failed MdmCommands
# File lib/jamf/api/classic/api_objects/management_history.rb 331 def failed_mdm_commands(ident, api: nil, cnx: Jamf.cnx) 332 cnx = api if api 333 334 mdm_command_history(ident, :failed, cnx: cnx) 335 end
The array from .policy_logs, limited to status = :failed @see ManagementHistory::ClassMethods.policy_logs
# File lib/jamf/api/classic/api_objects/management_history.rb 610 def failed_policies(ident, api: nil, cnx: Jamf.cnx) 611 cnx = api if api 612 613 policy_logs(ident, cnx: cnx).select { |pl| pl.status == :failed } 614 end
shortcut for app_store_app_history
where status = :installed
# File lib/jamf/api/classic/api_objects/management_history.rb 483 def installed_app_store_apps(ident,api: nil, cnx: Jamf.cnx) 484 cnx = api if api 485 486 app_store_app_history(ident, :installed, cnx: cnx) 487 end
shortcut for ebook_history
where status = :installed
@see ebook_history
# File lib/jamf/api/classic/api_objects/management_history.rb 679 def installed_ebooks(ident, api: nil, cnx: Jamf.cnx) 680 cnx = api if api 681 682 ebook_history(ident, :installed, cnx: cnx) 683 end
The time of the most recently completed or failed MDM
command. (knowledge of a failure means the device communicated with us)
For Mobile Devices, this seems to be the best indicator of the real last-contact time, since the last_inventory_update is changed when changes are made via the API.
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Time, nil] An array of completed MdmCommands
# File lib/jamf/api/classic/api_objects/management_history.rb 352 def last_mdm_contact(ident, api: nil, cnx: Jamf.cnx) 353 cnx = api if api 354 355 epochs = completed_mdm_commands(ident, cnx: cnx).map { |cmd| cmd.completed_epoch } 356 epochs += failed_mdm_commands(ident, cnx: cnx).map { |cmd| cmd.failed_epoch } 357 epoch = epochs.max 358 epoch ? JSS.epoch_to_time(epoch) : nil 359 end
The history of app store apps for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param status [Symbol] Return only the :installed, :pending, or :failed apps
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MacAppStoreApp>] An array of MacAppStoreApp
# File lib/jamf/api/classic/api_objects/management_history.rb 373 def mac_app_store_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) 374 cnx = api if api 375 376 raise Jamf::UnsupportedError, 'Only computers have mac app store apps' unless self == Jamf::Computer 377 378 hist = management_history(ident, :mac_app_store_applications, cnx: cnx) 379 if status 380 raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status 381 statuses_to_do = [status] 382 else 383 statuses_to_do = HIST_APP_STATUSES 384 end # if status 385 386 result = [] 387 388 statuses_to_do.each do |a_status| 389 result += hist[a_status].map! do |app| 390 # set the :status 391 app[:status] = a_status 392 Jamf::ManagementHistory::MacAppStoreApp.new app 393 end # map do |cmd| 394 end # statuses_to_do.each do |a_status| 395 396 result 397 end
Return the raw management history for a Computer
or Mobile Device
WARNING: It’s huge, better to use a subset.
NOTE: This returns the raw JSON data from the API, parsed into a ruby Hash
. Use the subset-specific methods to retrieve more consistent arrays of ruby-jss objects for each kind of history event, e.g. Jamf::Computer.audits(id)
or Jamf::MobileDevice.audits(id)
to get an array of Jamf::ManagementHistory::AuditEvent
objects
@param ident [Integer,String] An identifier (id, name, serialnumber,
macadress or udid) of the computer or device for which to retrieve history
@param subset the subset to return, rather than full history.
@param cnx [Jamf::Connection] an API connection to use for the query.
Defaults to the corrently active API. See {Jamf::Connection}
@return [Hash,Array] The raw full history or subset requested
# File lib/jamf/api/classic/api_objects/management_history.rb 189 def management_history(ident, subset = nil, api: nil, cnx: Jamf.cnx) 190 cnx = api if api 191 192 id = valid_id ident, cnx: cnx 193 raise Jamf::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} matches identifier: #{ident}" unless id 194 195 if self == Jamf::Computer 196 @hist_subsets ||= HIST_COMPUTER_SUBSETS 197 @hist_rsrc ||= HIST_COMPUTER_RSRC 198 @hist_key ||= HIST_COMPUTER_KEY 199 else 200 @hist_subsets ||= HIST_DEVICE_SUBSETS 201 @hist_rsrc ||= HIST_DEVICE_RSRC 202 @hist_key ||= HIST_DEVICE_KEY 203 end 204 205 if subset 206 raise "Subset must be one of :#{@hist_subsets.join ', :'}" unless @hist_subsets.include? subset 207 subset_rsrc = @hist_rsrc + "/id/#{id}/subset/#{subset}" 208 cnx.c_get(subset_rsrc)[@hist_key][subset] 209 else 210 cnx.c_get(@hist_rsrc + "/id/#{id}")[@hist_key] 211 end 212 end
The history of mdm commands for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param status [Symbol] Return only the :completed, :pending, or :failed commands
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MdmCommand>] An array of MdmCommands
# File lib/jamf/api/classic/api_objects/management_history.rb 259 def mdm_command_history(ident, status = nil, api: nil, cnx: Jamf.cnx) 260 cnx = api if api 261 262 subset = self == Jamf::Computer ? :commands : :management_commands 263 hist = management_history(ident, subset, cnx: cnx) 264 if status 265 raise Jamf::InvalidDataError, 'status must be one of :completed, :pending, or :failed' unless HIST_MDM_STATUSES.include? status 266 statuses_to_do = [status] 267 else 268 statuses_to_do = HIST_MDM_STATUSES 269 end # if status 270 271 result = [] 272 273 statuses_to_do.each do |a_status| 274 result += hist[a_status].map! do |cmd| 275 # failed computer cmds have the error message in cmd[:status] 276 # failed mdm commands have them in cmd[:error], where they should be 277 cmd[:error] ||= cmd[:status] if a_status == :failed 278 279 # but we always set the :status 280 cmd[:status] = a_status 281 282 Jamf::ManagementHistory::MdmCommand.new cmd 283 end # map do |cmd| 284 end # statuses_to_do.each do |a_status| 285 result 286 end
The history of apps for a mobile device
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param status [Symbol] Return only the :installed, :pending, or :failed apps
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MobileDeviceApp>] An array of MobileDeviceApp
# File lib/jamf/api/classic/api_objects/management_history.rb 410 def mobile_device_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) 411 cnx = api if api 412 413 raise Jamf::UnsupportedError, 'Only mobile devices have mobile device apps' unless self == Jamf::MobileDevice 414 415 hist = management_history(ident, :applications, cnx: cnx) 416 if status 417 raise Jamf::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status 418 statuses_to_do = [status] 419 else 420 statuses_to_do = HIST_APP_STATUSES 421 end # if status 422 423 result = [] 424 425 statuses_to_do.each do |a_status| 426 # merge the sources of installed apps into their hashes 427 apps = 428 if a_status == :installed 429 instapps = [] 430 hist[a_status].each do |src, apps_from_src| 431 real_src = 432 case src 433 when HIST_RAW_SOURCE_APP_IN_HOUSE then HIST_SOURCE_IN_HOUSE 434 when HIST_RAW_SOURCE_APP_STORE then HIST_SOURCE_APP_STORE 435 else HIST_SOURCE_OTHER 436 end # case src 437 instapps += apps_from_src.map! { |iapp| iapp[:source] = real_src } 438 end 439 instapps 440 else 441 hist[a_status] 442 end 443 # now 'apps' is an array of hashes of apps with the same status 444 # and if they are :installed, their source is in the hash 445 446 # merge the statuses of the apps into their hashes 447 result += apps.map! do |app| 448 # set the :status in the hash 449 app[:status] = a_status 450 Jamf::ManagementHistory::MobileDeviceApp.new app 451 end # map do |cmd| 452 end # statuses_to_do.each do |a_status| 453 454 result 455 end
shortcut for app_store_app_history
where status = :pending
# File lib/jamf/api/classic/api_objects/management_history.rb 494 def pending_app_store_apps(ident, api: nil, cnx: Jamf.cnx) 495 cnx = api if api 496 497 app_store_app_history(ident, :pending, cnx: cnx) 498 end
shortcut for ebook_history
where status = :pending
@see ebook_history
# File lib/jamf/api/classic/api_objects/management_history.rb 690 def pending_ebooks(ident, api: nil, cnx: Jamf.cnx) 691 cnx = api if api 692 693 ebook_history(ident, :pending, cnx: cnx) 694 end
The history of pending mdm commands for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::MdmCommand>] An array of pending MdmCommands
# File lib/jamf/api/classic/api_objects/management_history.rb 315 def pending_mdm_commands(ident, api: nil, cnx: Jamf.cnx) 316 cnx = api if api 317 318 mdm_command_history(ident, :pending, cnx: cnx) 319 end
The history of policy execution for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::PolicyLog>] An array of PolicyLog
events
# File lib/jamf/api/classic/api_objects/management_history.rb 590 def policy_logs(ident, api: nil, cnx: Jamf.cnx) 591 cnx = api if api 592 593 raise Jamf::UnsupportedError, 'Only computers have policy logs' unless self == Jamf::Computer 594 hist = management_history(ident, :policy_logs, cnx: cnx) 595 hist.map! { |evt| Jamf::ManagementHistory::PolicyLog.new evt } 596 end
The history of screen sharing events for a computer
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::ScreenSharingLog>] An array of ScreenSharingLog
events
# File lib/jamf/api/classic/api_objects/management_history.rb 573 def screen_sharing_logs(ident, api: nil, cnx: Jamf.cnx) 574 cnx = api if api 575 576 raise Jamf::UnsupportedError, 'Only computers have screen sharing logs' unless self == Jamf::Computer 577 hist = management_history(ident, :screen_sharing_logs, cnx: cnx) 578 hist.map! { |evt| Jamf::ManagementHistory::ScreenSharingLog.new evt } 579 end
The history of User/Location changes for a target
@param ident [Type] The identifier for the object - id, name, sn, udid, etc.
@param cnx [Jamf::Connection] The API connection to use for the query
defaults to the currently active connection
@return [Array<Jamf::ManagementHistory::UserLocationChange>] An array of UserLocation change events
# File lib/jamf/api/classic/api_objects/management_history.rb 241 def user_location_history(ident, api: nil, cnx: Jamf.cnx) 242 cnx = api if api 243 244 hist = management_history(ident, :user_location, cnx: cnx) 245 hist.map! { |evt| Jamf::ManagementHistory::UserLocationChange.new evt } 246 end