Class: JSS::MobileDevice

Inherits:
APIObject show all
Extended by:
Matchable
Includes:
Extendable, Locatable, Purchasable, Updatable, Uploadable
Defined in:
lib/jss/api_object/mobile_device.rb,
lib/jss.rb

Overview

This class represents a Mobile Device stored in the JSS.

Adding devices to the JSS

This class cannot be used to add new mobile devices to the JSS. That can only be done via the enrollment process. See JSS::MobileDeviceInvitation for sending an enrollment invite to a device.

Editing values

Only a few values can be changed via the API, using these methods, q.v:

  • #asset_tag= String

  • #extension_attribute= Hash of :name or :id, and :value

  • #location= Hash of values in @location, not all are required

  • #purchasing= Hash of values in @purchasing, not all are required

After modfying any values, #save must be called to save changes to the JSS.

MDM Commands

The following methods can be used to send an APNS command to the device represented by an instance of JSS::MobileDevice, equivalent to clicking one of the buttons on the Management Commands section of the Management tab of the Mobile Device details page in the JSS UI.

The methods supported are:

  • blank_push (aliases blank, noop, send_blank_push)

  • update_inventory (alias recon)

  • device_lock (aliases lock, lock_device)

  • erase_device (aliases wipe)

  • clear_passcode

  • unmanage_device (alias unmanage)

Each returns true if the command as sent.

See Also:

Constant Summary collapse

RSRC_BASE =

The base for REST resources of this class

'mobiledevices'.freeze
RSRC_LIST_KEY =

the hash key used for the JSON list output of all objects in the JSS

:mobile_devices
RSRC_OBJECT_KEY =

The hash key used for the JSON object output. It’s also used in various error messages

:mobile_device
VALID_DATA_KEYS =

these keys, as well as :id and :name, are present in valid API JSON data for this class

i[device_name capacity tethered].freeze
OTHER_LOOKUP_KEYS =

these keys, as well as :id and :name, can be used to look up objects of this class in the JSS

{
  udid: { rsrc_key: :udid, list: :all_udids },
  serialnumber: { rsrc_key: :serialnumber, list: :all_serial_numbers },
  serial_number: { rsrc_key: :serialnumber, list: :all_serial_numbers },
  macaddress: { rsrc_key: :macaddress, list: :all_wifi_mac_addresses },
  mac_address: { rsrc_key: :macaddress, list: :all_wifi_mac_addresses }
}.freeze
SEARCH_CLASS =

This class lets us seach for computers

JSS::AdvancedMobileDeviceSearch
EXT_ATTRIB_CLASS =

This is the class for relevant Extension Attributes

JSS::MobileDeviceExtensionAttribute
MDM_RSRC =

the rsrc for mobile dev commands

'mobiledevicecommands/command'.freeze
MDM_COMMANDS =

The MDM commands sendable via the api and alternative versions

{
  blank_push: 'BlankPush',
  send_blank_push: 'BlankPush',
  blank: 'BlankPush',
  noop: 'BlankPush',

  settings: 'Settings',

  update_inventory: 'UpdateInventory',
  recon: 'UpdateInventory',

  device_lock: 'DeviceLock',
  lock: 'DeviceLock',
  lock_device: 'DeviceLock',

  erase_device: 'EraseDevice',
  erase: 'EraseDevice',
  wipe: 'EraseDevice',

  clear_passcode: 'ClearPasscode',

  clear_restrictions_password: 'ClearRestrictionsPassword',

  enable_data_roaming: 'SettingsEnableDataRoaming',
  disable_data_roaming: 'SettingsDisableDataRoaming',

  enable_voice_roaming: 'SettingsEnableVoiceRoaming',
  disable_voice_roaming: 'SettingsDisableVoiceRoaming',

  enable_app_analytics: 'SettingsEnableAppAnalytics',
  disable_app_analytics: 'SettingsDisableAppAnalytics',

  enable_diagnostic_submission: 'SettingsEnableDiagnosticSubmission',
  disable_diagnostic_submission: 'SettingsDisableDiagnosticSubmission',

  # wallpaper: 'Wallpaper',

  device_name: 'DeviceName',

  shutdown_device: 'ShutDownDevice',
  shutdown: 'ShutDownDevice',

  restart_device: 'RestartDevice',
  restart: 'RestartDevice',

  # passcode_lock_grace_period: 'PasscodeLockGracePeriod',

  unmanage_device: 'UnmanageDevice',
  unmanage: 'UnmanageDevice'

}.freeze
MDM_COMMANDS_REQUIRING_DATA =

These MDM commands need extra data.

%w[DeviceLock DeviceName Wallpaper].freeze
HISTORY_RSRC =

The History resource

'mobiledevicehistory'.freeze
HISTORY_SUBSETS =

Available history subsets

i[management_commands user_location audits applications ebooks].freeze
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry

21

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ MobileDevice

Returns a new instance of MobileDevice.

See Also:



504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
 
# File 'lib/jss/api_object/mobile_device.rb', line 504

