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

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:



499
500
501
502
503
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
 
# File 'lib/jss/api_object/mobile_device.rb', line 499

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)



328
329
330
 
# File 'lib/jss/api_object/mobile_device.rb', line 328

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



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

def applications
  @applications
end

#asset_tag ⇒ String (readonly)

Returns the asset tag.

Returns:



331
332
333
 
# File 'lib/jss/api_object/mobile_device.rb', line 331

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?



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

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



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

def battery_level
  @battery_level
end

#bluetooth_mac_address ⇒ String (readonly)

Returns the bluetooth mac addr.

Returns:

  • (String) —

    the bluetooth mac addr



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

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



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

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:



431
432
433
 
# File 'lib/jss/api_object/mobile_device.rb', line 431

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



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

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:



442
443
444
 
# File 'lib/jss/api_object/mobile_device.rb', line 442

def configuration_profiles
  @configuration_profiles
end

#department ⇒ String Originally defined in module Locatable

Returns:

#device_id ⇒ String (readonly)

Returns what is this??.

Returns:



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

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



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

def initial_entry_date
  @initial_entry_date
end

#ip_address ⇒ String (readonly)

Returns the IP addr.

Returns:



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

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



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

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



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

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



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

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



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

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:



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

def locales
  @locales
end

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

Returns is this device managed?.

Returns:

  • (Boolean) —

    is this device managed?



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

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:



451
452
453
 
# File 'lib/jss/api_object/mobile_device.rb', line 451

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



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

def model_display
  @model_display
end

#model_identifier ⇒ String (readonly)

Returns the model identifier.

Returns:

  • (String) —

    the model identifier



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

def model_identifier
  @model_identifier
end

#modem_firmware ⇒ String (readonly)

Returns the model firmware.

Returns:

  • (String) —

    the model firmware



395
396
397
 
# File 'lib/jss/api_object/mobile_device.rb', line 395

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.



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

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:



471
472
473
 
# File 'lib/jss/api_object/mobile_device.rb', line 471

def network
  @network
end

#os_build ⇒ String (readonly)

Returns the OS build.

Returns:



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

def os_build
  @os_build
end

#os_version ⇒ String (readonly)

Returns the OS version.

Returns:



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

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?



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

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



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

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:



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

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:



490
491
492
 
# File 'lib/jss/api_object/mobile_device.rb', line 490

def security
  @security
end

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

Returns the serial numbee.

Returns:

  • (String) —

    the serial numbee



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

def serial_number
  @serial_number
end

#site ⇒ String (readonly)

Returns the site associated with this device.

Returns:

  • (String) —

    the site associated with this device



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

def site
  @site
end

#supervised ⇒ Boolean (readonly)

Returns Is this device supervised?.

Returns:

  • (Boolean) —

    Is this device supervised?



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

def supervised
  @supervised
end

#tethered ⇒ String (readonly)

Returns the tether state of the device.

Returns:

  • (String) —

    the tether state of the device



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

def tethered
  @tethered
end

#udid ⇒ String (readonly)

Returns the udid.

Returns:



419
420
421
 
# File 'lib/jss/api_object/mobile_device.rb', line 419

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



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

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:



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

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:



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

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:



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

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:



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

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



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

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:



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

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:



195
196
197
 
# File 'lib/jss/api_object/mobile_device.rb', line 195

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:



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

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



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

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:



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

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:



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/jss/api_object/mobile_device.rb', line 293

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:



262
263
264
265
266
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
 
# File 'lib/jss/api_object/mobile_device.rb', line 262

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:



864
865
866
 
# File 'lib/jss/api_object/mobile_device.rb', line 864

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:



552
553
554
 
# File 'lib/jss/api_object/mobile_device.rb', line 552

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:



594
595
596
 
# File 'lib/jss/api_object/mobile_device.rb', line 594

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:



614
615
616
 
# File 'lib/jss/api_object/mobile_device.rb', line 614

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



774
775
776
 
# File 'lib/jss/api_object/mobile_device.rb', line 774

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:



574
575
576
 
# File 'lib/jss/api_object/mobile_device.rb', line 574

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:



706
707
708
 
# File 'lib/jss/api_object/mobile_device.rb', line 706

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:



674
675
676
 
# File 'lib/jss/api_object/mobile_device.rb', line 674

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:



634
635
636
 
# File 'lib/jss/api_object/mobile_device.rb', line 634

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:



694
695
696
 
# File 'lib/jss/api_object/mobile_device.rb', line 694

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:



654
655
656
 
# File 'lib/jss/api_object/mobile_device.rb', line 654

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:



664
665
666
 
# File 'lib/jss/api_object/mobile_device.rb', line 664

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:



624
625
626
 
# File 'lib/jss/api_object/mobile_device.rb', line 624

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:



684
685
686
 
# File 'lib/jss/api_object/mobile_device.rb', line 684

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:



644
645
646
 
# File 'lib/jss/api_object/mobile_device.rb', line 644

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:



584
585
586
 
# File 'lib/jss/api_object/mobile_device.rb', line 584

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.



855
856
857
 
# File 'lib/jss/api_object/mobile_device.rb', line 855

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



914
915
916
 
# File 'lib/jss/api_object/mobile_device.rb', line 914

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



796
797
798
 
# File 'lib/jss/api_object/mobile_device.rb', line 796

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:



827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
 
# File 'lib/jss/api_object/mobile_device.rb', line 827

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.



888
889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/jss/api_object/mobile_device.rb', line 888

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



806
807
808
 
# File 'lib/jss/api_object/mobile_device.rb', line 806

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



874
875
876
 
# File 'lib/jss/api_object/mobile_device.rb', line 874

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



762
763
764
 
# File 'lib/jss/api_object/mobile_device.rb', line 762

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



740
741
742
 
# File 'lib/jss/api_object/mobile_device.rb', line 740

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



847
848
849
 
# File 'lib/jss/api_object/mobile_device.rb', line 847

def pending_managed_apps
  managed_app_history[:pending]
end

#pending_managed_ebooks ⇒ Array<Hash>

Mananged ebooks pending installation

Returns:



906
907
908
 
# File 'lib/jss/api_object/mobile_device.rb', line 906

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



785
786
787
 
# File 'lib/jss/api_object/mobile_device.rb', line 785

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:



726
727
728
 
# File 'lib/jss/api_object/mobile_device.rb', line 726

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.

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

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:



716
717
718
 
# File 'lib/jss/api_object/mobile_device.rb', line 716

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:



604
605
606
 
# File 'lib/jss/api_object/mobile_device.rb', line 604

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:



562
563
564
 
# File 'lib/jss/api_object/mobile_device.rb', line 562

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



751
752
753
 
# File 'lib/jss/api_object/mobile_device.rb', line 751

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