Module: Jamf::MDM

Included in:
Computer, ComputerGroup, MobileDevice, MobileDeviceGroup
Defined in:
lib/jamf/api/classic/api_objects/mdm.rb,
lib/jamf/api/classic/api_objects/mdm_classic.rb

Overview

This module provides the ability to work with MDM commands for objects that can receive them.

Objects mixing in this module MUST:

  • Define the constant MDM_COMMAND_TARGET - One of:

    :computers, :computergroups, :mobiledevices, :mobiledevicegroups

Defined Under Namespace

Modules: ClassMethods

Constant Summary collapse

MDM_COMMAND_RSRC =

JPAPI Resources

'v2/mdm/commands'
BLANK_PUSH_RSRC = 
'v2/mdm/blank-push'
COMPUTER_INV_RSRC =

computers are unmanaged via v1/computer-inventory/id/remove-mdm-profile

'v1/computer-inventory'
UNMANAGE_COMPUTER_RSRC = 
'remove-mdm-profile'
MOBILE_DEVICE_RSRC =

Devices are unmanaged via v2/mobile-devices/id/unmanage

'v2/mobile-devices'
UNMANAGE_MOBILE_DEVICE_RSRC = 
'unmanage'
COMPUTER_TARGETS =

These targets are computers

%i[computers computergroups].freeze
DEVICE_TARGETS =

These targets are mobile devices

%i[mobiledevices mobiledevicegroups].freeze
GROUP_TARGETS =

These targets are groups, and need their member ids expanded for sending commands

%i[computergroups mobiledevicegroups].freeze
BLANK_PUSH =

Both computers & devices

'BlankPush'.freeze
DEVICE_LOCK = 
'DeviceLock'.freeze
ERASE_DEVICE = 
'EraseDevice'.freeze
UNMANGE_DEVICE = 
'UnmanageDevice'.freeze
DELETE_USER =

computers only

'DeleteUser'.freeze
UNLOCK_USER_ACCOUNT = 
'UnlockUserAccount'.freeze
ENABLE_REMOTE_DESKTOP = 
'EnableRemoteDesktop'.freeze
DISABLE_REMOTE_DESKTOP = 
'DisableRemoteDesktop'.freeze
SETTINGS =

devices

'Settings'.freeze
CLEAR_PASSCODE = 
'ClearPasscode'.freeze
UPDATE_INVENTORY = 
'UpdateInventory'.freeze
CLEAR_RESTRICTIONS_PASSWORD = 
'ClearRestrictionsPassword'.freeze
ENABLE_DATA_ROAMING = 
'SettingsEnableDataRoaming'.freeze
DISABLE_DATA_ROAMING = 
'SettingsDisableDataRoaming'.freeze
ENABLE_VOICE_ROAMING = 
'SettingsEnableVoiceRoaming'.freeze
DISABLE_VOICE_ROAMING = 
'SettingsDisableVoiceRoaming'.freeze
PASSCODE_LOCK_GRACE_PERIOD =

shared ipads only

'PasscodeLockGracePeriod'.freeze
WALLPAPER =

supervised devices

'Wallpaper'.freeze
DEVICE_NAME = 
'DeviceName'.freeze
SHUT_DOWN_DEVICE = 
'SHUT_DOWN_DEVICE'
RESTART_DEVICE = 
'RestartDevice'.freeze
ENABLE_LOST_MODE = 
'EnableLostMode'.freeze
DISABLE_LOST_MODE = 
'DisableLostMode'.freeze
DEVICE_LOCATION = 
'DeviceLocation'.freeze
PLAY_LOST_MODE_SOUND = 
'PlayLostModeSound'.freeze
ENABLE_APP_ANALYTICS = 
'SettingsEnableAppAnalytics'.freeze
DISABLE_APP_ANALYTICS = 
'SettingsDisableAppAnalytics'.freeze
ENABLE_DIAGNOSTIC_SUBMISSION = 
'SettingsEnableDiagnosticSubmission'.freeze
DISABLE_DIAGNOSTIC_SUBMISSION = 
'SettingsDisableDiagnosticSubmission'.freeze
COMPUTER_COMMANDS =