def initialize(args = {})
  super args

  gen = @init_data[:general]
  @airplay_password = gen[:airplay_password]
  @asset_tag = gen[:asset_tag]
  @available_mb = gen[:available_mb]
  @battery_level = gen[:battery_level]
  @bluetooth_mac_address = gen[:bluetooth_mac_address]
  @capacity_mb = gen[:capacity_mb]
  @computer = gen[:computer]
  @device_id = gen[:device_id]
  @device_name = gen[:device_name]
  @display_name = gen[:display_name]
  @initial_entry_date = JSS.epoch_to_time gen[:initial_entry_date_epoch]
  @ip_address = gen[:ip_address]
  @languages = gen[:languages]
  @last_backup_time = JSS.epoch_to_time gen[:last_backup_time_epoch]
  @last_inventory_update = JSS.epoch_to_time gen[:last_inventory_update_epoch]
  @last_enrollment = JSS.epoch_to_time gen[:last_enrollment_epoch]
  @locales = gen[:locales]
  @managed = gen[:managed]
  @supervised = gen[:supervised]
  @model_display = gen[:model_display]
  @model_identifier = gen[:model_identifier]
  @modem_firmware = gen[:modem_firmware]
  @os_build = gen[:os_build]
  @os_version = gen[:os_version]
  @percentage_used = gen[:percentage_used]
  @phone_number = gen[:phone_number]
  @serial_number = gen[:serial_number]
  @site = JSS::APIObject.get_name(gen[:site])
  @supervised = gen[:supervised]
  @tethered = gen[:tethered]
  @udid = gen[:udid]
  @wifi_mac_address = gen[:wifi_mac_address]

  @mobile_device_groups = @init_data[:mobile_device_groups]
  @network = @init_data[:network]
  @extension_attributes = @init_data[:extension_attributes]
  @certificates = @init_data[:certificates]
  @configuration_profiles = @init_data[:configuration_profiles]
  @provisioning_profiles = @init_data[:provisioning_profiles]
  @security = @init_data[:security]
  @applications = @init_data[:applications]
end

Instance Attribute Details

#airplay_password ⇒ String (readonly)

Returns the airplay passwd on devices that can receive AirPlay (i.e. apple tvs).

Returns:

  • (String) —

    the airplay passwd on devices that can receive AirPlay (i.e. apple tvs)



333
334
335
 
# File 'lib/jss/api_object/mobile_device.rb', line 333

def airplay_password
  @airplay_password
end

#applecare_id ⇒ String Originally defined in module Purchasable

Returns:

#applications ⇒ Array<Hash> (readonly)

Returns the applications on the devices.

Returns:

  • (Array<Hash>) —

    the applications on the devices



427
428
429
 
# File 'lib/jss/api_object/mobile_device.rb', line 427

def applications
  @applications
end

#asset_tag ⇒ String (readonly)

Returns the asset tag.

Returns:



336
337
338
 
# File 'lib/jss/api_object/mobile_device.rb', line 336

def asset_tag
  @asset_tag
end

#available_mb ⇒ Intger (readonly)

Returns how much space available on the device?.

Returns:

  • (Intger) —

    how much space available on the device?



339
340
341
 
# File 'lib/jss/api_object/mobile_device.rb', line 339

def available_mb
  @available_mb
end

#battery_level ⇒ Integer (readonly) Also known as: battery_percent

Returns what percentage of the battery is remaining.

Returns:

  • (Integer) —

    what percentage of the battery is remaining



348
349
350
 
# File 'lib/jss/api_object/mobile_device.rb', line 348

def battery_level
  @battery_level
end

#bluetooth_mac_address ⇒ String (readonly)

Returns the bluetooth mac addr.

Returns:

  • (String) —

    the bluetooth mac addr



351
352
353
 
# File 'lib/jss/api_object/mobile_device.rb', line 351

def bluetooth_mac_address
  @bluetooth_mac_address
end

#building ⇒ String Originally defined in module Locatable

Returns:

#capacity_mb ⇒ Integer (readonly)

Returns total storage on the device.

Returns:

  • (Integer) —

    total storage on the device



342
343
344
 
# File 'lib/jss/api_object/mobile_device.rb', line 342

def capacity_mb
  @capacity_mb
end

#certificates ⇒ Array<Hash> (readonly)

The certificates on the device

Each has has two keys:

  • :identity => Boolean

  • :common_name => String, possibly a udid

Returns:



436
437
438
 
# File 'lib/jss/api_object/mobile_device.rb', line 436

def certificates
  @certificates
end

#computer ⇒ Hash (readonly)

Returns {:name=>“xxx”, :id=>nnn} the computer associated with this device.

Returns:

  • (Hash) —

    {:name=>“xxx”, :id=>nnn} the computer associated with this device



357
358
359
 
# File 'lib/jss/api_object/mobile_device.rb', line 357

def computer
  @computer
end

#configuration_profiles ⇒ Array<Hash> (readonly)

One for each ConfigurationProfile on the device

The Hash keys are:

  • :identifier => a unique id, often the sams as the uuid

  • :display_name => its name in the JSS

  • :uuid => the ConfigurationProfile uuid

  • :version => a String

Returns:



447
448
449
 
# File 'lib/jss/api_object/mobile_device.rb', line 447

def configuration_profiles
  @configuration_profiles
end

#department ⇒ String Originally defined in module Locatable

Returns:

#device_id ⇒ String (readonly)

Returns what is this??.

Returns:



360
361
362
 
# File 'lib/jss/api_object/mobile_device.rb', line 360

def device_id
  @device_id
end

#email_address ⇒ String Originally defined in module Locatable

Returns:

#ext_attrs ⇒ Hash (readonly) Originally defined in module Extendable

Returns A mapping of Ext Attrib names to their values.

Returns:

  • (Hash) —

    A mapping of Ext Attrib names to their values

