Commands and Command Queue

Commands and Command Queue

CORE MDM commands are queued and cancellable. This page explains the model, the four command types, and how cancellation is guaranteed safe.

The queue

Each device has a subcollection /devices/{deviceId}/commands. A command document looks like:

{
  type:       "lock" | "reboot" | "wipe" | "lockdown",
  state:      "pending" | "executed" | "cancelled",
  createdAt:  Timestamp,
  executedAt: Timestamp,   // set when the device runs it
  issuedBy:   "admin@example.com"
}

Lifecycle

1. Dispatch — the console adds a doc with state: "pending".
2. Listen — the device's queue listener (whereEqualTo("state","pending")) sees it.
3. Claim — the device runs claimCommand, a Firestore transaction that re-reads the doc and flips pending → executed only if it's still pending.
4. Execute — if the claim wins, the device runs the action.
5. Cancel — if the admin pressed Cancel first, state is already cancelled; the transaction aborts and the device does nothing.

Because the claim is a transaction, a command executes at most once, even across reconnects or duplicate listener fires, and a cancel that lands before the claim always wins.

Command types

Type	Effect	Requires
lock	Locks the screen immediately (lockNow())	Device Admin
reboot	Reboots the device	Device Owner
wipe	Factory-resets the device (external storage not included)	Device Admin
lockdown	Applies the full-lockdown bundle (safe boot, factory reset, debugging, add-user, installs, Wi-Fi/Bluetooth/cellular config all blocked; status bar, screen capture, camera disabled) and syncs those policy values	Device Owner for the full effect

Alarm is not a queued command — it's the boolean field alarmActive on the device doc, toggled instantly. Cancellation doesn't apply.

Using it in the console

1. Open a device → Commands tab.
2. Press Lock Screen / Reboot / Apply Full Lockdown (Wipe is under Danger).
3. The command appears under Pending Commands with the type and age.
4. Press Cancel to stop it before the device picks it up. If the device already claimed it, Cancel has no effect (it already ran).

Because the emulator/device polls fast, the pending window can be short — Cancel is most useful when the device is briefly offline or slow.

Offline behavior

A command queued while the device is offline stays pending and is delivered when the device reconnects (Firestore replays the listener). To stop it, cancel it while still offline.

Full lockdown details

Apply Full Lockdown writes the whole set of policies.* lockdown values and enqueues a lockdown command. Writing the policy values too keeps the policy map consistent — otherwise the next single-policy change would re-apply stale false values and silently undo the lockdown.

Related

• Policies Reference — the persistent toggles (not commands)
• Security Rules — who can create/cancel commands and who can mark them executed
• Firestore Data Model — the command document schema