Class: JSS::MobileDevice

Inherits:
APIObject show all
Extended by:
Matchable
Includes:
Extendable, Locatable, Purchasable, Updatable, Uploadable
Defined in:
lib/jss-api/api_object/mobile_device.rb,
lib/jss-api.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"
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

[:device_name, :capacity, :tethered ]
SEARCH_CLASS =

This class lets us seach for computers

JSS::AdvancedMobileDeviceSearch
EXT_ATTRIB_CLASS =

This is the class for relevant Extension Attributes

JSS::MobileDeviceExtensionAttribute
MOBILE_DEV_MDM_COMMANDS =

The MDM commands sendable via the api and alternative versions

{
  :blank_push => "BlankPush",
  :send_blank_push => "BlankPush",
  :blank => "BlankPush",
  :noop => "BlankPush",
  :update_inventory => "UpdateInventory",
  :recon => "UpdateInventory",
  :device_lock => "DeviceLock",
  :lock => "DeviceLock",
  :lock_device => "DeviceLock",
  :erase_device => "EraseDevice",
  :erase => "EraseDevice",
  :wipe => "EraseDevice",
  :clear_passcode => "ClearPasscode",
  :unmanage_device => "UnmanageDevice",
  :unmanage => "UnmanageDevice"
}

Constants included from Matchable

JSS::Matchable::MATCHABLE, JSS::Matchable::MATCH_RSRC

Constants included from Extendable

Extendable::EXTENDABLE, Extendable::NUMERIC_TYPES

Constants included from Uploadable

Uploadable::UPLOAD_RSRC_PREFIX

Constants included from Purchasable

Purchasable::PURCHASABLE, Purchasable::SUBSET_PURCH

Constants included from Locatable

Locatable::LOCATABLE

Constants included from Updatable

Updatable::UPDATABLE

Constants inherited from APIObject

APIObject::DEFAULT_LOOKUP_KEYS, APIObject::REQUIRED_DATA_KEYS

Instance Attribute Summary collapse

Attributes included from Extendable

#ext_attrs, #extension_attributes

Attributes included from Purchasable

#applecare_id, #is_leased, #is_purchased, #lease_expires, #life_expectancy, #po_date, #po_number, #purchase_price, #purchasing_account, #purchasing_contact, #vendor, #warranty_expires

Attributes included from Locatable

#building, #department, #email_address, #phone, #position, #real_name, #room, #username

Attributes included from Updatable

#need_to_update

Attributes inherited from APIObject

#id, #in_jss, #rest_rsrc

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Matchable

match

Methods included from Extendable

#ext_attr_xml, #parse_ext_attrs, #set_ext_attr

Methods included from Uploadable

#upload

Methods included from Purchasable

#has_purchasing?, #parse_purchasing, #purchasing, #purchasing_xml

Methods included from Locatable

#has_location?, #location, #location_xml, #parse_location

Methods included from Updatable

#name=, #update

Methods inherited from APIObject

all, all_ids, all_names, #delete, get_name, map_all_ids_to, #save, xml_list

Constructor Details

#initialize(args = {}) ⇒ MobileDevice

Returns a new instance of MobileDevice.

See Also:



393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 393

def initialize(args = {})

  super args, [:udid, :serialnumber, :macaddress]

  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]
  @locales = gen[:locales]
  @managed = gen[:managed]
  @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]

  parse_location
  parse_purchasing
  parse_ext_attrs

  @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]

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)



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

def airplay_password
  @airplay_password
end

#applications ⇒ Array<Hash> (readonly)

Returns the applications on the devices.

Returns:

  • (Array<Hash>) —

    the applications on the devices



314
315
316
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 314

def applications
  @applications
end

#asset_tag ⇒ String (readonly)

Returns the asset tag.

Returns:



228
229
230
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 228

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?



231
232
233
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 231

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



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

def battery_level
  @battery_level
end

#bluetooth_mac_address ⇒ String (readonly)

