Android custom commands

Run remote actions by using custom commands on the managed Android devices.

In addition to default device actions available in the IBM® MaaS360® Portal, you can use custom commands to run dynamic actions on managed devices. After you send a custom command, you can track the execution status of all commands in the Device History page in the IBM MaaS360 Portal. This feature requires MaaS360 for Android app version 7.40 and later.

Supported custom commands

IBM MaaS360 supports the following Android custom commands.
Action Description Command
Enable kiosk mode Starts kiosk mode on the devices.
The following requirements must be met.
  • Kiosk mode is not already activated on the target devices.
  • Silent enablement is allowed.
  • Kiosk mode is enabled in the MDM policies.
 enable-kiosk
Launch app Starts the specified app on the device.
The following requirement must be met.
  • The target app must be installed on the device.
 launch-app <package name>.
Examples,
  • launch-app com.google.android.gm
  • launch-app us.zoom.videomeetings
Start activity Starts an instance of the activity that has an intent.
Device support
  • Device Admin is supported on Android version 9 or earlier.
  • Profile Owner is supported on Android version 9 or earlier.
  • Device Owner is supported on all OS versions.
  • Work Profile on Corporate Owned (WPCO) is not supported.
The following requirement must be met.
  • For explicit intents, you can start the activities of the packages that are installed on the device only.
 start-activity <intent options>
Start broadcast Broadcast the specified intent to the device. send-broadcast <intent options>
Clear app data Clears app data. This command supports multiple app IDs. The requirements are as follows.
  • Requires MaaS360 for Android app version 7.60 and later.
  • Supported only on Android Enterprise devices on OS version 9 and later.
  • The action fails if target apps are not installed on the device.
 clear-app-data <comma-separated app IDs>
  • clear-app-data com.ibm.security.verifyapp, com.ibm.gts.banorte.epass
Download eSIM Downloads eSIM on the device. The requirements are as follows.
  • eSIM supported device
  • Android devices with version 15 and later
 <download e-sim options>
Delete eSIM Deletes eSIM on the device. The requirements are as follows.
  • eSIM supported device
  • Android devices with version 15 and later
 <delete e-sim options>
Uninstall single app

The following requirement must be met.

  • The device must be enrolled in DeviceOwner mode.
  • The app must be installed on the device.
  • The app must not be marked as a required app in the MDM policy.
  • The app must not be a system app.
The following error messages are displayed when the conditions are not satisfied.
  • If the device is not enrolled in Device Owner mode, then Silent uninstall command is only supported on Device owner devices is displayed.
  • If the package name or any other parameters are not specified when you add the command, then Action failed. Invalid command is displayed.
  • When the app is not found on the device, then Application not found on the device is displayed. During this message, the action is marked as a success.
  • If the app is a system app and cannot be uninstalled, then System installed App cannot be uninstalled is displayed.
 uninstall-single-app <packageName>

Intent options

The following table describes the supported intent options with the sample commands.
Intent options Description Example
-a Set the action on the intent
  • start-activity -a android.intent.action.VIEW lists the apps that support this action.
  • send-broadcast -a 'my_action' broadcasts the action on the Android OS. Apps can use the action if the action is registered on the app.
  • send-broadcast -a 'my_action' -n com.example.sampleapp/.MyActivity -es EXTRA "SampleData" sends the broadcast "my-action" to the activity "MyActivity" of the sample app with the string data in the form of a key-value pair (key: "EXTRA" value: "SampleData").