#extension_attributes ⇒ Array<Hash> (readonly) Originally defined in module Extendable

Returns The extension attribute values for the object.

Returns:

  • (Array<Hash>) —

    The extension attribute values for the object

#initial_entry_date ⇒ Time (readonly)

Returns uses the value from the API’s initial_entry_date_epoch.

Returns:

  • (Time) —

    uses the value from the API’s initial_entry_date_epoch



366
367
368
 
# File 'lib/jss/api_object/mobile_device.rb', line 366

def initial_entry_date
  @initial_entry_date
end

#ip_address ⇒ String (readonly)

Returns the IP addr.

Returns:



369
370
371
 
# File 'lib/jss/api_object/mobile_device.rb', line 369

def ip_address
  @ip_address
end

#is_leased ⇒ Boolean Also known as: leased? Originally defined in module Purchasable

Returns:

  • (Boolean)

#is_purchased ⇒ Boolean Also known as: purchased? Originally defined in module Purchasable

Returns:

  • (Boolean)

#languages ⇒ String (readonly)

Returns the language setting.

Returns:

  • (String) —

    the language setting



372
373
374
 
# File 'lib/jss/api_object/mobile_device.rb', line 372

def languages
  @languages
end

#last_backup_time ⇒ Time (readonly)

Returns uses the value from the API’s last_backup_time_epoch.

Returns:

  • (Time) —

    uses the value from the API’s last_backup_time_epoch



375
376
377
 
# File 'lib/jss/api_object/mobile_device.rb', line 375

def last_backup_time
  @last_backup_time
end

#last_enrollment ⇒ Time (readonly)

Returns the last time this device enrolled in Jamf.

Returns:

  • (Time) —

    the last time this device enrolled in Jamf



381
382
383
 
# File 'lib/jss/api_object/mobile_device.rb', line 381

def last_enrollment
  @last_enrollment
end

#last_inventory_update ⇒ Time (readonly)

Returns uses the value from the API’s last_inventory_update_utc.

Returns:

  • (Time) —

    uses the value from the API’s last_inventory_update_utc



378
379
380
 
# File 'lib/jss/api_object/mobile_device.rb', line 378

def last_inventory_update
  @last_inventory_update
end

#lease_expires ⇒ Time Originally defined in module Purchasable

Returns:

#life_expectancy ⇒ Integer Originally defined in module Purchasable

Returns:

  • (Integer)

#locales ⇒ String (readonly)

Returns the locales.

Returns:



384
385
386
 
# File 'lib/jss/api_object/mobile_device.rb', line 384

def locales
  @locales
end

#managed ⇒ Boolean (readonly) Also known as: managed?

Returns is this device managed?.

Returns:

  • (Boolean) —

    is this device managed?



387
388
389
 
# File 'lib/jss/api_object/mobile_device.rb', line 387

def managed
  @managed
end

#mobile_device_groups ⇒ Array<Hash> (readonly)

One for each group to which the device belongs

The Hash keys are:

  • :name => the group name

  • :id => the group id in the JSS

Returns:



456
457
458
 
# File 'lib/jss/api_object/mobile_device.rb', line 456

def mobile_device_groups
  @mobile_device_groups
end

#model_display ⇒ String (readonly) Also known as: model

Returns the display name of the model.

Returns:

  • (String) —

    the display name of the model



393
394
395
 
# File 'lib/jss/api_object/mobile_device.rb', line 393

def model_display
  @model_display
end

#model_identifier ⇒ String (readonly)

Returns the model identifier.

Returns:

  • (String) —

    the model identifier



397
398
399
 
# File 'lib/jss/api_object/mobile_device.rb', line 397

def model_identifier
  @model_identifier
end

#modem_firmware ⇒ String (readonly)

Returns the model firmware.

Returns:

  • (String) —

    the model firmware



400
401
402
 
# File 'lib/jss/api_object/mobile_device.rb', line 400

def modem_firmware
  @modem_firmware
end

#name ⇒ String (readonly)

Returns the API’s device_name and display_name are not used.

Returns:

  • (String) —

    the API’s device_name and display_name are not used.



363
364
365
 
# File 'lib/jss/api_object/mobile_device.rb', line 363

def name
  @name
end

#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    do we have unsaved changes?

#network ⇒ Hash (readonly)

A Hash of network data

The Hash keys are:

  • :voice_roaming_enabled=>“Disabled”,

  • :current_mobile_network_code=>“nnn”,

  • :imei=>“nn nnnnnn nnnnnn n”,

  • :home_mobile_country_code=>“nnn”,

  • :iccid=>“nnnn nnnn nnnn nnnn nnnn”,

  • :home_mobile_network_code=>“nnn”,

  • :current_carrier_network=>“”,

  • :data_roaming_enabled=>false,

  • :home_carrier_network=>“AT&T”,

  • :carrier_settings_version=>“16.0”,

  • :roaming=>false,

  • :cellular_technology=>“GSM”,

  • :current_mobile_country_code=>“nnn”

Returns:



476
477
478
 
# File 'lib/jss/api_object/mobile_device.rb', line 476

def network
  @network
end

#os_build ⇒ String (readonly)

Returns the OS build.

Returns:



406
407
408
 
# File 'lib/jss/api_object/mobile_device.rb', line 406

def os_build
  @os_build
end

#os_version ⇒ String (readonly)

Returns the OS version.

Returns:



403
404
405
 