The MDM commands applicable to computers

[
  BLANK_PUSH,
  DEVICE_LOCK,
  ERASE_DEVICE,
  UNMANGE_DEVICE,
  DELETE_USER,
  UNLOCK_USER_ACCOUNT,
  ENABLE_REMOTE_DESKTOP,
  DISABLE_REMOTE_DESKTOP
].freeze
ALL_DEVICE_COMMANDS =

The MDM commands applicable to all mobile devices

[
  BLANK_PUSH,
  DEVICE_LOCK,
  ERASE_DEVICE,
  UNMANGE_DEVICE,
  SETTINGS,
  CLEAR_PASSCODE,
  UPDATE_INVENTORY,
  ENABLE_DATA_ROAMING,
  DISABLE_DATA_ROAMING,
  ENABLE_VOICE_ROAMING,
  DISABLE_VOICE_ROAMING,
  PASSCODE_LOCK_GRACE_PERIOD
].freeze
SUPERVISED_DEVICE_COMMANDS =

The MDM commands applicable to supervised mobile devices

[
  WALLPAPER,
  DEVICE_NAME,
  SHUTDOWN_DEVICE,
  RESTART_DEVICE,
  CLEAR_RESTRICTIONS_PASSWORD,
  ENABLE_LOST_MODE,
  DISABLE_LOST_MODE,
  DEVICE_LOCATION,
  PLAY_LOST_MODE_SOUND,
  ENABLE_APP_ANALYTICS,
  DISABLE_APP_ANALYTICS,
  ENABLE_DIAGNOSTIC_SUBMISSION,
  DISABLE_DIAGNOSTIC_SUBMISSION
].freeze
DEVICE_COMMANDS =

The MDM commands applicable to mobile devices

ALL_DEVICE_COMMANDS + SUPERVISED_DEVICE_COMMANDS
COMMANDS =

Symbols that can be used to represent the commands to the send_mdm_command Class method. Alternates are provided to match both the actual API command, and the command label in the JSS web UI, as well as common variants. e.g. the DeviceLock command in the API, is recognized as: :device_lock and :lock_device, and just :lock

{

  # all objects
  blank_push: BLANK_PUSH,
  send_blank_push: BLANK_PUSH,
  noop: BLANK_PUSH,

  device_lock: DEVICE_LOCK,
  lock_device: DEVICE_LOCK,
  lock: DEVICE_LOCK,

  erase_device: ERASE_DEVICE,
  wipe_device: ERASE_DEVICE,
  wipe_computer: ERASE_DEVICE,
  wipe: ERASE_DEVICE,
  erase: ERASE_DEVICE,

  unmanage_device: UNMANGE_DEVICE,
  remove_mdm_profile: UNMANGE_DEVICE,

  # computers only
  unlock_user_account: UNLOCK_USER_ACCOUNT,

  delete_user: DELETE_USER,

  enable_remote_desktop: ENABLE_REMOTE_DESKTOP,
  disable_remote_desktop: DISABLE_REMOTE_DESKTOP,

  # mobile devices only
  settings: SETTINGS, # not yet implemented as its own method

  update_inventory: UPDATE_INVENTORY,
  recon: UPDATE_INVENTORY,

  clear_passcode: CLEAR_PASSCODE,

  clear_restrictions_password: CLEAR_RESTRICTIONS_PASSWORD,

  enable_data_roaming: ENABLE_DATA_ROAMING,
  disable_data_roaming: DISABLE_DATA_ROAMING,

  enable_voice_roaming: ENABLE_VOICE_ROAMING,
  disable_voice_roaming: DISABLE_VOICE_ROAMING,

  # supervized mobile devices only
  device_name: DEVICE_NAME, # implemented as part of MobileDevice.name=

  wallpaper: WALLPAPER,
  set_wallpaper: WALLPAPER,

  passcode_lock_grace_period: PASSCODE_LOCK_GRACE_PERIOD,

  shut_down_device: SHUTDOWN_DEVICE,
  shutdown_device: SHUTDOWN_DEVICE,
  shut_down: SHUTDOWN_DEVICE,
  shutdown: SHUTDOWN_DEVICE,

  restart_device: RESTART_DEVICE,
  restart: RESTART_DEVICE,

  enable_app_analytics: ENABLE_APP_ANALYTICS,
  disable_app_analytics: DISABLE_APP_ANALYTICS,

  enable_diagnostic_submission: ENABLE_DIAGNOSTIC_SUBMISSION,
  disable_diagnostic_submission: DISABLE_DIAGNOSTIC_SUBMISSION,

  enable_lost_mode: ENABLE_LOST_MODE,
  disable_lost_mode: DISABLE_LOST_MODE,

  device_location: DEVICE_LOCATION, # not yet implemented as its own method

  play_lost_mode_sound: PLAY_LOST_MODE_SOUND
}.freeze
COMMAND_DATA =

