Module: JSS::MDM

Included in:
Computer, ComputerGroup, MobileDevice, MobileDeviceGroup
Defined in:
lib/jss/api_object/mdm.rb,
lib/jss.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

COMPUTER_TARGETS =

These targets are computers

%i[computers computergroups].freeze
COMPUTER_RSRC =

The API resource for sending computer commands

'computercommands'.freeze
DEVICE_TARGETS =

These targets are mobile devices

%i[mobiledevices mobiledevicegroups].freeze
DEVICE_RSRC =

the API resource for sending device commands

'mobiledevicecommands'.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
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
SHUTDOWN_DEVICE =
'ShutDownDevice'.freeze
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
].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,

  # 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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(klass) ⇒ Object

Extend ourself when included

See Also:

  • {JSS{JSS::MDM{JSS::MDM::ClassMethods}

991
992
993
# File 'lib/jss/api_object/mdm.rb', line 991

def self.included(klass)
  klass.extend JSS::MDM::ClassMethods
end

Instance Method Details

#blank_pushvoid Also known as: send_blank_push, noop

This method returns an undefined value.

Send a blank push to this object


1008
1009
1010
# File 'lib/jss/api_object/mdm.rb', line 1008

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

#clear_passcodeObject

Send an clear_passcode command to this object


1096
1097
1098
# File 'lib/jss/api_object/mdm.rb', line 1096

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

#clear_restrictions_passwordObject

Send an clear_restrictions_password command to this object


1104
1105
1106
# File 'lib/jss/api_object/mdm.rb', line 1104

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


1074
1075
1076
# File 'lib/jss/api_object/mdm.rb', line 1074

def delete_user(user)
  self.class.delete_user @id, user, api: @api
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


1021
1022
1023
# File 'lib/jss/api_object/mdm.rb', line 1021

def device_lock(passcode_or_message = '')
  self.class.device_lock @id, passcode: passcode_or_message, message: passcode_or_message, api: @api
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


1153
1154
1155
# File 'lib/jss/api_object/mdm.rb', line 1153

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

#disable_app_analyticsObject

Send a disable_app_analytics command to this object


1224
1225
1226
# File 'lib/jss/api_object/mdm.rb', line 1224

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

#disable_data_roamingObject

Send a disable_data_roaming command to this object


1120
1121
1122
# File 'lib/jss/api_object/mdm.rb', line 1120

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

#disable_diagnostic_submissionObject

Send a disable_diagnostic_submission command to this object


1240
1241
1242
# File 'lib/jss/api_object/mdm.rb', line 1240

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

#disable_lost_modeObject

Send a disable_lost_mode command to this object


1290
1291
1292
# File 'lib/jss/api_object/mdm.rb', line 1290

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

#disable_voice_roamingObject

Send a disable_voice_roaming command to this object


1136
1137
1138
# File 'lib/jss/api_object/mdm.rb', line 1136

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

#enable_app_analyticsObject

Send an enable_app_analytics command to this object


1216
1217
1218
# File 'lib/jss/api_object/mdm.rb', line 1216

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

#enable_data_roamingObject

Send an enable_data_roaming command to this object


1112
1113
1114
# File 'lib/jss/api_object/mdm.rb', line 1112

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

#enable_diagnostic_submissionObject

Send an enable_diagnostic_submission command to this object


1232
1233
1234
# File 'lib/jss/api_object/mdm.rb', line 1232

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

#enable_lost_mode(message: nil, phone_number: nil, footnote: nil, enforce_lost_mode: true, 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)

    The message to display on the lock screen

  • phone_number (String)

    The phone number to display on the lock screen

  • footnote (String)

    Optional footnote to display on the lock screen

  • play_sound (Boolean)

    Play a sound when entering lost mode

  • enforce_lost_mode (Boolean)

    Re-enabled lost mode when re-enrolled after wipe.


1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
# File 'lib/jss/api_object/mdm.rb', line 1260

def enable_lost_mode(
      message: nil,
      phone_number: nil,
      footnote: nil,
      enforce_lost_mode: true,
      play_sound: false
)
  self.class.enable_lost_mode(
    @id,
    message: message,
    phone_number: phone_number,
    footnote: footnote,
    play_sound: play_sound,
    enforce_lost_mode: enforce_lost_mode,
    api: @api
  )
end

#enable_voice_roamingObject

Send an enable_voice_roaming command to this object


1128
1129
1130
# File 'lib/jss/api_object/mdm.rb', line 1128

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


1033
1034
1035
# File 'lib/jss/api_object/mdm.rb', line 1033

def erase_device(passcode = '', preserve_data_plan: false)
  self.class.erase_device @id, passcode: passcode, preserve_data_plan: preserve_data_plan, api: @api
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


1303
1304
1305
# File 'lib/jss/api_object/mdm.rb', line 1303

def flush_mdm_commands(status)
  self.class.flush_mdm_commands @id, status: status, api: @api
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


1188
1189
1190
# File 'lib/jss/api_object/mdm.rb', line 1188

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

#play_lost_mode_soundObject

Send a play_lost_mode_sound command to this object


1282
1283
1284
# File 'lib/jss/api_object/mdm.rb', line 1282

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

#restart_deviceObject Also known as: restart

Send a restart_device command to this object


1207
1208
1209
# File 'lib/jss/api_object/mdm.rb', line 1207

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

#shut_down_deviceObject Also known as: shutdown_device, shut_down, shutdown

Send a shut_down_device command to this object


1196
1197
1198
# File 'lib/jss/api_object/mdm.rb', line 1196

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


1064
1065
1066
# File 'lib/jss/api_object/mdm.rb', line 1064

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

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


1050
1051
1052
# File 'lib/jss/api_object/mdm.rb', line 1050

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

#update_inventoryObject Also known as: recon

Send an update_inventory command to this object


1087
1088
1089
# File 'lib/jss/api_object/mdm.rb', line 1087

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

    :lock_screen, :home_screen, or :lock_and_home_screen

  • wallpaper_content (String, Pathname)

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

  • wallpaper_id (Symbol)

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


1171
1172
1173
1174
1175
1176
1177
1178
1179
# File 'lib/jss/api_object/mdm.rb', line 1171

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,
    api: @api
  )
end