# File 'lib/jss/api_object/mobile_device.rb', line 403

def os_version
  @os_version
end

#percentage_used ⇒ Integer (readonly)

Returns how much of the capacity is in use?.

Returns:

  • (Integer) —

    how much of the capacity is in use?



345
346
347
 
# File 'lib/jss/api_object/mobile_device.rb', line 345

def percentage_used
  @percentage_used
end

#phone ⇒ String Originally defined in module Locatable

Returns:

#phone_number ⇒ String (readonly)

Returns the phone number of the device’s SIM card.

Returns:

  • (String) —

    the phone number of the device’s SIM card



409
410
411
 
# File 'lib/jss/api_object/mobile_device.rb', line 409

def phone_number
  @phone_number
end

#po_date ⇒ Time Originally defined in module Purchasable

Returns:

#po_number ⇒ String Originally defined in module Purchasable

Returns:

#position ⇒ String Originally defined in module Locatable

Returns:

#provisioning_profiles ⇒ Array<Hash> (readonly)

One per provisioning profile

Returns:



482
483
484
 
# File 'lib/jss/api_object/mobile_device.rb', line 482

def provisioning_profiles
  @provisioning_profiles
end

#purchase_price ⇒ Float Originally defined in module Purchasable

Returns:

  • (Float)

#purchasing_account ⇒ String Originally defined in module Purchasable

Returns:

#purchasing_contact ⇒ String Originally defined in module Purchasable

Returns:

#real_name ⇒ String Originally defined in module Locatable

Returns:

#room ⇒ String Originally defined in module Locatable

Returns:

#security ⇒ Hash (readonly)

A Hash of security data

The Hash has these keys, all of which are Boolean

  • :passcode_present=>true,

  • :passcode_compliant=>true,

  • :passcode_compliant_with_profile=>true,

  • :data_protection=>true,

  • :block_level_encryption_capable=>true,

  • :file_level_encryption_capable=>true

Returns:



495
496
497
 
# File 'lib/jss/api_object/mobile_device.rb', line 495

def security
  @security
end

#serial_number ⇒ String (readonly) Also known as: sn, serialnumber

Returns the serial numbee.

Returns:

  • (String) —

    the serial numbee



412
413
414
 
# File 'lib/jss/api_object/mobile_device.rb', line 412

def serial_number
  @serial_number
end

#site ⇒ String (readonly)

Returns the site associated with this device.

Returns:

  • (String) —

    the site associated with this device



415
416
417
 
# File 'lib/jss/api_object/mobile_device.rb', line 415

def site
  @site
end

#supervised ⇒ Boolean (readonly)

Returns Is this device supervised?.

Returns:

  • (Boolean) —

    Is this device supervised?



390
391
392
 
# File 'lib/jss/api_object/mobile_device.rb', line 390

def supervised
  @supervised
end

#tethered ⇒ String (readonly)

Returns the tether state of the device.

Returns:

  • (String) —

    the tether state of the device



421
422
423
 
# File 'lib/jss/api_object/mobile_device.rb', line 421

def tethered
  @tethered
end

#udid ⇒ String (readonly)

Returns the udid.

Returns:



424
425
426
 
# File 'lib/jss/api_object/mobile_device.rb', line 424

def udid
  @udid
end

#username ⇒ String Also known as: user Originally defined in module Locatable

Returns:

#vendor ⇒ String Originally defined in module Purchasable

Returns:

#warranty_expires ⇒ Time Originally defined in module Purchasable

Returns:

#wifi_mac_address ⇒ String (readonly)

Returns the wifi mac addr.

Returns:

  • (String) —

    the wifi mac addr



354
355
356
 
# File 'lib/jss/api_object/mobile_device.rb', line 354

def wifi_mac_address
  @wifi_mac_address
end

Class Method Details

.all_apple_tvs(refresh = false, api: JSS.api) ⇒ Array<Hash>

Returns the list of all iPads.

Returns:



245
246
247
 
# File 'lib/jss/api_object/mobile_device.rb', line 245

def self.all_apple_tvs(refresh = false, api: JSS.api)
  all(refresh, api: API).select { |d| d[:model_identifier].start_with? 'AppleTV' }
end

.all_ipads(refresh = false, api: JSS.api) ⇒ Array<Hash>

Returns the list of all iPads.

Returns:



240
241
242
 
# File 'lib/jss/api_object/mobile_device.rb', line 240

def self.all_ipads(refresh = false, api: JSS.api)
  all(refresh, api: API).select { |d| d[:model].start_with? 'iPad' }
end

.all_iphones(refresh = false, api: JSS.api) ⇒ Array<Hash>

Returns the list of all iPhones.

Returns:



235
236
237
 
# File 'lib/jss/api_object/mobile_device.rb', line 235

def self.all_iphones(refresh = false, api: JSS.api)
  all(refresh, api: API).select { |d| d[:model].start_with? 'iPhone' }
end

.all_mac_addresses(refresh = false, api: JSS.api) ⇒ Array<String>

Returns all mobiledevice wifi mac addrs.

Returns:



215
216
217
 
# File 'lib/jss/api_object/mobile_device.rb', line 215

def self.all_mac_addresses(refresh = false, api: JSS.api)
  all_wifi_mac_addresses(refresh, api: API)
end

.all_managed(refresh = false, api: JSS.api) ⇒ Array<Hash>

Returns the list of all managed mobile devices.