Command Data

{
  DEVICE_LOCK => :passcode, # 6 char passcode
  ERASE_DEVICE => String, # 6 char passcode
  DELETE_USER => String, # username
  UNLOCK_USER_ACCOUNT => String # username
}.freeze
WALLPAPER_LOCATIONS = 
{
  lock_screen: 1,
  home_screen: 2,
  lock_and_home_screen: 3
}.freeze
PENDING_STATUS =

the status to flush for ‘pending’

'Pending'.freeze
FAILED_STATUS =

the status to flush for ‘failed’

'Failed'.freeze
PENDINGFAILED_STATUS =

the status to flush for both pending and failed

'Pending+Failed'.freeze
FLUSHABLE_STATUSES = 
{
  pending: PENDING_STATUS,
  failed: FAILED_STATUS,
  pending_failed: PENDINGFAILED_STATUS
}.freeze
BLANK_PUSH_RESULT = 
'Command sent'.freeze
GENERAL_ELEMENT =

xml elements

'general'.freeze
COMMAND_ELEMENT = 
'command'.freeze
TARGET_ID_ELEMENT = 
'id'.freeze
COMPUTER_COMMAND_ELEMENT = 
'computer_command'.freeze
COMPUTER_ID_ELEMENT = 
'computer_id'.freeze
COMPUTER_COMMAND_UDID_ELEMENT = 
'command_uuid'.freeze
DEVICE_COMMAND_ELEMENT = 
'mobile_device_command'.freeze
DEVICE_LIST_ELEMENT = 
'mobile_devices'.freeze
DEVICE_ID_ELEMENT = 
'id'.freeze
DEVICE_COMMAND_STATUS_ELEMENT = 
'status'.freeze
COMPUTER_RSRC =

The API resource for sending computer commands

'computercommands'.freeze
DEVICE_RSRC =

the API resource for sending device commands

'mobiledevicecommands'.freeze
SHUTDOWN_DEVICE = 
'ShutDownDevice'.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(klass) ⇒ Object

Extend ourself when included

