Module: JSS::MDM::ClassMethods

Defined in:
lib/jss/api_object/mdm.rb

Overview

See codereview.stackexchange.com/questions/23637/mixin-both-instance-and-class-methods-in-ruby for discussion of this technique for mixing in both Class and Instance methods when including a module.

Instance Method Summary collapse

Instance Method Details

#blank_push(targets, api: JSS.api) ⇒ see .send_mdm_command Also known as: send_blank_push, noop

Send a blank push to one or more targets

Parameters:

Returns:


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

def blank_push(targets, api: JSS.api)
  send_mdm_command targets, :blank_push, api: api
end

#clear_passcode(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an clear_passcode command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


682
683
684
# File 'lib/jss/api_object/mdm.rb', line 682

def clear_passcode(targets, api: JSS.api)
  send_mdm_command targets, :clear_passcode, api: api
end

#clear_restrictions_password(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an clear_restrictions_password command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


694
695
696
# File 'lib/jss/api_object/mdm.rb', line 694

def clear_restrictions_password(targets, api: JSS.api)
  send_mdm_command targets, :clear_restrictions_password, api: api
end

#delete_user(targets, user, api: JSS.api) ⇒ Hash{Integer=>String}

Send a delete_user command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


654
655
656
# File 'lib/jss/api_object/mdm.rb', line 654

def delete_user(targets, user, api: JSS.api)
  send_mdm_command targets, :delete_user, opts: { user_name: user }, api: api
end

#device_lock(targets, passcode: '', message: nil, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: lock_device, lock

Send a Device Lock to one or more targets

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

  • passcode (String)

    a six-char passcode, required for computers & computergroups

  • message (String)

    An optional message to display on mobiledevices & mobiledevicegroups

  • api (JSS::APIConnection)

    the API thru which to send the command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


567
568
569
570
571
572
573
574
575
576
577
# File 'lib/jss/api_object/mdm.rb', line 567

def device_lock(targets, passcode: '', message: nil, api: JSS.api)
  case self::MDM_COMMAND_TARGET
  when *COMPUTER_TARGETS
    raise JSS::InvalidDataError, 'Locking computers requires a 6-character String passcode' unless passcode.size == 6
    opts = { passcode: passcode }
  when *DEVICE_TARGETS
    opts = {}
    opts[:lock_message] = message if message
  end # case
  send_mdm_command targets, :device_lock, opts: opts, api: api
end

#device_name(targets, name, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: set_name, set_device_name

Send a device_name command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


759
760
761
# File 'lib/jss/api_object/mdm.rb', line 759

def device_name(targets, name, api: JSS.api)
  send_mdm_command targets, :device_name, opts: { device_name: name }, api: api
end

#disable_app_analytics(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send a disable_app_analytics command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


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

def disable_app_analytics(targets, api: JSS.api)
  send_mdm_command targets, :disable_app_analytics, api: api
end

#disable_data_roaming(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send andisable_data_roaming command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


718
719
720
# File 'lib/jss/api_object/mdm.rb', line 718

def disable_data_roaming(targets, api: JSS.api)
  send_mdm_command targets, :disable_data_roaming, api: api
end

#disable_diagnostic_submission(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send a disable_diagnostic_submission command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


886
887
888
# File 'lib/jss/api_object/mdm.rb', line 886

def disable_diagnostic_submission(targets, api: JSS.api)
  send_mdm_command targets, :disable_diagnostic_submission, api: api
end

#disable_lost_mode(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send a disable_lost_mode command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


949
950
951
# File 'lib/jss/api_object/mdm.rb', line 949

def disable_lost_mode(targets, api: JSS.api)
  send_mdm_command targets, :disable_lost_mode, api: api
end

#disable_voice_roaming(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send a disable_voice_roaming command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


742
743
744
# File 'lib/jss/api_object/mdm.rb', line 742

def disable_voice_roaming(targets, api: JSS.api)
  send_mdm_command targets, :disable_voice_roaming, api: api
end

#enable_app_analytics(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an enable_app_analytics command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


850
851
852
# File 'lib/jss/api_object/mdm.rb', line 850

def enable_app_analytics(targets, api: JSS.api)
  send_mdm_command targets, :enable_app_analytics, api: api
end

#enable_data_roaming(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an enable_data_roaming command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