Returns the bluetooth mac addr.

Returns:

  • (String) —

    the bluetooth mac addr



243
244
245
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 243

def bluetooth_mac_address
  @bluetooth_mac_address
end

#capacity_mb ⇒ Integer (readonly)

Returns total storage on the device.

Returns:

  • (Integer) —

    total storage on the device



234
235
236
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 234

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:



323
324
325
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 323

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



249
250
251
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 249

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:



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

def configuration_profiles
  @configuration_profiles
end

#device_id ⇒ String (readonly)

Returns what is this??.

Returns:



252
253
254
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 252

def device_id
  @device_id
end

#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



258
259
260
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 258

def initial_entry_date
  @initial_entry_date
end

#ip_address ⇒ String (readonly)

Returns the IP addr.

Returns:



261
262
263
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 261

def ip_address
  @ip_address
end

#languages ⇒ String (readonly)

Returns the language setting.

Returns:

  • (String) —

    the language setting



264
265
266
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 264

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



268
269
270
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 268

def last_backup_time
  @last_backup_time
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



271
272
273
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 271

def last_inventory_update
  @last_inventory_update
end

#locales ⇒ String (readonly)

Returns the locales.

Returns:



274
275
276
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 274

def locales
  @locales
end

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

Returns is this device managed?.

Returns:

  • (Boolean) —

    is this device managed?



277
278
279
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 277

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:



344
345
346
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 344

def mobile_device_groups
  @mobile_device_groups
end

#model_display ⇒ String (readonly)

Returns the display name of the model.

Returns:

  • (String) —

    the display name of the model



280
281
282
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 280

def model_display
  @model_display
end

#model_identifier ⇒ String (readonly)

Returns the model identifier.

Returns:

  • (String) —

    the model identifier



283
284
285
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 283

def model_identifier
  @model_identifier
end

#modem_firmware ⇒ String (readonly)

Returns the model firmware.

Returns:

  • (String) —

    the model firmware



286
287
288
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 286

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.



255
256
257
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 255

def name
  @name
end

#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:



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

def network
  @network
end

#os_build ⇒ String (readonly)

Returns the OS build.

Returns:



292
293
294
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 292

def os_build
  @os_build
end

#os_version ⇒ String (readonly)

Returns the OS version.

Returns:



289
290
291
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 289

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?



237
238
239
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 237

def percentage_used
  @percentage_used
end

#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



295
296
297
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 295

def phone_number
  @phone_number
end

#provisioning_profiles ⇒ Array<Hash> (readonly)

One per provisioning profile

Returns:



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

def provisioning_profiles
  @provisioning_profiles
end

#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:



383
384
385
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 383

def security
  @security
end

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

Returns the serial numbee.

Returns:

  • (String) —

    the serial numbee



298
299
300
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 298

def serial_number
  @serial_number
end

#site ⇒ String (readonly)

Returns the site associated with this device.

Returns:

  • (String) —

    the site associated with this device



302
303
304
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 302

def site
  @site
end

#supervised ⇒ Boolean (readonly)

Returns Is this device supervised?.

Returns:

  • (Boolean) —

    Is this device supervised?



305
306
307
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 305

def supervised
  @supervised
end

#tethered ⇒ String (readonly)

Returns the tether state of the device.

Returns:

  • (String) —

    the tether state of the device



308
309
310
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 308

def tethered
  @tethered
end

#udid ⇒ String (readonly)

Returns the udid.

Returns:



311
312
313
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 311

def udid
  @udid
end

#wifi_mac_address ⇒ String (readonly)

Returns the wifi mac addr.

Returns:

  • (String) —

    the wifi mac addr



246
247
248
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 246

def wifi_mac_address
  @wifi_mac_address
end

Class Method Details

.all_ipads(refresh = false) ⇒ Array<Hash>

Returns the list of all iPads.

Returns:



135
136
137
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 135