Returns:

  • (Array<Hash>) —

    the list of all managed mobile devices



225
226
227
 
# File 'lib/jss/api_object/mobile_device.rb', line 225

def self.all_managed(refresh = false, api: JSS.api)
  all(refresh, api: API).select { |d| d[:managed] }
end

.all_phone_numbers(refresh = false, api: JSS.api) ⇒ Array<String>

Returns all mobiledevice phone numbers.

Returns:



205
206
207
 
# File 'lib/jss/api_object/mobile_device.rb', line 205

def self.all_phone_numbers(refresh = false, api: JSS.api)
  all(refresh, api: API).map { |i| i[:phone_number] }.reject(&:empty?)
end

.all_serial_numbers(refresh = false, api: JSS.api) ⇒ Array<String>

Returns all mobiledevice serial_numbers.

Returns:



200
201
202
 
# File 'lib/jss/api_object/mobile_device.rb', line 200

def self.all_serial_numbers(refresh = false, api: JSS.api)
  all(refresh, api: API).map { |i| i[:serial_number] }
end

.all_udids(refresh = false, api: JSS.api) ⇒ Array<String>

Returns all mobiledevice udids.

Returns:



220
221
222
 
# File 'lib/jss/api_object/mobile_device.rb', line 220

def self.all_udids(refresh = false, api: JSS.api)
  all(refresh, api: API).map { |i| i[:udid] }
end

.all_unmanaged(refresh = false, api: JSS.api) ⇒ Array<Hash>

Returns the list of all unmanaged mobile devices.

Returns:

  • (Array<Hash>) —

    the list of all unmanaged mobile devices



230
231
232
 
# File 'lib/jss/api_object/mobile_device.rb', line 230

def self.all_unmanaged(refresh = false, api: JSS.api)
  all(refresh, api: API).reject { |d| d[:managed] }
end

.all_wifi_mac_addresses(refresh = false, api: JSS.api) ⇒ Array<String>

Returns all mobiledevice wifi mac addrs.

Returns:



210
211
212
 
# File 'lib/jss/api_object/mobile_device.rb', line 210

def self.all_wifi_mac_addresses(refresh = false, api: JSS.api)
  all(refresh, api: API).map { |i| i[:wifi_mac_address] }
end

.management_history(identifier, subset = nil, api: JSS.api) ⇒ Object

Raises:



298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/jss/api_object/mobile_device.rb', line 298

def self.management_history(identifier, subset = nil, api: JSS.api)
  id = nil
  if identifier.is_a? Integer
    id = identifier
  else
    key = case identifier
    when *all_names(api: api) then :name
    when *all_serial_numbers(api: api) then :serial_number
    when *all_mac_addresses(api: api) then :mac_address
    when *all_udids(api: api) then :udid
    end
    id = map_all_ids_to(key, api: api).invert[identifier]
  end # if identifier.is_a? Integer

  raise JSS::NoSuchItemError, "No MobileDevice found matching #{identifier}" unless id && all_ids(api: api).include?(id)

  rsrc = "#{HISTORY_RSRC}/id/#{id}"

  if subset
    raise "subset must be one of: :#{HISTORY_SUBSETS.join ', :'}" unless HISTORY_SUBSETS.include? subset
    rsrc << "/subset/#{subset}"
  end

  hist = api.get_rsrc(rsrc)[:mobile_device_history]
  subset ? hist[subset] : hist
end

.match(term, api: JSS.api) ⇒ Array<Hash> Originally defined in module Matchable

Perform a match, returning an Array of Hashes, one for each item matched

At the moment, it appears the search is an “exact match” search regardless of the prefs of the user connected to the API.

Parameters:

  • term (String) —

    the term to match.

Returns:

Raises:

.send_mdm_command(targets, command, data = nil, api: JSS.api) ⇒ String

Send an MDM command to one or more mobile devices by id or name

Parameters:

  • targets (String, Integer, Array<String,Integer>) —

    the name or id of the mobile devices to receive the command, or an array of such names or ids, or a comma-separated string of them.

  • command (Symbol) —

    the command to send, one of the keys of MDM_COMMANDS

  • data (String) (defaults to: nil) —

    Some commands require extra data.

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

    the APi to query. Defaults to the currently active API, see APIConnection

Returns:

  • (String) —

    The uuid of the MDM command sent, if applicable (blank pushes do not generate uuids)

Raises:



267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/jss/api_object/mobile_device.rb', line 267

def self.send_mdm_command(targets, command, data = nil, api: JSS.api)
  raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless MDM_COMMANDS.keys.include? command

  command = MDM_COMMANDS[command]
  cmd_rsrc = "#{MDM_RSRC}/#{command}"

  if MDM_COMMANDS_REQUIRING_DATA.include? command
    raise "MDM command '#{command}' requires additional data." unless data
    cmd_rsrc << "/#{data}"
  end

  targets = JSS.to_s_and_a(targets.to_s)[:arrayform] unless targets.is_a? Array

  # make sure its an array of ids
  targets.map! do |md|
    if all_ids(api: api).include? md.to_i
      md.to_i
    elsif all_names(api: api).include? md
      map_all_ids_to(:name, api: api.invert[md])
    else
      raise JSS::NoSuchItemError, "No mobile device found matching '#{md}'"
    end # if
  end # map!

  cmd_rsrc << "/id/#{targets.join ','}"

  result = api.post_rsrc cmd_rsrc, nil
  result =~ %r{<uuid>(.*)</uuid>}
  Regexp.last_match(1)