706
707
708
# File 'lib/jss/api_object/mdm.rb', line 706

def enable_data_roaming(targets, api: JSS.api)
  send_mdm_command targets, :enable_data_roaming, api: api
end

#enable_diagnostic_submission(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an enable_diagnostic_submission command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


874
875
876
# File 'lib/jss/api_object/mdm.rb', line 874

def enable_diagnostic_submission(targets, api: JSS.api)
  send_mdm_command targets, :enable_diagnostic_submission, api: api
end

#enable_lost_mode(targets, message: nil, phone: nil, footnote: nil, play_sound: false, enforce_lost_mode: true, api: JSS.api) ⇒ Hash{Integer=>String}

Send a enable_lost_mode command to one or more targets

Either or both of message and phone number must be provided

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

  • message (String)

    The message to display on the lock screen

  • phone (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.

  • api (JSS::APIConnection)

    the API thru which to send the command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)

Raises:

  • (ArgumentError)

910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
# File 'lib/jss/api_object/mdm.rb', line 910

def enable_lost_mode(
      targets,
      message: nil,
      phone: nil,
      footnote: nil,
      play_sound: false,
      enforce_lost_mode: true,
      api: JSS.api
)
  raise ArgumentError, 'Either message: or phone_number: must be provided' unless message || phone
  opts = { always_enforce_lost_mode: enforce_lost_mode }
  opts[:lost_mode_message] = message if message
  opts[:lost_mode_phone] = phone if phone
  opts[:lost_mode_footnote] = footnote if footnote
  opts[:lost_mode_with_sound] = 'true' if play_sound

  send_mdm_command targets, :enable_lost_mode, opts: opts, api: api
end

#enable_voice_roaming(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send an enable_voice_roaming command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


730
731
732
# File 'lib/jss/api_object/mdm.rb', line 730

def enable_voice_roaming(targets, api: JSS.api)
  send_mdm_command targets, :enable_voice_roaming, api: api
end

#erase_device(targets, passcode: '', preserve_data_plan: false, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: wipe, wipe_device, erase, wipe_computer

Send an Erase Device command to one or more targets

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

  • passcode (String)

    a six-char passcode, required for computers & computergroups

  • preserve_data_plan (Boolean)

    Should the data plan of the mobile device be preserved?

  • api (JSS::APIConnection)

    the API thru which to send the command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


593
594
595
596
597
598
599
600
601
602
603
# File 'lib/jss/api_object/mdm.rb', line 593

def erase_device(targets, passcode: '', preserve_data_plan: false, api: JSS.api)
  case self::MDM_COMMAND_TARGET
  when *COMPUTER_TARGETS
    raise JSS::InvalidDataError, 'Erasing computers requires a 6-character String passcode' unless passcode.size == 6
    opts = { passcode: passcode }
  when *DEVICE_TARGETS
    opts = {}
    opts[:preserve_data_plan] = 'true' if preserve_data_plan
  end # case
  send_mdm_command targets, :erase_device, opts: opts, api: api
end

#flush_mdm_commands(targets, status: nil, api: JSS.api) ⇒ void

This method returns an undefined value.

Flush pending or failed commands on devices or groups

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    the name or id of the device or group to flush commands, or an array of such names or ids, or a comma-separated string of them. NOTE: when calling this on a Group class, the targets are the groups themselves, not the individual members.

  • status (String)

    a key from Commandable::FLUSHABLE_STATUSES

  • api (JSS::APIConnection)

    an API connection to use. Defaults to the corrently active API. See APIConnection

Raises:


971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
# File 'lib/jss/api_object/mdm.rb', line 971

def flush_mdm_commands(targets, status: nil, api: JSS.api)
  raise JSS::InvalidDataError, "Status must be one of :#{FLUSHABLE_STATUSES.keys.join ', :'}" unless FLUSHABLE_STATUSES.keys.include? status

  status = FLUSHABLE_STATUSES[status]

  target_ids = raw_targets_to_ids targets, api: api, expand_groups: false

  command_flush_rsrc = "commandflush/#{self::MDM_COMMAND_TARGET}/id"

  flush_rsrc = "#{command_flush_rsrc}/#{target_ids.join ','}/status/#{status}"

  puts "Sending API DELETE: #{flush_rsrc}" if JSS.devmode?

  api.delete_rsrc flush_rsrc
end