-c Add a category to an intent start-activity -c android.intent.category.HOME -a android.intent.action.MAIN starts the Home screen.
-d Set the data URL on the intent start-activity -a android.intent.action.VIEW -d http://www.google.com opens google.com in a browser app. The command fails if a browser app is not installed.
-t Set the MIME type on the intent start-activity -t image/* -a android.intent.action.VIEW opens the Gallery or any app that displays images. A list of apps is displayed for multiple apps.
-n Set the specific intent component start-activity -n com.example.sampleapp/.SaveFileActivity opens the sample app Save File screen. If "SaveFileActivity" is not exported, the command fails.

-es, -eb, -ei, -ed, -en, -eia, -esa, -eba, -eda

(For string data, you must use quotation marks around the string to specify the value)

Add data/extras as a key-value pair to intent -es - String

start-activity -n com.example.sampleapp/.MyActivity -es EXTRA "Life is Great" opens the specific activity "MyActivity" and sends the string data in the form of a key-value pair (key: "EXTRA" value: "Life is Great") to the activity. If "MyActivity" is not exported, the command fails.
-eb - Boolean
start-activity -n com.example.sampleapp/.MyActivity -eb Status true opens the specific activity "MyActivity" and sends the Boolean data in the form of a key-value pair (key:"Status" value: true) to the activity.
Note: If "MyActivity" is not exported, the command fails.
-ed - Double/Float

start-activity -n com.example.sampleapp/.MyActivity -ed Code 999.9878 opens the specific activity "MyActivity" and sends the double or float data in the form of a key-value pair (key:"Code" value: 999.9878) to the activity. If "MyActivity" is not exported, the command fails.
-ei - Integer

start-activity -n com.example.sampleapp/.MyActivity -ei Code 999 opens the specific activity "MyActivity" and sends the integer data in the form of a key-value pair (key:"Code" value: 999) to the activity. If "MyActivity" is not exported, the command fails.
-esa - String Array

start-activity -n com.example.sampleapp/.MyActivity -esa Months "[Jan,Feb,March]" opens the specific activity "MyActivity" and sends the string array data in the form of a key-value pair (key: "Months" value: "[Jan,Feb,Mar]") to the activity. If "MyActivity" is not exported, the command fails.
-eba - Boolean Array

start-activity -n com.example.sampleapp/.MyActivity -eba Status [true, false, false, false] opens the specific activity "MyActivity" and sends the Boolean array data in the form of a key-value pair (key:"Status" value: [true, false, false, false]) to the activity. If "MyActivity" is not exported, the command fails.
-eda - Double/Float Array

start-activity -n com.example.sampleapp/.MyActivity -eda Codes [10.33, 12.33, 14.33, 15.33] opens the specific activity "MyActivity" and sends the double or float array data in the form of a key-value pair (key:"Codes" value: [10.33, 12.33, 14.33, 15.33]) to the activity. If "MyActivity" is not exported, the command fails.
-eia - Integer Array

start-activity -n com.example.sampleapp/.MyActivity -eia Codes [998, 999, 1000] opens the specific activity "MyActivity" and sends the integer array data in the form of a key-value pair (key:"Codes" value: [998, 999, 1000]) to the activity. If "MyActivity" is not exported, the command fails.
-en - Null

start-activity -n com.example.sampleapp/.MyActivity -en DataValue null opens the specific activity "MyActivity" and sends the null data in the form of a key-value pair (key: "DataValue" value: null) to the activity. If "MyActivity" is not exported, the command fails. If you want to pass null, use the -en option. If you use other options to pass null, the command fails.

Download-eSIM options

The following table describes the supported download-eSIM options with the sample commands.
Download options Description Required or Optional Example
-ac Set the eSIM activation code Required download-esim -ac LPA:1smdprd.jio.comBDB39E0CE8D69C33511E699FA8C47FCC
-sd Select whether to switch to the eSIM automatically after download. The values are true or false (default).
Note:
  • This option requires Device Owner mode.
  • The value is set to false by default for Profile Owner mode.
 Optional download-esim -sd true -ac LPA:1smdprd.jio.comBDB39E0CE8D69C33511E699FA8C47FCC
-sn Select whether to notify the user after download. The values are true (default) or false. Optional download-esim -sn false -ac LPA:1smdprd.jio.comBDB39E0CE8D69C33511E699FA8C47FCC

Delete-eSIM options

The following table describes the supported delete-eSIM options with the sample commands.
Delete options Description Required or Optional Example
-ic Set the ICCID number of the eSIM. Required delete-esim -ic 8988303000000614227
-sn Select whether to notify the user after download. The values are true (default) or false. Optional delete-esim -sn false -ic 8988303000000614227

Custom command requirements

  • The angle brackets < and > are not supported.
  • You cannot use the word script, and the signs &lt and &gt more than one time.
  • The maximum character limit is 2500.

Pushing custom commands to devices

You can issue custom commands to an individual device or a group of devices.

Important: You can send the eSIM custom commands from the IBM MaaS360 Portal to an individual device only for Android. You cannot send the commands to a group of devices because the parameters are specific to a single device.
To send custom commands to an individual device, do the following.
  1. Go to Device > Summary and then select a device.
  2. On the Device Summary page, click More and select Android Custom Command.
  3. Enter the custom command and click Run.
To send custom commands to a group of devices, do the following.
  1. Go to Devices > Groups.
  2. Hover over the More option for the device group and select Manage Android Devices.
  3. On the Manage Android Devices window, select Android Custom Command from Action.
  4. Enter the custom command and click Run.

Tracking the execution status of commands

You can view the execution status of all the commands that were issued to the selected device in the Device History page. When the custom command is run, the following statuses are returned.
  • Completed, if the action is successfully implemented on the device.
  • Error, if the action failed to run. The error details are displayed in the Error Description column.