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

app_store_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: managed_app_history
audit_history(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: audits
audits(ident, api: nil, cnx: Jamf.cnx)
Alias for: audit_history
casper_imaging_logs(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
casper_remote_logs(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
commands(ident, status = nil, api: nil, cnx: Jamf.cnx)
Alias for: mdm_command_history
completed_commands(ident, api: nil, cnx: Jamf.cnx)
completed_mdm_commands(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: completed_commands
completed_policies(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
computer_usage_logs(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: usage_logs
ebook_history(ident, status = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: managed_ebook_history
failed_app_store_apps(ident, api: nil, cnx: Jamf.cnx) click to toggle source

shortcut for app_store_app_history where status = :failed

@see app_store_app_history

    # 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
Also aliased as: failed_managed_apps
failed_commands(ident, api: nil, cnx: Jamf.cnx)
Alias for: failed_mdm_commands
failed_ebooks(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: failed_managed_ebooks
failed_managed_apps(ident, api: nil, cnx: Jamf.cnx)
failed_managed_ebooks(ident, api: nil, cnx: Jamf.cnx)
Alias for: failed_ebooks
failed_mdm_commands(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: failed_commands
failed_policies(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
history(ident, subset = nil, api: nil, cnx: Jamf.cnx)
Alias for: management_history
installed_app_store_apps(ident,api: nil, cnx: Jamf.cnx) click to toggle source

shortcut for app_store_app_history where status = :installed

@see app_store_app_history

    # 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
Also aliased as: installed_managed_apps
installed_ebooks(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: installed_managed_ebooks
installed_managed_apps(ident,api: nil, cnx: Jamf.cnx)
installed_managed_ebooks(ident, api: nil, cnx: Jamf.cnx)
Alias for: installed_ebooks
last_mdm_contact(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
mac_app_store_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
managed_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx)
managed_ebook_history(ident, status = nil, api: nil, cnx: Jamf.cnx)
Alias for: ebook_history
management_command_history(ident, status = nil, api: nil, cnx: Jamf.cnx)
Alias for: mdm_command_history
management_history(ident, subset = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: history
mdm_command_history(ident, status = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
mobile_device_app_history(ident, status = nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
pending_app_store_apps(ident, api: nil, cnx: Jamf.cnx) click to toggle source

shortcut for app_store_app_history where status = :pending

@see app_store_app_history

    # 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
Also aliased as: pending_managed_apps
pending_commands(ident, api: nil, cnx: Jamf.cnx)
pending_ebooks(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: pending_managed_ebooks
pending_managed_apps(ident, api: nil, cnx: Jamf.cnx)
pending_managed_ebooks(ident, api: nil, cnx: Jamf.cnx)
Alias for: pending_ebooks
pending_mdm_commands(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
Also aliased as: pending_commands
policy_logs(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
screen_sharing_logs(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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
usage_logs(ident, api: nil, cnx: Jamf.cnx)
Alias for: computer_usage_logs
user_location_history(ident, api: nil, cnx: Jamf.cnx) click to toggle source

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