See Also:

  • {Jamf{Jamf::MDM{Jamf::MDM::ClassMethods}


20
21
22
23
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 20

def self.included(includer)
  Jamf.load_msg "--> #{includer} is including #{self}"
  includer.extend(ClassMethods)
end

Instance Method Details

#blank_push ⇒ void Also known as: send_blank_push, noop

This method returns an undefined value.

Send a blank push to this object



1260
1261
1262
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1260

def blank_push
  self.class.send_blank_push @id, cnx: @cnx
end

#clear_passcode ⇒ Object

Send an clear_passcode command to this object



1397
1398
1399
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1397

def clear_passcode(unlock_token:)
  self.class.clear_passcode @id, unlock_token: unlock_token, cnx: @cnx
end

#clear_restrictions_password ⇒ Object

Send an clear_restrictions_password command to this object



1405
1406
1407
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1405

def clear_restrictions_password
  self.class.clear_restrictions_password @id, cnx: @cnx
end

#delete_user(user) ⇒ Object

Send a delete_user command to this computer or group

Parameters:

  • user (String) —

    the username of the acct to delete



1359
1360
1361
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1359

def delete_user(user, force: false, all: false)
  self.class.delete_user @id, user, force: force, all: all, cnx: @cnx
end

#device_lock(passcode_or_message = '') ⇒ Object Also known as: lock, lock_device

Send a dev lock to this object

Parameters:

  • passcode_or_message (String) (defaults to: '') —

    a six-char passcode, required for computers & computergroups Or an optional message to display on mobiledevices & mobiledevicegroups



1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1277

def device_lock(passcode_or_message = '', passcode: nil, message: nil, phoneNumber: nil)
  # backward compatibility: if only one arg given, decide if it's a passcode or message
  # explicit args override that
  if passcode_or_message.length == 6
    passcode ||= passcode_or_message
  elsif passcode_or_message.length > 0
    message ||= passcode_or_message
  end

  self.class.device_lock @id, passcode: passcode, message: message, phoneNumber: phoneNumber, cnx: @cnx
end

#device_name(name) ⇒ Object Also known as: set_name, set_device_name

Send a device_name command to this object

Parameters:

  • name (String) —

    The new name



1262
1263
1264
 
# File 'lib/jamf/api/classic/api_objects/mdm_classic.rb', line 1262

def device_name(name)
  self.class.device_name @id, name, cnx: @cnx
end

#disable_app_analytics ⇒ Object

Send a disable_app_analytics command to this object



1523
1524
1525
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1523

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

#disable_data_roaming ⇒ Object

Send a disable_data_roaming command to this object



1421
1422
1423
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1421

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

#disable_diagnostic_submission ⇒ Object

Send a disable_diagnostic_submission command to this object



1539
1540
1541
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1539

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

#disable_lost_mode ⇒ Object

Send a disable_lost_mode command to this object



1589
1590
1591
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1589

def disable_lost_mode
  self.class.disable_lost_mode @id, cnx: @cnx
end

#disable_remote_desktop ⇒ Object

Send a disable_remote_desktop command to this computer or group



1375
1376
1377
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1375

def disable_remote_desktop
  self.class.disable_remote_desktop @id, cnx: @cnx
end

#disable_voice_roaming ⇒ Object

Send a disable_voice_roaming command to this object



1437
1438
1439
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1437

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

#enable_app_analytics ⇒ Object

Send an enable_app_analytics command to this object



1515
1516
1517
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1515

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

#enable_data_roaming ⇒ Object

Send an enable_data_roaming command to this object



1413
1414
1415
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1413

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

#enable_diagnostic_submission ⇒ Object

Send an enable_diagnostic_submission command to this object



1531
1532
1533
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1531

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

#enable_lost_mode(message: nil, phone: nil, footnote: nil, enforce_lost_mode: false, play_sound: false) ⇒ Object

Send a enable_lost_mode command to one or more targets

Either or both of message and phone number must be provided

Parameters:

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

    The message to display on the lock screen

  • phone_number (String) —

    The phone number to display on the lock screen

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

    Optional footnote to display on the lock screen

  • play_sound (Boolean) (defaults to: false) —

    Play a sound when entering lost mode

  • enforce_lost_mode (Boolean) (defaults to: false) —

    Re-enable lost mode when re-enrolled after wipe. Default is false



1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1559

def enable_lost_mode(
  message: nil,
  phone: nil,
  footnote: nil,
  enforce_lost_mode: false,
  play_sound: false
)
  self.class.enable_lost_mode(
    @id,
    message: message,
    phone: phone,
    footnote: footnote,
    play_sound: play_sound,
    enforce_lost_mode: enforce_lost_mode,
    cnx: @cnx
  )
end

#enable_remote_desktop ⇒ Object

Send an enable_remote_desktop command to this computer or group



1367
1368
1369
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1367

def enable_remote_desktop
  self.class.enable_remote_desktop @id, cnx: @cnx
end

#enable_voice_roaming ⇒ Object

Send an enable_voice_roaming command to this object



1429
1430
1431
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1429

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

#erase_device(passcode = '', preserve_data_plan: false) ⇒ Object Also known as: wipe_device, wipe_computer, wipe, erase

Send an erase device command to this object

Parameters:

  • passcode (String) (defaults to: '') —

    a six-char passcode, required for computers & computergroups



1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1303

def erase_device(
  passcode: nil,
  preserve_data_plan: false,
  disallow_proximity_setup: false,
  obliteration_behavior: 'Default',
  return_to_service: nil
)
  self.class.erase_device(
    @id,
    passcode: passcode,
    preserve_data_plan: preserve_data_plan,
    disallow_proximity_setup: disallow_proximity_setup,
    obliteration_behavior: obliteration_behavior,
    return_to_service: return_to_service,
    cnx: @cnx
  )
end

#flush_mdm_commands(status) ⇒ void

This method returns an undefined value.

flush pending and/or failed MDM commands for this object

Parameters:

  • status (String) —

    a key from Commandable::FLUSHABLE_STATUSES



1602
1603
1604
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1602

def flush_mdm_commands(status)
  self.class.flush_mdm_commands @id, status: status, cnx: @cnx
end

#passcode_lock_grace_period(secs) ⇒ Object

Send a passcode_lock_grace_period command to this object

Parameters:

  • secs (Integer) —

    The numer of seconds for the grace period



1487
1488
1489
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1487

def passcode_lock_grace_period(secs)
  self.class.passcode_lock_grace_period @id, secs, cnx: @cnx
end

#play_lost_mode_sound ⇒ Object

Send a play_lost_mode_sound command to this object



1581
1582
1583
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1581

def play_lost_mode_sound
  self.class.play_lost_mode_sound @id, cnx: @cnx
end

#restart_device ⇒ Object Also known as: restart

Send a restart_device command to this object



1506
1507
1508
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1506

def restart_device
  self.class.restart_device @id, cnx: @cnx
end

#shut_down_device ⇒ Object Also known as: shutdown_device, shut_down, shutdown

Send a shut_down_device command to this object



1495
1496
1497
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1495

def shut_down_device
  self.class.shut_down_device @id, cnx: @cnx
end

#unlock_user_account(user) ⇒ Object

Send an unlock_user_account command to this computer or group

Parameters:

  • user (String) —

    the username of the acct to unlock



1348
1349
1350
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1348

def (user)
  self.class. @id, user, cnx: @cnx
end

#unmanage_device ⇒ Object Also known as: remove_mdm_profile

Send an unmanage device command to this object

NOTE: when used with computers, the mdm profile will probably be re-installed immediately unless the computer is also no longer managed by Jamf Pro itself. To fully unmanage a computer, use the Computer#make_unmanaged instance method.



1334
1335
1336
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1334

def unmanage_device
  self.class.unmanage_device @id, cnx: @cnx
end

#update_inventory ⇒ Object Also known as: recon

Send an update_inventory command to this object



1388
1389
1390
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1388

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

#wallpaper(wallpaper_setting: nil, wallpaper_content: nil, wallpaper_id: nil) ⇒ Object Also known as: set_wallpaper

Send a wallpaper command to this object

Parameters:

  • wallpaper_setting (Symbol) (defaults to: nil) —

    :lock_screen, :home_screen, or :lock_and_home_screen

  • wallpaper_content (String, Pathname) (defaults to: nil) —

    The local path to a .png or .jpg to use as the walpaper image, required if no wallpaper_id

  • wallpaper_id (Symbol) (defaults to: nil) —

    The id of an Icon in Jamf Pro to use as the wallpaper image, required if no wallpaper_content



1471
1472
1473
1474
1475
1476
1477
1478
 
# File 'lib/jamf/api/classic/api_objects/mdm.rb', line 1471

def wallpaper(wallpaper_setting: nil, wallpaper_content: nil, wallpaper_id: nil)
  self.class.wallpaper(
    @id,
    wallpaper_setting: wallpaper_setting,
    wallpaper_content: wallpaper_content,
    wallpaper_id: wallpaper_id, cnx: @cnx
  )
end