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:



496
497
498
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
 
# File 'lib/jss/api_object/mobile_device.rb', line 496

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)



325
326
327
 
# File 'lib/jss/api_object/mobile_device.rb', line 325

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



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

def applications
  @applications
end

#asset_tag ⇒ String (readonly)

Returns the asset tag.

Returns:



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

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?



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

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



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

def battery_level
  @battery_level
end

#bluetooth_mac_address ⇒ String (readonly)

Returns the bluetooth mac addr.

Returns:

  • (String) —

    the bluetooth mac addr



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

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



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

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:



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

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



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

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:



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

def configuration_profiles
  @configuration_profiles
end

#department ⇒ String Originally defined in module Locatable

Returns:

#device_id ⇒ String (readonly)

Returns what is this??.

Returns:



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

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



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

def initial_entry_date
  @initial_entry_date
end

#ip_address ⇒ String (readonly)

Returns the IP addr.

Returns:



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

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



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

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



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

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



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

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



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

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:



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

def locales
  @locales
end

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

Returns is this device managed?.

Returns:

  • (Boolean) —

    is this device managed?



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

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:



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

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



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

def model_display
  @model_display
end

#model_identifier ⇒ String (readonly)

Returns the model identifier.

Returns:

  • (String) —

    the model identifier



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

def model_identifier
  @model_identifier
end

#modem_firmware ⇒ String (readonly)

Returns the model firmware.

Returns:

  • (String) —

    the model firmware



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

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.



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

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:



468
469
470
 
# File 'lib/jss/api_object/mobile_device.rb', line 468

def network
  @network
end

#os_build ⇒ String (readonly)

Returns the OS build.

Returns:



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

def os_build
  @os_build
end

#os_version ⇒ String (readonly)

Returns the OS version.

Returns:



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

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?



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

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



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

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:



474
475
476
 
# File 'lib/jss/api_object/mobile_device.rb', line 474

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:



487
488
489
 
# File 'lib/jss/api_object/mobile_device.rb', line 487

def security
  @security
end

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

Returns the serial numbee.

Returns:

  • (String) —

    the serial numbee



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

def serial_number
  @serial_number
end

#site ⇒ String (readonly)

Returns the site associated with this device.

Returns:

  • (String) —

    the site associated with this device



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

def site
  @site
end

#supervised ⇒ Boolean (readonly)

Returns Is this device supervised?.

Returns:

  • (Boolean) —

    Is this device supervised?



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

def supervised
  @supervised
end

#tethered ⇒ String (readonly)

Returns the tether state of the device.

Returns:

  • (String) —

    the tether state of the device



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

def tethered
  @tethered
end

#udid ⇒ String (readonly)

Returns the udid.

Returns:



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

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



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

def wifi_mac_address
  @wifi_mac_address
end

Class Method Details

.all_apple_tvs(refresh = false) ⇒ 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)
  all(refresh).select { |d| d[:model_identifier].start_with? 'AppleTV' }
end

.all_ipads(refresh = false) ⇒ 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)
  all(refresh).select { |d| d[:model].start_with? 'iPad' }
end

.all_iphones(refresh = false) ⇒ 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)
  all(refresh).select { |d| d[:model].start_with? 'iPhone' }
end

.all_mac_addresses(refresh = false) ⇒ 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)
  all_wifi_mac_addresses(refresh)
end

.all_managed(refresh = false) ⇒ 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)
  all(refresh).select { |d| d[:managed] }
end

.all_phone_numbers(refresh = false) ⇒ 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)
  all(refresh).map { |i| i[:phone_number] }.reject(&:empty?)
end

.all_serial_numbers(refresh = false) ⇒ 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)
  all(refresh).map { |i| i[:serial_number] }
end

.all_udids(refresh = false) ⇒ 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)
  all(refresh).map { |i| i[:udid] }
end

.all_unmanaged(refresh = false) ⇒ 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)
  all(refresh).reject { |d| d[:managed] }
end

.all_wifi_mac_addresses(refresh = false) ⇒ 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)
  all(refresh).map { |i| i[:wifi_mac_address] }
end

.management_history(identifier, subset = nil) ⇒ Object

Raises:



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

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

  raise JSS::NoSuchItemError, "No MobileDevice found matching #{identifier}" unless id && all_ids.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 = JSS.api.get_rsrc(rsrc)[:mobile_device_history]
  subset ? hist[subset] : hist
end

.match(term) ⇒ 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) ⇒ 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.

Returns:

  • (String) —

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

Raises:



259
260
261
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
 
# File 'lib/jss/api_object/mobile_device.rb', line 259

def self.send_mdm_command(targets, command, data = nil)
  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.include? md.to_i
      md.to_i
    elsif all_names.include? md
      map_all_ids_to(:name).invert[md]
    else
      raise JSS::NoSuchItemError, "No mobile device found matching '#{md}'"
    end # if
  end # map!

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

  result = JSS::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:



862
863
864
 
# File 'lib/jss/api_object/mobile_device.rb', line 862

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

