You may have a message you’d like to send in anticipation of monthly schedule updates. Or you might want to wipe app data after each business day. Make use of Esper’s API and scheduled commands to make messages, app installs, and Blueprint updates more seamless in your fleet management workflow.
You can also schedule certain commands, such as app installations, from the Console.
This article is intended for those comfortable with sending API requests. Learn how to get started with APIs and about our API commands.
Requirements:
In this article:
- Scheduled Commands Terminology
- Best Practices
- Creating Scheduled Commands
- Canceling Commands
- Understanding Command States
Scheduled Commands Terminology
Scheduled commands take special parameters. This section provides an overview of those parameters and other terms.
Command Type
- Device: A command used for devices
- Group: A command used for groups
- Dynamic: A command used for a dynamic set of devices, such as a subset of devices from different groups.
Level
- Group Level: A command sent to a group of devices.
- Device Level: A command sent to a single device.
Device Type
Specify which types of devices will receive the command. (Useful when firing a command to a Group.)
- Active: Fires the command to active devices only.
- Inactive: Fires the command to inactive devices only. Note: If the device remains inactive (powered off for example, or not connected to a network) during the scheduled window, the device will not receive the command.
- All: Fires the command to all devices.
Schedule Type
Select the schedule type for the command.
- Immediate: Fires the command immediately.
- Window: Fires the command during a window. Accepts a “start” and “end” time. Also known as a non-recurring command. They execute at any time within the window until they expire.
- Recurring: Fires the command during a recurring timeframe (for example, Saturday and Sunday nights from 12 a.m. to 5 a.m.). Will retry for devices that were previously offline during the timeframe, but won’t execute on devices that already received the command. They execute within the scheduled times until successful or until they expire.
Time
Specify the time the command will be sent.
- Device Time: The command fires according to the device’s timezone.
- Console Time: Recommended for most use cases. The command fires at the time selected according to the console, providing a standardized time for devices. Console time is relative to the user's machine.
- Start Time: When the scheduled command begins. Must be a time before End Time by at least three minutes.
- End Time: When the schedule command ends. Must be a time after Start Time.
Best Practices
When scheduling commands:
- It's best to keep the schedule window as brief as possible. Be sure to consider network speeds which may be required to install applications.
- Add or provision devices into a group after the scheduled window has expired or been deleted. This will prevent unexpected behavior.
Creating Scheduled Commands
All commands (scheduled or unscheduled) use the following endpoint.
Endpoint
POST https://tenant_name-api.esper.cloud/api/v0/enterprise/enterprise_id/command/
Common Scheduled Commands
The JSON body indicates which type of command will be sent to the device. We’ve provided examples of what the JSON body looks like for our most common commands. A full list of commands can be found in API commands.
When sending a command to a device, the command type can be changed to “groups” and the following code block:
"devices": [
"device_id"
]
can instead be replaced with:
"groups": [
"group_id"
]
Separate each ID by a comma.
List of Commands
See how to create a scheduled command for some of our most popular API endpoints. The following code should be inserted into the body of the request.
Broadcast a Scheduled Message
Send a message to devices.
{
"command_type": "DEVICE",
"command": "NOTIFY_DEVICE",
"command_args": {
"title": "Notice of App Update",
"message":"We will be updating our application on 2/23 at 1:00 AM.",
"url":"https://esper.io"
},
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-9T18:41:22Z",
"end_datetime": "2023-05-9T20:44:22Z",
"time_type": "device",
"window_start_time": "18:15:22",
"window_end_time": "19:30:22",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Reboot
Schedule a reboot.
{
"command_type": "DEVICE",
"command": "REBOOT",
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-10T13:00:22Z",
"end_datetime": "2023-05-10T13:05:22Z",
"time_type": "device",
"window_start_time": "13:00:22",
"window_end_time": "13:05:22",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Install or Update an App
To install or update the app, you’ll need the app version. This app should already be on the Esper tenant. The update won’t uninstall the previous version, but will upgrade the current app to the specific version. The version ID can be found in Get All Apps.
{
"command_type": "DEVICE",
"command": "INSTALL",
"command_args": {
"app_version": "AAAAAA-1111-111A-AB113-127384AB11"
},
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-10T13:51:00Z",
"end_datetime": "2023-05-10T13:55:00Z",
"time_type": "device",
"window_start_time": "13:51:00",
"window_end_time": "13:55:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Clear App Data
Clear app data at the end of the business day or after hotel guests check out. Requires "package_name" that can be found in Get All Apps and "is_g_play" (true or false).
{
"command_type": "DEVICE",
"command": "CLEAR_APP_DATA",
"command_args": {
"package_name": "com.sample.app",
"application_name": "",
"version_code": "",
"version_name": "",
"is_g_play": true
},
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-10T14:06:00Z",
"end_datetime": "2023-05-10T14:13:00Z",
"time_type": "device",
"window_start_time": "14:08:00",
"window_end_time": "14:13:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Uninstall an App
Removes an app from a device. Requires a package_name
that can be found in Get All Apps.
{
"command_type": "DEVICE",
"command": "UNINSTALL",
"command_args": {
"package_name": "com.sample.app"
},
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-10T14:06:00Z",
"end_datetime": "2023-05-10T14:13:00Z",
"time_type": "device",
"window_start_time": "14:08:00",
"window_end_time": "14:13:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Push a Blueprint Update
Pushes an update for a Blueprint. Note: The device can only be updated with its assigned Blueprint.
{
"command_type": "DEVICE",
"command": "UPDATE_BLUEPRINT",
"schedule": "RECURRING",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-10T11:26:00Z",
"end_datetime": "2023-05-10T11:31:00Z",
"time_type": "device",
"window_start_time": "11:26:00",
"window_end_time": "11:31:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Set a Lockscreen
Lock devices after the business day, and then unlock them once they’re ready for use again.
You’ll need to provide the following information:
- State: LOCK
- Message: Displayed on the device’s locked screen. For example, “Contact admin to unlock device.”
{
"command_type": "DEVICE",
"command": "SET_DEVICE_LOCKDOWN_STATE",
"schedule": "WINDOW",
"command_args": {
"state": "LOCK",
"message": "Contact admin to unlock device."
},
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-11T12:35:00Z",
"end_datetime": "2023-05-11T12:45:00Z",
"time_type": "device",
"window_start_time": "12:35:00",
"window_end_time": "12:45:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Wipe
Wipes a device. Devices are factory reset. Learn more about removing devices.
Setting wipe_external_storage
to true will wipe the device and remove it from the Console. Devices removed in this way will take a few moments to disappear from the Console. To perform a factory reset only, remove the command_args
object.
{
"command_type": "DEVICE",
"command": "WIPE",
"command_args": {
"wipe_external_storage": true
}
"schedule": "WINDOW",
"schedule_args": {
"name": "string",
"start_datetime": "2023-05-11T14:40:00Z",
"end_datetime": "2023-05-11T14:50:00Z",
"time_type": "device",
"window_start_time": "14:40:00",
"window_end_time": "14:50:00",
"days": [
"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"
]
},
"devices": [
"device_id"
],
"device_type": "all"
}
Canceling Commands
Commands that are scheduled but not yet executed can be canceled from the Event Feed of the device or the group.
Go to the device or group's Event Feed and select Cancel from the event table. Only queued commands may be canceled.
You’ll be able to cancel a scheduled application installation or uninstallation. Learn more about Canceling Application Installations.
Understanding 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 Just like a queue (or line) at a grocery store, the first person (or command) in line will be processed first and so on. “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). |
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. |