end

Instance Method Details

#audit_history ⇒ Array<Hash>

The audits subset of the full history The history of ‘auditable’ events.

Returns:



869
870
871
 
# File 'lib/jss/api_object/mobile_device.rb', line 869

def audit_history
  self.class.management_history @id, :audits, api: @api
end

#blank_push ⇒ String Also known as: noop, send_blank_push

Send a blank_push MDM command

Returns:

  • (String) —

    The command uuid

See Also:



557
558
559
 
# File 'lib/jss/api_object/mobile_device.rb', line 557

def blank_push
  self.class.send_mdm_command @id, :blank_push, api: @api
end

#clear_location ⇒ void Originally defined in module Locatable

This method returns an undefined value.

Clear all location data

#clear_passcode ⇒ String

Send a clear_passcode MDM command

Returns:

  • (String) —

    The command uuid

See Also:



599
600
601
 
# File 'lib/jss/api_object/mobile_device.rb', line 599

def clear_passcode
  self.class.send_mdm_command @id, :clear_passcode, api: @api
end

#clear_restrictions_password ⇒ String

Send a ClearRestrictionsPassword MDM command

Returns:

  • (String) —

    The command uuid

See Also:



619
620
621
 
# File 'lib/jss/api_object/mobile_device.rb', line 619

def clear_restrictions_password
  self.class.send_mdm_command @id, :clear_restrictions_password, api: @api
end

#completed_mdm_commands ⇒ Array<Hash>

The history of completed mdm commands.

Returns:

  • (Array<Hash>) —

    Each hash contains a command name and and the timestamp as a JSS epoch value or string. use JSS.epoch_to_time or JSS.parse_time to convert them to Time objects



779
780
781
 
# File 'lib/jss/api_object/mobile_device.rb', line 779

def completed_mdm_commands
  management_command_history[:completed]
end

#device_lock(message) ⇒ String Also known as: lock, lock_device

Send a device_lock MDM command

Parameters:

  • message (String) —

    The message to display on the lock screen.

Returns:

  • (String) —

    The command uuid

See Also:



579
580
581
 
# File 'lib/jss/api_object/mobile_device.rb', line 579

def device_lock(message)
  self.class.send_mdm_command @id, :device_lock, message, api: @api
end

#device_name(new_name) ⇒ String

Send a device_name MDM command

Parameters:

  • new_name (String) —

    The name for the device

Returns:

  • (String) —

    The command uuid

See Also:



711
712
713
 
# File 'lib/jss/api_object/mobile_device.rb', line 711

def device_name(new_name)
  self.class.send_mdm_command @id, :device_name, new_name, api: @api
end

#disable_app_analytics ⇒ String

Send a disable_app_analytics MDM command

Returns:

  • (String) —

    The command uuid

See Also:



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

def disable_app_analytics
  self.class.send_mdm_command @id, :disable_app_analytics, api: @api
end

#disable_data_roaming ⇒ String

Send a disable_data_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



639
640
641
 
# File 'lib/jss/api_object/mobile_device.rb', line 639

def disable_data_roaming
  self.class.send_mdm_command @id, :disable_data_roaming, api: @api
end

#disable_diagnostic_submission ⇒ String

Send a disable_diagnostic_submission MDM command

Returns:

  • (String) —

    The command uuid

See Also:



699
700
701
 
# File 'lib/jss/api_object/mobile_device.rb', line 699

def disable_diagnostic_submission
  self.class.send_mdm_command @id, :disable_diagnostic_submission, api: @api
end

#disable_voice_roaming ⇒ String

Send a disable_voice_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



659
660
661
 
# File 'lib/jss/api_object/mobile_device.rb', line 659

def disable_voice_roaming
  self.class.send_mdm_command @id, :disable_voice_roaming, api: @api
end

#enable_app_analytics ⇒ String

Send a enable_app_analytics MDM command

Returns:

  • (String) —

    The command uuid

See Also:



669
670
671
 
# File 'lib/jss/api_object/mobile_device.rb', line 669

def enable_app_analytics
  self.class.send_mdm_command @id, :enable_app_analytics, api: @api
end

#enable_data_roaming ⇒ String

Send a SettingsEnableDataRoaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



629
630
631
 
# File 'lib/jss/api_object/mobile_device.rb', line 629

def enable_data_roaming
  self.class.send_mdm_command @id, :enable_data_roaming, api: @api
end

#enable_diagnostic_submission ⇒ String

Send a enable_diagnostic_submission MDM command

Returns:

  • (String) —

    The command uuid

See Also:



689
690
691
 
# File 'lib/jss/api_object/mobile_device.rb', line 689

def enable_diagnostic_submission
  self.class.send_mdm_command @id, :enable_diagnostic_submission, api: @api
end

#enable_voice_roaming ⇒ String

Send a enable_voice_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



649
650
651
 
# File 'lib/jss/api_object/mobile_device.rb', line 649

def enable_voice_roaming
  self.class.send_mdm_command @id, :enable_voice_roaming, api: @api
end

#erase_device ⇒ String Also known as: erase, wipe

Send an erase_device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



589
590
591
 
# File 'lib/jss/api_object/mobile_device.rb', line 589

def erase_device
  self.class.send_mdm_command @id, :erase_device, api: @api
end