#blank_push ⇒ String Also known as: noop, send_blank_push

Send a blank_push MDM command

Returns:

  • (String) —

    The command uuid

See Also:



549
550
551
 
# File 'lib/jss/api_object/mobile_device.rb', line 549

def blank_push
  self.class.send_mdm_command @id, :blank_push
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:



591
592
593
 
# File 'lib/jss/api_object/mobile_device.rb', line 591

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

#clear_restrictions_password ⇒ String

Send a ClearRestrictionsPassword MDM command

Returns:

  • (String) —

    The command uuid

See Also:



611
612
613
 
# File 'lib/jss/api_object/mobile_device.rb', line 611

def clear_restrictions_password
  self.class.send_mdm_command @id, :clear_restrictions_password
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



772
773
774
 
# File 'lib/jss/api_object/mobile_device.rb', line 772

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:



571
572
573
 
# File 'lib/jss/api_object/mobile_device.rb', line 571

def device_lock(message)
  self.class.send_mdm_command @id, :device_lock, message
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:



703
704
705
 
# File 'lib/jss/api_object/mobile_device.rb', line 703

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

#disable_app_analytics ⇒ String

Send a disable_app_analytics MDM command

Returns:

  • (String) —

    The command uuid

See Also:



671
672
673
 
# File 'lib/jss/api_object/mobile_device.rb', line 671

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

#disable_data_roaming ⇒ String

Send a disable_data_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



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

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

#disable_diagnostic_submission ⇒ String

Send a disable_diagnostic_submission MDM command

Returns:

  • (String) —

    The command uuid

See Also:



691
692
693
 
# File 'lib/jss/api_object/mobile_device.rb', line 691

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

#disable_voice_roaming ⇒ String

Send a disable_voice_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



651
652
653
 
# File 'lib/jss/api_object/mobile_device.rb', line 651

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

#enable_app_analytics ⇒ String

Send a enable_app_analytics MDM command

Returns:

  • (String) —

    The command uuid

See Also:



661
662
663
 
# File 'lib/jss/api_object/mobile_device.rb', line 661

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

#enable_data_roaming ⇒ String

Send a SettingsEnableDataRoaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



621
622
623
 
# File 'lib/jss/api_object/mobile_device.rb', line 621

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

#enable_diagnostic_submission ⇒ String

Send a enable_diagnostic_submission MDM command

Returns:

  • (String) —

    The command uuid

See Also:



681
682
683
 
# File 'lib/jss/api_object/mobile_device.rb', line 681

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

#enable_voice_roaming ⇒ String

Send a enable_voice_roaming MDM command

Returns:

  • (String) —

    The command uuid

See Also:



641
642
643
 
# File 'lib/jss/api_object/mobile_device.rb', line 641

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

#erase_device ⇒ String Also known as: erase, wipe

Send an erase_device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



581
582
583
 
# File 'lib/jss/api_object/mobile_device.rb', line 581

def erase_device
  self.class.send_mdm_command @id, :erase_device
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.



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

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



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

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



794
795
796
 
# File 'lib/jss/api_object/mobile_device.rb', line 794

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:



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

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.



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

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



804
805
806
 
# File 'lib/jss/api_object/mobile_device.rb', line 804

def managed_app_history
  self.class.management_history @id, :applications
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



872
873
874
 
# File 'lib/jss/api_object/mobile_device.rb', line 872

def managed_ebook_history
  self.class.management_history @id, :ebooks
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



760
761
762
 
# File 'lib/jss/api_object/mobile_device.rb', line 760

def management_command_history
  self.class.management_history @id, :management_commands
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



738
739
740
 
# File 'lib/jss/api_object/mobile_device.rb', line 738

def management_history
  self.class.management_history @id
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



845
846
847
 
# File 'lib/jss/api_object/mobile_device.rb', line 845

def pending_managed_apps
  managed_app_history[:pending]
end

#pending_managed_ebooks ⇒ Array<Hash>

Mananged ebooks pending installation

Returns:



904
905
906
 
# File 'lib/jss/api_object/mobile_device.rb', line 904

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



783
784
785
 
# File 'lib/jss/api_object/mobile_device.rb', line 783

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:



723
724
725
 
# File 'lib/jss/api_object/mobile_device.rb', line 723

def restart
  self.class.send_mdm_command @id, :restart
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:



713
714
715
 
# File 'lib/jss/api_object/mobile_device.rb', line 713

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

#unmanage_device ⇒ String Also known as: unmanage, make_unmanaged

Send a unmanage_device MDM command

Returns:

  • (String) —

    The command uuid

See Also:



601
602
603
 
# File 'lib/jss/api_object/mobile_device.rb', line 601

def unmanage_device
  @managed = false if self.class.send_mdm_command(@id, :unmanage_device)
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:



559
560
561
 
# File 'lib/jss/api_object/mobile_device.rb', line 559

def update_inventory
  self.class.send_mdm_command @id, :update_inventory
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



749
750
751
 
# File 'lib/jss/api_object/mobile_device.rb', line 749

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