#mdm_command_xml(command, options, targets) ⇒ String

Generate the XML to send to the API, sending the MDM command to the targets

Parameters:

  • command (Symbol)

    the command to be sent, a key from COMMANDS

  • options (Hash)

    different commands require different options, see each command method

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

Returns:

  • (String)

    The XML content to send to the API

Raises:


476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
# File 'lib/jss/api_object/mdm.rb', line 476

def mdm_command_xml(command, options, targets)
  raise JSS::MissingDataError, 'Targets cannot be empty' if targets.empty?

  case self::MDM_COMMAND_TARGET
  when *COMPUTER_TARGETS
    command_elem = COMPUTER_COMMAND_ELEMENT
    target_list_elem = JSS::Computer::RSRC_LIST_KEY.to_s
    target_elem = JSS::Computer::RSRC_OBJECT_KEY.to_s
  when *DEVICE_TARGETS
    command_elem = DEVICE_COMMAND_ELEMENT
    target_list_elem = JSS::MobileDevice::RSRC_LIST_KEY.to_s
    target_elem = JSS::MobileDevice::RSRC_OBJECT_KEY.to_s
  else
    raise JSS::NoSuchItemError, "Unknonwn MDM command target: #{self::MDM_COMMAND_TARGET}"
  end # case

  xml = REXML::Document.new JSS::APIConnection::XML_HEADER
  cmd_xml = xml.add_element command_elem

  general = cmd_xml.add_element GENERAL_ELEMENT
  general.add_element(COMMAND_ELEMENT).text = command
  options.each do |opt, val|
    general.add_element(opt.to_s).text = val.to_s
  end # do opt val

  tgt_list = cmd_xml.add_element target_list_elem
  targets.each do |tgt_id|
    tgt = tgt_list.add_element(target_elem)
    tgt.add_element(TARGET_ID_ELEMENT).text = tgt_id.to_s
  end

  xml.to_s
end

#passcode_lock_grace_period(targets, secs, api: JSS.api) ⇒ Hash{Integer=>String}

Send a passcode_lock_grace_period command to one or more targets

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

  • secs (Integer)

    The numer of seconds for the grace period

  • api (JSS::APIConnection)

    the API thru which to send the command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


810
811
812
# File 'lib/jss/api_object/mdm.rb', line 810

def passcode_lock_grace_period(targets, secs, api: JSS.api)
  send_mdm_command targets, :passcode_lock_grace_period, opts: { passcode_lock_grace_period: secs }, api: api
end

#play_lost_mode_sound(targets, api: JSS.api) ⇒ Hash{Integer=>String}

Send a play_lost_mode_sound command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


937
938
939
# File 'lib/jss/api_object/mdm.rb', line 937

def play_lost_mode_sound(targets, api: JSS.api)
  send_mdm_command targets, :play_lost_mode_sound, api: api
end

#process_computer_xml_result(result) ⇒ Hash{Integer=>String}

Convert the result of senting a computer MDM command into the appropriate hash

Parameters:

  • result (String)

    The raw XML from POSTing a computer command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


383
384
385
386
387
388
389
390
391
# File 'lib/jss/api_object/mdm.rb', line 383

def process_computer_xml_result(result)
  hash = {}
  REXML::Document.new(result).elements[COMPUTER_COMMAND_ELEMENT].each_element do |cmd|
    compid = cmd.elements[COMPUTER_ID_ELEMENT].text.to_i
    udid = cmd.elements[COMPUTER_COMMAND_UDID_ELEMENT].text
    hash[compid] = udid
  end
  hash
end

#process_mobiledevice_xml_result(result) ⇒ Hash{Integer=>String}

Convert the result of senting a device MDM command into the appropriate hash

Parameters:

  • result (String)

    The raw XML from POSTing a device command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


400
401
402
403
404
405
406
407
408
409
# File 'lib/jss/api_object/mdm.rb', line 400

def process_mobiledevice_xml_result(result)
  hash = {}
  mds = REXML::Document.new(result).elements[DEVICE_COMMAND_ELEMENT].elements[DEVICE_LIST_ELEMENT]
  mds.each_element do |md|
    id = md.elements[DEVICE_ID_ELEMENT].text.to_i
    status = md.elements[DEVICE_COMMAND_STATUS_ELEMENT].text
    hash[id] = status
  end
  hash
end