def self.all_ipads(refresh = false)
  self.all(refresh).select{|d| d[:model].start_with? "iPad" }
end

.all_iphones(refresh = false) ⇒ Array<Hash>

Returns the list of all iPhones.

Returns:



130
131
132
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 130

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



120
121
122
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 120

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

.all_phone_numbers(refresh = false) ⇒ Array<String>

Returns all mobiledevice phone numbers.

Returns:



105
106
107
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 105

def self.all_phone_numbers(refresh = false)
  self.all(refresh).map{|i| i[:phone_number]}.select{|p| not p.empty?}
end

.all_serial_numbers(refresh = false) ⇒ Array<String>

Returns all mobiledevice serial_numbers.

Returns:



100
101
102
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 100

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

.all_udids(refresh = false) ⇒ Array<String>

Returns all mobiledevice udids.

Returns:



115
116
117
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 115

def self.all_udids(refresh = false)
  self.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



125
126
127
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 125

def self.all_unmanaged(refresh = false)
  self.all(refresh).select{|d| not d[:managed] }
end

.all_wifi_mac_addresses(refresh = false) ⇒ Array<String>

Returns all mobiledevice wifi mac addrs.

Returns:



110
111
112
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 110

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

.send_mdm_command(dev, command) ⇒ Boolean

Send an MDM command to a managed mobile device.

See also #blank_push, #update_inventory, #device_lock, #erase_device, #clear_passcode, and #unmanage_device

Parameters:

  • dev (Integer, String) —

    the id, name, serialnum, udid, phone num, or wifi macaddr of the device

  • command (Symbol) —

    the command to send, one of the keys of MOBILE_DEV_MDM_COMMANDS

Returns:

  • (Boolean) —

    true if command was sent successfully

Raises:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 151

def self.send_mdm_command(dev,command)

  raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless MOBILE_DEV_MDM_COMMANDS.keys.include? command
  command_xml ="#{JSS::APIConnection::XML_HEADER}<mobile_device><command>#{MOBILE_DEV_MDM_COMMANDS[command]}</command></mobile_device>"
  the_id = nil
  self.all_managed.each do |mmd|
    if [mmd[:id], mmd[:name], mmd[:serial_number], mmd[:phone_number], mmd[:udid], mmd[:wifi_mac_address]].include? dev
      the_id = mmd[:id]
      break
    end
  end # each do mmd

  if the_id
    response = JSS::API.put_rsrc( "#{RSRC_BASE}/id/#{the_id}", command_xml)
    response =~ %r{<notification_sent>(.+)</notification_sent>}
    return ($1 and $1 == "true")
  end
  raise JSS::UnmanagedError, "Cannot send command to unknown/unmanaged device '#{dev}'"
end

Instance Method Details

#blank_push ⇒ Boolean Also known as: noop, send_blank_push

Send a blank_push MDM command

Returns:

  • (Boolean)

See Also:



450
451
452
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 450

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

#clear_passcode ⇒ Boolean

Send a clear_passcode MDM command

Returns:

  • (Boolean)

See Also:



498
499
500
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 498

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

#device_lock ⇒ Boolean Also known as: lock, lock_device

Send a device_lock MDM command

Returns:

  • (Boolean)

See Also:



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

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

#erase_device ⇒ Boolean Also known as: erase, wipe

Send an erase_device MDM command

Returns:

  • (Boolean)

See Also:



486
487
488
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 486

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

#unmanage_device ⇒ Boolean Also known as: unmanage, make_unmanaged

Send a unmanage_device MDM command

Returns:

  • (Boolean)

See Also:



509
510
511
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 509

def unmanage_device
  @managed = false if send_mdm_command(:unmanage_device)
end

#update_inventory ⇒ Boolean Also known as: recon

Send an update_inventory MDM command

Returns:

  • (Boolean)

See Also:



463
464
465
 
# File 'lib/jss-api/api_object/mobile_device.rb', line 463

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