Module: JSS::ManagementHistory::ClassMethods

Defined in:
lib/jss/api_object/management_history.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#app_store_app_history(ident, status = nil, api: JSS.api) ⇒ Array Also known as: managed_app_history

Wrapper for app store history for both computers and mobile devices

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • status (Symbol) (defaults to: nil) —

    Return only the :installed, :pending, or :failed apps

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

  • (Array) —

    An array of MacAppStoreApp or MobileDeviceApp



426
427
428
429
430
431
432
 
# File 'lib/jss/api_object/management_history.rb', line 426

def app_store_app_history(ident, status = nil, api: JSS.api)
  if self == JSS::MobileDevice
    mobile_device_app_history(ident, status, api: api)
  else
    mac_app_store_app_history(ident, status, api: api)
  end
end

#audit_history(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::AuditEvent> Also known as: audits

The history of Audit events for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



222
223
224
225
 
# File 'lib/jss/api_object/management_history.rb', line 222

def audit_history(ident, api: JSS.api)
  hist = management_history(ident, :audits, api: api)
  hist.map! { |aud| JSS::ManagementHistory::AuditEvent.new aud }
end

#casper_imaging_logs(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::CasperImagingLog>

The history of Casper Imaging events for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



471
472
473
474
475
 
# File 'lib/jss/api_object/management_history.rb', line 471