#raw_targets_to_ids(targets, api: JSS.api, expand_groups: true) ⇒ Array<Integer>

Convert the targets provided for sending a command into the final list of computers or mobile devices.

Parameters:

Returns:

  • (Array<Integer>)

    The ids of the target devices for a command


437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
# File 'lib/jss/api_object/mdm.rb', line 437

def raw_targets_to_ids(targets, api: JSS.api, expand_groups: true)
  targets = targets.is_a?(Array) ? targets : [targets]

  # make sure its an array of ids
  targets.map! do |md|
    id = valid_id md, api: api
    raise JSS::NoSuchItemError, "No #{self} matches identifier: #{md}" unless id
    id
  end # map!

  # expand group members if needed
  if expand_groups && GROUP_TARGETS.include?(self::MDM_COMMAND_TARGET)
    target_ids = []
    targets.each { |group_id| target_ids += fetch(id: group_id).member_ids }
    targets = target_ids
  end

  # make sure all of them are managed, or else the API will raise a 400
  # 'Bad Request' when sending the command to an unmanaged target
  all_mgd = self.map_all_ids_to(:managed).select { |_id, mgd| mgd }.keys

  targets.each do |target_id|
    raise JSS::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id
  end

  targets
end

#restart_device(targets, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: restart

Send a restart_device command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


837
838
839
# File 'lib/jss/api_object/mdm.rb', line 837

def restart_device(targets, api: JSS.api)
  send_mdm_command targets, :restart_device, api: api
end

#send_command_rsrcString

The API rsrc for sending MDM commands to this kind of target

Returns:


415
416
417
418
419
420
421
422
423
424
# File 'lib/jss/api_object/mdm.rb', line 415

def send_command_rsrc
  case self::MDM_COMMAND_TARGET
  when *COMPUTER_TARGETS
    COMPUTER_RSRC
  when *DEVICE_TARGETS
    DEVICE_RSRC
  else
    raise JSS::InvalidDataError, "Unknown MDM command target: #{self::MDM_COMMAND_TARGET}"
  end
end

#send_mdm_command(targets, command, opts: {}, api: JSS.api) ⇒ Hash{Integer=>String}

Send an MDM command to one or more targets without instantiating them.

This general class method, and all the specific ones that all it, have matching instance methods. Use the class method when you don't have, or don't want to retrieve, instances of all the targets.

If you do have an instance or a target, call the matching instance method to send commands to that specific target.

Examples:

send a blank push to mobiledevice id 12 without instantiating:


JSS::MobileDevice.send_blank_push 12

send a blank push to mobiledevice id 12 with instantiating:


device = JSS::MobileDevice.fetch id: 12
device.send_blank_push

send a blank push to computers in computer groups

'SpecialMacs' and 'FooBarGroup'

JSS::ComputerGroup.send_blank_push ['SpecialMacs', 'FooBarGroup']

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    the name or id of the device(s), or devicegroup(s) to receive the command, or an array of such names or ids. NOTE: when calling this on a Group class, the targets are the groups themselves, not the individual members - the membership will be expanded.

  • command (Symbol)

    the command to send, one of the keys of COMMANDS

  • opts (Hash)

    Some commands require extra data, e.g. a device name. Put it here

  • api (JSS::APIConnection)

    the API connection to use. Defaults to the currently active API, see APIConnection

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
# File 'lib/jss/api_object/mdm.rb', line 347

def send_mdm_command(targets, command, opts: {}, api: JSS.api)
  command = validate_command(command)

  rsrc = "#{send_command_rsrc}/command/#{command}"

  targets = raw_targets_to_ids targets, api: api

  cmd_xml = mdm_command_xml(command, opts, targets)

  if JSS.devmode?
    puts "Sending XML:\n"
    REXML::Document.new(cmd_xml).write STDOUT, 2
    puts "\n\nTo rsrc: #{rsrc}"
  end

  result = api.post_rsrc rsrc, cmd_xml

  if command == BLANK_PUSH
    hash = {}
    targets.each { |t| hash[t] = BLANK_PUSH_RESULT }
  elsif COMPUTER_TARGETS.include? self::MDM_COMMAND_TARGET
    hash = process_computer_xml_result(result)
  elsif DEVICE_TARGETS.include? self::MDM_COMMAND_TARGET
    hash = process_mobiledevice_xml_result(result)
  end

  hash