#ext_attr_xml ⇒ REXML::Element Originally defined in module Extendable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns An <extension_attribute> element to be included in the rest_xml of objects that mix-in this module.

Returns:

  • (REXML::Element) —

    An <extension_attribute> element to be included in the rest_xml of objects that mix-in this module.

#failed_managed_apps ⇒ Array<Hash>

An array of data about failed managed app installs

Returns:

  • (Array<Hash>) —

    The name: and version: of each failed app install.



860
861
862
 
# File 'lib/jss/api_object/mobile_device.rb', line 860

def failed_managed_apps
  managed_app_history[:failed]
end

#failed_managed_ebooks ⇒ Array<Hash>

Mananged ebooks tha failed installation

Returns:

  • (Array<Hash>) —

    The failed ebook installs



919
920
921
 
# File 'lib/jss/api_object/mobile_device.rb', line 919

def failed_managed_ebooks
  managed_ebook_history[:failed]
end

#failed_mdm_commands ⇒ Array<Hash>

The history of failed mdm commands.

Returns:

  • (Array<Hash>) —

    Each hash contains a command name and an :error message and timestamps for issuance and failure as JSS epoch values or strings. use JSS.epoch_to_time or JSS.parse_time to convert them to Time objects



801
802
803
 
# File 'lib/jss/api_object/mobile_device.rb', line 801

def failed_mdm_commands
  management_command_history[:failed]
end

#has_location? ⇒ Boolean Originally defined in module Locatable

Returns Does this item have location data?.

Returns:

  • (Boolean) —

    Does this item have location data?

#has_purchasing? ⇒ Boolean Originally defined in module Purchasable

Returns does this item have any purchasing info?.

Returns:

  • (Boolean) —

    does this item have any purchasing info?

#installed_managed_apps(from = :all) ⇒ Hash{Array<Hash>}, Array<Hash>

The apps that have been installed via MDM

Parameters:

  • from (Symbol) (defaults to: :all) —

    :in_house, :app_store, :other, or :all. Defaults to :all

Returns:

  • (Hash{Array<Hash>}) —

    When from = :all, all three sources.

  • (Array<Hash>) —

    When from = :in_house, :app_store, or :other the managed apps that have been installed from that source. Each Hash includes these keys:

    name:
version:
short_version:
management_status:
bundle_size:
dynamic_size:



832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
 
# File 'lib/jss/api_object/mobile_device.rb', line 832

def installed_managed_apps(from = :all)
  all = managed_app_history[:installed]
  case from
  when :all
    all
  when :in_house
    all[:in_house_from_mobile_device_app_catalog]
  when :app_store
    all[:app_store_from_mobile_device_app_catalog]
  when :other
    all[:other]
  else
    raise JSS::InvalidDataError, "Unknown mobiledevice app source: '#{from}'"
  end
end

#installed_managed_ebooks(from = :all) ⇒ Hash{Array<Hash>}, Array<Hash>

The ebooks that have been installed via MDM

Parameters:

  • from (Symbol) (defaults to: :all) —

    :in_house, :ibookstore, or :all. Defaults to :all

Returns:

  • (Hash{Array<Hash>}) —

    When from = :all, all three sources.

  • (Array<Hash>) —

    When from = :in_house, :app_store, or :other the managed apps that have been installed from that source.



893
894
895
896
897
898
899
900
901
902
903
904
905
 
# File 'lib/jss/api_object/mobile_device.rb', line 893

def installed_managed_ebooks(from = :all)
  all = managed_ebook_history[:installed]
  case from
  when :all
    all
  when :in_house
    all[:inhouse]
  when :ibookstore
    all[:ibookstore]
  else
    raise JSS::InvalidDataError, "Unknown ebook source: '#{from}'"
  end
end

#location ⇒ Hash<String> Originally defined in module Locatable

All the location data in a Hash, as it comes from the API.

The reason it isn’t stored this way is to prevent editing of the hash directly.

Returns:

#location_xml ⇒ REXML::Element Originally defined in module Locatable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return a REXML <location> element to be included in the rest_xml of objects that have a Location subset

Returns:

  • (REXML::Element)

#managed_app_history ⇒ Hash

The applications subset of the full history

Returns:

  • (Hash) —

    Keys are :installed, :pending, and :failed See #installed_managed_apps, #pending_managed_apps and #failed_managed_apps



811
812
813
 
# File 'lib/jss/api_object/mobile_device.rb', line 811

def managed_app_history
  self.class.management_history @id, :applications, api: @api
end

#managed_ebook_history ⇒ Hash

The ebooks subset of the full history

Returns:

  • (Hash) —

    Keys are :installed, :pending, and :failed See #installed_managed_ebooks, #pending_managed_ebooks and #failed_managed_ebooks



879
880
881
 
# File 'lib/jss/api_object/mobile_device.rb', line 879

def managed_ebook_history
  self.class.management_history @id, :ebooks, api: @api
end

#management_command_history ⇒ Hash Also known as: mdm_command_history

The management_commands subset of the full history

Returns:

  • (Hash) —

    A hash of :completed, :pending, and :failed mdm commands, each being an array of hashes. see #completed_mdm_commands, #pending_mdm_commands and #failed_mdm_commands



767
768
769
 
# File 'lib/jss/api_object/mobile_device.rb', line 767

def management_command_history
  self.class.management_history @id, :management_commands, api: @api
end

#management_history ⇒ Hash

The full management History data for this Mobile Device

