Commands play a fundamental role in device management. Learn about the different commands and how they are used in the console.
In this article:
- What is a command?
- Types of Commands
- Device Commands
- Understanding Dispatch Commands
- Cancelling Commands
What is a command?
A command is any action you perform on a device. Whether that’s locking a screen when you detect suspicious behavior, or updating an app across a group of devices–all of these are examples of commands.
In the Esper console specifically, a command can be:
- Any time a device converges to a blueprint
- Any action you send to a single device on the Devices & Groups page
- Any action you perform on a group of devices
Non-console actions can also be commands:
- Any action that targets a device and is sent through the API
Types of Commands
Device commands
Any action performed on a device through the Esper console or API is a device command.
Dispatch commands
A special subset of device commands. Dispatch commands were designed to perform actions on a large number of devices.
Device Commands
Understanding Device Command States
Once a command is sent, it follows a series of steps to reach the device. User behavior (for instance, canceling a command) as well as exterior factors (slow network connections, etc.) can influence if or when the command is fired to the device.
| State | Explanation |
| Queued |
Every command enters the queue before it is initiated. The queue follows the “First In, First Out” principle. |
| Scheduled | For scheduled commands, the command will check if a schedule is set and fire during the scheduled window. |
| Canceled | Any queued command may be canceled before it fires. |
| Initiated | The command has fired. |
| Acknowledged | The command has reached the device. The device still needs to process the command. |
| In Progress | The device is currently processing the command. |
| Time Out | The Esper Cloud will wait for a response from the device. The amount of time it waits depends on the timeout value of the command (2 minutes - 3 days depending on the command). Timed out commands may succeed or fail eventually. |
| Failure | The command reached the device but failed to execute. |
| Success | The command executed successfully. |
Command Scenarios and Behavior
Another way of thinking about Command States is to understand scenarios and behaviors. These scenarios apply to sets of devices, groups, or a single device.
| Scenario | Behavior |
| What if Esper is never able to communicate with the device for the entirety of the command schedule? | The device will not receive the command. |
| What if a device is added to a group that is currently receiving a scheduled command? | The newly added device will receive the command. |
| What if a device is removed from the group that is set to receive a schedule and then is added back in? | The device will receive the command. |
| What if a command is scheduled but then canceled and later, during what would have been the scheduled window, a new device is added to the group? | The device will not receive the command. |
| What if a device is removed from a group before the scheduled start time? | The device will not receive the command. |
| What if a device is added after the scheduled end time? | The device will not receive the command. |
Checking a device command’s status
You can check on the state of each device command from the Event Feed.
Individual Device Event Feed
Accessed from the individual device overview page, this event feed shows each command sent to the device.
Group Event Feed
Accessed from the individual device overview page, this event feed shows each command sent to the group.
Devices & Groups Event Feed
Accessed from the Devices & Groups page, the Devices & Groups event feed shows the commands sent to devices in the console.
A more detailed explanation of the Event Feed can be found in the Event Feed article.
Understanding Dispatch Commands
Dispatch commands are designed for large fleet actions. Currently, dispatch commands are available for:
- Converge
- Group-level app installations and uninstallations (immediate only)
Overall Dispatch Command States
| State | Description |
| Created | The initial state of the operation. |
| Query Initiated | The operation has been picked up by the system and the applicable devices are being identified. |
| Query Resolved | The applicable devices have been identified and the system is waiting to dispatch the command. |
| Dispatching | The command is being dispatched to the applicable devices. |
| Dispatched | All commands have been fired. |
| Processing | The system receives the status of each command. |
| Success | The commands have successfully executed on all applicable devices. |
| Failure | If a single device fails to execute the command, the operation is marked as a failure in the system. |
Commands can stay indefinitely in the dispatched or processing states if there are no devices to pick up the command. This is usually because of network issues.
Device Command States
Once the dispatch command reaches the device, it is tracked based on the device’s status.
| State | Description |
| Queued | The device is waiting to process the command. |
| In Progress | The device is processing the command. |
| Success | The command was executed on the device. |
| Failed | The command failed to execute on the device. |
| Cancelled | The command was cancelled (usually by the user) before it was able to execute. |
Checking a dispatch command’s status
Find dispatch command status in the Activity Feed.
Cancelling Commands
Use the Activity Feed to cancel multiple bulk actions at once. Certain device commands and group commands can be cancelled in this way.
Only commands with the queued status may be cancelled in this way. Actions may move from the queued status before the cancel action can reach it. The cancel command is not always guaranteed.
Requirements
- Esper Agent 11+ (Android devices only)
- The command must be supported by the device’s OS platform
Supported Commands
The following bulk commands can be cancelled from the Activity Feed:
| Command | Supported platforms |
|---|---|
| INSTALL | Android, iOS/iPadOS/tvOS |
| UNINSTALL | Android, iOS/iPadOS/tvOS |
| CONVERGE | All platforms |
| CLEAR_APP_CACHE | Android (supervised devices) |
| SET_GEOFENCE | Android |
Unsupported Commands
| Command | Reason |
|---|---|
| UPDATE_HEARTBEAT (PING) | Not supported |
| UPDATE_DPC | This command is no longer in use |
| GPlay INSTALL | Google manages when an application is installed |
While in the Activity Feed, press Cancel next to the command.
A modal will appear showing the current status of the actions.
Press Cancel next to the device to cancel one device’s command, or use Cancel All to cancel all commands. The status may not immediately refresh, especially for a large amount of devices.
Use Cancel to cancel commands that appear stuck in the queued state for a long period of time.