end

#shut_down_device(targets, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: shutdown_device, shut_down, shutdown

Send a shut_down_device command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


822
823
824
# File 'lib/jss/api_object/mdm.rb', line 822

def shut_down_device(targets, api: JSS.api)
  send_mdm_command targets, :shut_down_device, api: api
end

#unlock_user_account(targets, user, api: JSS.api) ⇒ Hash{Integer=>String}

Send an unlock_user_account command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


640
641
642
# File 'lib/jss/api_object/mdm.rb', line 640

def (targets, user, api: JSS.api)
  send_mdm_command targets, :unlock_user_account, opts: { user_name: user }, api: api
end

#unmanage_device(targets, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: remove_mdm_profile

Send an Unmanage Device command to one or more targets

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.

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


622
623
624
# File 'lib/jss/api_object/mdm.rb', line 622

def unmanage_device(targets, api: JSS.api)
  send_mdm_command targets, :unmanage_device, api: api
end

#update_inventory(targets, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: recon

Send an update_inventory command to one or more targets

Parameters:

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)


669
670
671
# File 'lib/jss/api_object/mdm.rb', line 669

def update_inventory(targets, api: JSS.api)
  send_mdm_command targets, :update_inventory, api: api
end

#validate_command(command) ⇒ String

Validate that this command is known and can be sent to this kind of object, raising an error if not.

Parameters:

  • command (Symbol)

    One of the symbolic commands as keys in COMMANDS

Returns:

  • (String)

    the matching value for the command symbol given

Raises:


517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
# File 'lib/jss/api_object/mdm.rb', line 517

def validate_command(command)
  raise JSS::NoSuchItemError, "Unknown command '#{command}'" unless COMMANDS.keys.include? command

  command = COMMANDS[command]

  case self::MDM_COMMAND_TARGET
  when *COMPUTER_TARGETS
    return command if COMPUTER_COMMANDS.include? command
    raise JSS::UnsupportedError, "'#{command}' cannot be sent to computers or computer groups"
  when *DEVICE_TARGETS
    return command if DEVICE_COMMANDS.include? command
    raise JSS::UnsupportedError, "'#{command}' cannot be sent to mobile devices or mobile device groups"
  end

  raise JSS::NoSuchItemError, "'#{command}' is known, but not available for computers or mobile devices. This is a bug. Please report it."
end

#wallpaper(targets, wallpaper_setting: nil, wallpaper_content: nil, wallpaper_id: nil, api: JSS.api) ⇒ Hash{Integer=>String} Also known as: set_wallpaper

Send a wallpaper command to one or more targets

Parameters:

  • targets (String, Integer, Array<String,Integer>)

    @see .send_mdm_command

  • 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

  • api (JSS::APIConnection)

    the API thru which to send the command

Returns:

  • (Hash{Integer=>String})

    Keys are the target device ids. Values depend on the kind of target:

    • Computers will have the udid of the command sent to that computer. The udid can be used to later retrieve info about the command.

    • Mobile Devices seem to only have one command udid returned - for the last device to have the command sent to it. (even in the Database, not just in the API). So instead, the Hash value is the status of the command for that device, most often 'Command sent'

    Blank pushes do not generate return values, so Hash values are always 'Command sent' (an error will be raised if there are problems sending)

Raises:

  • (ArgumentError)

781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
# File 'lib/jss/api_object/mdm.rb', line 781

def wallpaper(targets, wallpaper_setting: nil, wallpaper_content: nil, wallpaper_id: nil, api: JSS.api)
  raise ArgumentError, "wallpaper_setting must be one of: :#{WALLPAPER_LOCATIONS.keys.join ', :'}" unless WALLPAPER_LOCATIONS.keys.include? wallpaper_setting

  opts = { wallpaper_setting: WALLPAPER_LOCATIONS[wallpaper_setting] }

  if wallpaper_content
    file = Pathname.new wallpaper_content
    raise JSS::NoSuchItemError, "Not a file: #{file}" unless file.file?
    opts[:wallpaper_content] = Base64.encode64 file.read
  elsif wallpaper_id
    opts[:wallpaper_id] = wallpaper_id
  else
    raise ArgumentError, 'Either wallpaper_id: or wallpaper_content must be provided'
  end

  send_mdm_command targets, :wallpaper, opts: opts, api: api
end