Returns:

  • (Hash) —

    Keys are: general: Hash of identifiers user_location: see user_location_history management_commands: see management_command_history audits: see audit_history applications: see managed_app_history ebooks: see managed



745
746
747
 
# File 'lib/jss/api_object/mobile_device.rb', line 745

def management_history
  self.class.management_history @id, api: @api
end

#name=(newname) ⇒ void Originally defined in module Updatable

This method returns an undefined value.

Change the name of this item Remember to #update to push changes to the server.

Parameters:

  • newname (String) —

    the new name

Raises:

#parse_ext_attrs ⇒ void Originally defined in module Extendable

This method returns an undefined value.

Populate @extension_attributes (the Array of Hashes that comes from the API) and @ext_attr_names, which is a Hash mapping the EA names to their index in the @extension_attributes Array.

Classes including this module should call this in #initialize

#parse_location ⇒ void Originally defined in module Locatable

This method returns an undefined value.

Call this during initialization of objects that have a Location subset and the location attributes will be populated (as primary attributes) from @init_data

#parse_purchasing ⇒ Object Originally defined in module Purchasable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Call this during initialization of objects that have a Purchasing subset and the purchasing attribute will be populated from @init_data

#pending_managed_apps ⇒ Array<Hash>

An array of pending managed app installs.

Returns:

  • (Array<Hash>) —

    Hashes for each pending app install



852
853
854
 
# File 'lib/jss/api_object/mobile_device.rb', line 852

def pending_managed_apps
  managed_app_history[:pending]
end

#pending_managed_ebooks ⇒ Array<Hash>

Mananged ebooks pending installation

Returns:



911
912
913
 
# File 'lib/jss/api_object/mobile_device.rb', line 911

def pending_managed_ebooks
  managed_ebook_history[:pending]
end

#pending_mdm_commands ⇒ Array<Hash>

The currently pending mdm commands.

Returns:

  • (Array<Hash>) —

    Each hash contains a command name and a :status and a a timestamp as a JSS epoch value or string. use JSS.epoch_to_time or JSS.parse_time to convert them to Time objects



790
791
792
 
# File 'lib/jss/api_object/mobile_device.rb', line 790

def pending_mdm_commands
  management_command_history[:pending]
end

#purchasing ⇒ Hash<String> Originally defined in module Purchasable

All the purchasing data in a Hash, as it comes from the API.

The reason it isn’t stored this way is to prevent editing of the hash directly.

Returns:

#purchasing_xml ⇒ REXML::Element Originally defined in module Purchasable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns A <purchasing> element to be included in the rest_xml of objects that mix-in this module.

Returns:

  • (REXML::Element) —

    A <purchasing> element to be included in the rest_xml of objects that mix-in this module.

#restart ⇒ String

Send a restart device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



731
732
733
 
# File 'lib/jss/api_object/mobile_device.rb', line 731

def restart
  self.class.send_mdm_command @id, :restart, api: @api
end

#set_ext_attr(name, value) ⇒ void Originally defined in module Extendable

This method returns an undefined value.

Set the value of an extension attribute

If the extension attribute is defined as a popup menu, the value must be one of the defined popup choices, or an empty string

If the ext. attrib. is defined with a data type of Integer, the value must be an Integer.

If the ext. attrib. is defined with a data type of Date, the value will be converted to a Time

Note that while the Jamf Pro Web interface does not allow editing the values of Extension Attributes populated by Scripts or LDAP, the API does allow it. Bear in mind however that those values will be reset again at the next recon.

Parameters:

  • name (String) —

    the name of the extension attribute to set

  • value (String, Time, Time, Integer) —

    the new value for the extension attribute for this user

#shutdown ⇒ String

Send a shutdown device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



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

def shutdown
  self.class.send_mdm_command @id, :shutdown, api: @api
end

#unmanage_device ⇒ String Also known as: unmanage, make_unmanaged

Send a unmanage_device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



609
610
611
 
# File 'lib/jss/api_object/mobile_device.rb', line 609

def unmanage_device
  @managed = false if self.class.send_mdm_command(@id, :unmanage_device, api: @api)
end

#update ⇒ Boolean Originally defined in module Updatable

Save changes to the JSS

Returns:

  • (Boolean) —

    success

Raises:

#update_inventory ⇒ String Also known as: recon

Send an update_inventory MDM command

Returns:

  • (String) —

    The command uuid

See Also:



567
568
569
 
# File 'lib/jss/api_object/mobile_device.rb', line 567

def update_inventory
  self.class.send_mdm_command @id, :update_inventory, api: @api
end

#upload(type, local_file) ⇒ String Originally defined in module Uploadable

Upload a file to the JSS via the REST Resource of the object to which this module is mixed in.

Parameters:

  • type (Symbol) —

    the type of upload happening. Must be one of the keys defined in the class’s UPLOAD_TYPES Hash.

  • local_file (String, Pathname) —

    String or Pathname pointing to the locally-readable file to be uploaded.

Returns:

  • (String) —

    The xml response from the server.

Raises:

#user_location_history ⇒ Array<Hash>

The user_location subset of the full history

Returns:

  • (Array<Hash>) —

    Each hash contains user and location data and the timestamp as a JSS epoch value or string. use JSS.epoch_to_time or JSS.parse_time to convert them to Time objects



756
757
758
 
# File 'lib/jss/api_object/mobile_device.rb', line 756

def user_location_history
  self.class.management_history @id, :user_location, api: @api
end