def casper_imaging_logs(ident, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have casper imaging logs' unless self == JSS::Computer
  hist = management_history(ident, :casper_imaging_logs, api: api)
  hist.map! { |evt| JSS::ManagementHistory::CasperImagingLog.new evt }
end

#casper_remote_logs(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::CasperRemoteLog>

The history of Casper Remote events for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



486
487
488
489
490
 
# File 'lib/jss/api_object/management_history.rb', line 486

def casper_remote_logs(ident, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have casper remote logs' unless self == JSS::Computer
  hist = management_history(ident, :casper_remote_logs, api: api)
  hist.map! { |evt| JSS::ManagementHistory::CasperRemoteLog.new evt }
end

#completed_mdm_commands(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MDMCommand> Also known as: completed_commands

The history of completed mdm commands for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



291
292
293
 
# File 'lib/jss/api_object/management_history.rb', line 291

def completed_mdm_commands(ident, api: JSS.api)
  mdm_command_history(ident, :completed, api: api)
end

#completed_policies(ident, api: JSS.api) ⇒ Object

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

See Also:

  • ManagementHistory::ClassMethods.policy_logs


541
542
543
 
# File 'lib/jss/api_object/management_history.rb', line 541

def completed_policies(ident, api: JSS.api)
  policy_logs(ident, api: api).select { |pl| pl.status == :completed }
end

#computer_usage_logs(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::ComputerUsageLog> Also known as: usage_logs

The history of usage events for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



501
502
503
504
505
 
# File 'lib/jss/api_object/management_history.rb', line 501

def computer_usage_logs(ident, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have usage logs' unless self == JSS::Computer
  hist = management_history(ident, :computer_usage_logs, api: api)
  hist.map! { |evt| JSS::ManagementHistory::ComputerUsageLog.new evt }
end

#ebook_history(ident, status = nil, api: JSS.api) ⇒ Array<JSS::ManagementHistory::EBook> Also known as: managed_ebook_history

The history of ebooks for a mobile device

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • status (Symbol) (defaults to: nil) —

    Return only the :installed, :pending, or :failed apps

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
 
# File 'lib/jss/api_object/management_history.rb', line 563

def ebook_history(ident, status = nil, api: JSS.api)
  raise JSS::UnsupportedError, 'Only mobile devices have ebooks' unless self == JSS::MobileDevice

  hist = management_history(ident, :ebooks, api: api)
  if status
    raise JSS::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
    statuses_to_do = [status]
  else
    statuses_to_do = HIST_APP_STATUSES
  end # if status

  result = []

  statuses_to_do.each do |a_status|
    # merge the sources of installed apps into their hashes
    books =
      if a_status == :installed
        instbooks = []
        hist[a_status].each do |src, books_from_src|
          real_src =
            case src
            when HIST_RAW_SOURCE_EBOOK_IN_HOUSE then HIST_SOURCE_IN_HOUSE
            when HIST_RAW_SOURCE_IBOOKSTORE then HIST_SOURCE_IBOOKSTORE
            else HIST_SOURCE_OTHER
            end # case src
          instbooks += books_from_src.map! { |book| book[:source] = real_src }
        end
        instbooks
      else
        hist[a_status]
      end
    # now 'books' is an array of hashes of books with the same status
    # and if they are :installed, their source is in the hash

    # merge the statuses of the books into their hashes
    result += books.map! do |book|
      # set the :status in the hash
      book[:status] = a_status
      JSS::ManagementHistory::EBook.new book
    end # map do |books|
  end # statuses_to_do.each do |a_status|

  result
end

#failed_app_store_apps(ident, api: JSS.api) ⇒ Object Also known as: failed_managed_apps

shortcut for app_store_app_history where status = :failed

See Also:



457
458
459
 
# File 'lib/jss/api_object/management_history.rb', line 457

def failed_app_store_apps(ident, api: JSS.api)
  app_store_app_history(ident, :failed, api: api)
end

#failed_ebooks(ident, api: JSS.api) ⇒ Object Also known as: failed_managed_ebooks

shortcut for ebook_history where status = :failed

See Also:



631
632
633
 
# File 'lib/jss/api_object/management_history.rb', line 631

def failed_ebooks(ident, api: JSS.api)
  ebook_history(ident, :failed, api: api)
end

#failed_mdm_commands(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MDMCommand> Also known as: failed_commands

The history of failed mdm commands for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



319
320
321
 
# File 'lib/jss/api_object/management_history.rb', line 319

def failed_mdm_commands(ident, api: JSS.api)
  mdm_command_history(ident, :failed, api: api)
end

#failed_policies(ident, api: JSS.api) ⇒ Object

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

See Also:

  • ManagementHistory::ClassMethods.policy_logs


548
549
550
 
# File 'lib/jss/api_object/management_history.rb', line 548

def failed_policies(ident, api: JSS.api)
  policy_logs(ident, api: api).select { |pl| pl.status == :failed }
end

#installed_app_store_apps(ident, api: JSS.api) ⇒ Object Also known as: installed_managed_apps

shortcut for app_store_app_history where status = :installed

See Also:



439
440
441
 
# File 'lib/jss/api_object/management_history.rb', line 439

def installed_app_store_apps(ident, api: JSS.api)
  app_store_app_history(ident, :installed, api: api)
end

#installed_ebooks(ident, api: JSS.api) ⇒ Object Also known as: installed_managed_ebooks

shortcut for ebook_history where status = :installed

See Also:



613
614
615
 
# File 'lib/jss/api_object/management_history.rb', line 613

def installed_ebooks(ident, api: JSS.api)
  ebook_history(ident, :installed, api: api)
end

#mac_app_store_app_history(ident, status = nil, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MacAppStoreApp>

The history of app store apps for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • status (Symbol) (defaults to: nil) —

    Return only the :installed, :pending, or :failed apps

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/jss/api_object/management_history.rb', line 335

def mac_app_store_app_history(ident, status = nil, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have mac app store apps' unless self == JSS::Computer

  hist = management_history(ident, :mac_app_store_applications, api: api)
  if status
    raise JSS::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
    statuses_to_do = [status]
  else
    statuses_to_do = HIST_APP_STATUSES
  end # if status

  result = []

  statuses_to_do.each do |a_status|
    result += hist[a_status].map! do |app|
      # set the :status
      app[:status] = a_status
      JSS::ManagementHistory::MacAppStoreApp.new app
    end # map do |cmd|
  end # statuses_to_do.each do |a_status|

  result
end

#management_history(ident, subset = nil, api: JSS.api) ⇒ Hash, Array Also known as: history

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. JSS::Computer.audits(id) or JSS::MobileDevice.audits(id) to get an array of JSS::ManagementHistory::AuditEvent objects

Parameters:

  • ident (Integer, String) —

    An identifier (id, name, serialnumber, macadress or udid) of the computer or device for which to retrieve history

  • subset (Symbol) (defaults to: nil) —

    the subset to return, rather than full history.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    an API connection to use for the query. Defaults to the corrently active API. See APIConnection

Returns:

  • (Hash, Array) —

    The raw full history or subset requested

Raises:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/jss/api_object/management_history.rb', line 189

def management_history(ident, subset = nil, api: JSS.api)
  id = valid_id ident, api: api
  raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} matches identifier: #{ident}" unless id

  if self == JSS::Computer
    @hist_subsets ||= HIST_COMPUTER_SUBSETS
    @hist_rsrc ||= HIST_COMPUTER_RSRC
    @hist_key ||= HIST_COMPUTER_KEY
  else
    @hist_subsets ||= HIST_DEVICE_SUBSETS
    @hist_rsrc ||= HIST_DEVICE_RSRC
    @hist_key ||= HIST_DEVICE_KEY
  end

  if subset
    raise "Subset must be one of :#{@hist_subsets.join ', :'}" unless @hist_subsets.include? subset
    subset_rsrc = @hist_rsrc + "/id/#{id}/subset/#{subset}"
    api.get_rsrc(subset_rsrc)[@hist_key][subset]
  else
    api.get_rsrc(@hist_rsrc + "/id/#{id}")[@hist_key]
  end
end

#mdm_command_history(ident, status = nil, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MDMCommand> Also known as: commands, management_command_history

The history of mdm commands for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • status (Symbol) (defaults to: nil) —

    Return only the :completed, :pending, or :failed commands

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/jss/api_object/management_history.rb', line 253

def mdm_command_history(ident, status = nil, api: JSS.api)
  subset = self == JSS::Computer ? :commands : :management_commands
  hist = management_history(ident, subset, api: api)
  if status
    raise JSS::InvalidDataError, 'status must be one of :completed, :pending, or :failed' unless HIST_MDM_STATUSES.include? status
    statuses_to_do = [status]
  else
    statuses_to_do = HIST_MDM_STATUSES
  end # if status

  result = []

  statuses_to_do.each do |a_status|
    result += hist[a_status].map! do |cmd|
      # failed computer cmds have the error message in cmd[:status]
      # failed mdm commands have them in cmd[:error], where they should be
      cmd[:error] ||= cmd[:status] if a_status == :failed

      # but we always set the :status
      cmd[:status] = a_status

      JSS::ManagementHistory::MDMCommand.new cmd
    end # map do |cmd|
  end # statuses_to_do.each do |a_status|
  result
end

#mobile_device_app_history(ident, status = nil, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MobileDeviceApp>

The history of apps for a mobile device

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • status (Symbol) (defaults to: nil) —

    Return only the :installed, :pending, or :failed apps

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/jss/api_object/management_history.rb', line 370

def mobile_device_app_history(ident, status = nil, api: JSS.api)
  raise JSS::UnsupportedError, 'Only mobile devices have mobile device apps' unless self == JSS::MobileDevice

  hist = management_history(ident, :applications, api: api)
  if status
    raise JSS::InvalidDataError, 'status must be one of :installed, :pending, or :failed' unless HIST_APP_STATUSES.include? status
    statuses_to_do = [status]
  else
    statuses_to_do = HIST_APP_STATUSES
  end # if status

  result = []

  statuses_to_do.each do |a_status|
    # merge the sources of installed apps into their hashes
    apps =
      if a_status == :installed
        instapps = []
        hist[a_status].each do |src, apps_from_src|
          real_src =
            case src
            when HIST_RAW_SOURCE_APP_IN_HOUSE then HIST_SOURCE_IN_HOUSE
            when HIST_RAW_SOURCE_APP_STORE then HIST_SOURCE_APP_STORE
            else HIST_SOURCE_OTHER
            end # case src
          instapps += apps_from_src.map! { |iapp| iapp[:source] = real_src }
        end
        instapps
      else
        hist[a_status]
      end
    # now 'apps' is an array of hashes of apps with the same status
    # and if they are :installed, their source is in the hash

    # merge the statuses of the apps into their hashes
    result += apps.map! do |app|
      # set the :status in the hash
      app[:status] = a_status
      JSS::ManagementHistory::MobileDeviceApp.new app
    end # map do |cmd|
  end # statuses_to_do.each do |a_status|

  result
end

#pending_app_store_apps(ident, api: JSS.api) ⇒ Object Also known as: pending_managed_apps

shortcut for app_store_app_history where status = :pending

See Also:



448
449
450
 
# File 'lib/jss/api_object/management_history.rb', line 448

def pending_app_store_apps(ident, api: JSS.api)
  app_store_app_history(ident, :pending, api: api)
end

#pending_ebooks(ident, api: JSS.api) ⇒ Object Also known as: pending_managed_ebooks

shortcut for ebook_history where status = :pending

See Also:



622
623
624
 
# File 'lib/jss/api_object/management_history.rb', line 622

def pending_ebooks(ident, api: JSS.api)
  ebook_history(ident, :pending, api: api)
end

#pending_mdm_commands(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::MDMCommand> Also known as: pending_commands

The history of pending mdm commands for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



305
306
307
 
# File 'lib/jss/api_object/management_history.rb', line 305

def pending_mdm_commands(ident, api: JSS.api)
  mdm_command_history(ident, :pending, api: api)
end

#policy_logs(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::PolicyLog>

The history of policy execution for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



532
533
534
535
536
 
# File 'lib/jss/api_object/management_history.rb', line 532

def policy_logs(ident, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have policy logs' unless self == JSS::Computer
  hist = management_history(ident, :policy_logs, api: api)
  hist.map! { |evt| JSS::ManagementHistory::PolicyLog.new evt }
end

#screen_sharing_logs(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::ScreenSharingLog>

The history of screen sharing events for a computer

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:

Raises:



517
518
519
520
521
 
# File 'lib/jss/api_object/management_history.rb', line 517

def screen_sharing_logs(ident, api: JSS.api)
  raise JSS::UnsupportedError, 'Only computers have screen sharing logs' unless self == JSS::Computer
  hist = management_history(ident, :screen_sharing_logs, api: api)
  hist.map! { |evt| JSS::ManagementHistory::ScreenSharingLog.new evt }
end

#user_location_history(ident, api: JSS.api) ⇒ Array<JSS::ManagementHistory::UserLocationChange>

The history of User/Location changes for a target

Parameters:

  • ident (Type) —

    The identifier for the object - id, name, sn, udid, etc.

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to use for the query defaults to the currently active connection

Returns:



237
238
239
240
 
# File 'lib/jss/api_object/management_history.rb', line 237

def user_location_history(ident, api: JSS.api)
  hist = management_history(ident, :user_location, api: api)
  hist.map! { |evt| JSS::ManagementHistory::UserLocationChange.new evt }
end