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"
}

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:



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) 



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

def airplay_password
  @airplay_password
end

#applecare_id ⇒ String Originally defined in module Purchasable

#applications ⇒ Array<Hash> (readonly) 



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

def applications
  @applications
end

#asset_tag ⇒ String (readonly) 



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

def asset_tag
  @asset_tag
end

#available_mb ⇒ Intger (readonly) 



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 



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) 



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

def bluetooth_mac_address
  @bluetooth_mac_address
end

#building ⇒ String Originally defined in module Locatable

#capacity_mb ⇒ Integer (readonly) 



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



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

def certificates
  @certificates
end

#computer ⇒ Hash (readonly) 



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



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

def configuration_profiles
  @configuration_profiles
end

#department ⇒ String Originally defined in module Locatable

#device_id ⇒ String (readonly) 



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

def device_id
  @device_id
end

#email_address ⇒ String Originally defined in module Locatable

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

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

#initial_entry_date ⇒ Time (readonly) 



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) 



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

def ip_address
  @ip_address
end

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

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

#languages ⇒ String (readonly) 



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

def languages
  @languages
end

#last_backup_time ⇒ Time (readonly) 



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) 



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

def last_inventory_update
  @last_inventory_update
end

#lease_expires ⇒ Time Originally defined in module Purchasable

#life_expectancy ⇒ Integer Originally defined in module Purchasable

#locales ⇒ String (readonly) 



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? 



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



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) 



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

def model_display
  @model_display
end

#model_identifier ⇒ String (readonly) 



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

def model_identifier
  @model_identifier
end

#modem_firmware ⇒ String (readonly) 



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

def modem_firmware
  @modem_firmware
end

#name ⇒ String (readonly) 



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

def name
  @name
end

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

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



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

def network
  @network
end

#os_build ⇒ String (readonly) 



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

def os_build
  @os_build
end

#os_version ⇒ String (readonly) 



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

def os_version
  @os_version
end

#percentage_used ⇒ Integer (readonly) 



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

def percentage_used
  @percentage_used
end

#phone ⇒ String Originally defined in module Locatable

#phone_number ⇒ String (readonly) 



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

def phone_number
  @phone_number
end

#po_date ⇒ Time Originally defined in module Purchasable

#po_number ⇒ String Originally defined in module Purchasable

#position ⇒ String Originally defined in module Locatable

#provisioning_profiles ⇒ Array<Hash> (readonly)

One per provisioning profile



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

def provisioning_profiles
  @provisioning_profiles
end

#purchase_price ⇒ Float Originally defined in module Purchasable

#purchasing_account ⇒ String Originally defined in module Purchasable

#purchasing_contact ⇒ String Originally defined in module Purchasable

#real_name ⇒ String Originally defined in module Locatable

#room ⇒ String Originally defined in module Locatable

#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



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 



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

def serial_number
  @serial_number
end

#site ⇒ String (readonly) 



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

def site
  @site
end

#supervised ⇒ Boolean (readonly) 



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

def supervised
  @supervised
end

#tethered ⇒ String (readonly) 



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

def tethered
  @tethered
end

#udid ⇒ String (readonly) 



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

def udid
  @udid
end

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

#vendor ⇒ String Originally defined in module Purchasable

#warranty_expires ⇒ Time Originally defined in module Purchasable

#wifi_mac_address ⇒ String (readonly) 



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> 



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> 



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> 



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> 



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> 



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> 



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> 



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> 



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

.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.

Raises:

.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

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

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_location ⇒ void Originally defined in module Locatable

This method returns an undefined value.

Clear all location data

#clear_passcode ⇒ Boolean

Send a clear_passcode MDM command

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

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

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

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

#has_location? ⇒ Boolean Originally defined in module Locatable

#has_purchasing? ⇒ Boolean Originally defined in module Purchasable

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

#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

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

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

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

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

#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

#unmanage_device ⇒ Boolean Also known as: unmanage, make_unmanaged

Send a unmanage_device MDM command

See Also:



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

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

Raises:

#update_inventory ⇒ Boolean Also known as: recon

Send an update_inventory MDM command

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

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

Raises: