Executing Commands

Once a command has a definition and a binding, you can execute it on an asset. The platform routes the command through the edge gateway to the physical device, tracks progress, and reports the result.

Executing a command

To execute a command on a single asset:

1. Navigate to the asset's detail page
2. Open the Commands tab
3. Find the command you want to execute in the list
4. Click the Execute button on the command row

This opens the execution dialog, which varies based on the command's risk level.

Risk-level confirmation flow

The confirmation experience adapts to the command's risk level to prevent accidental execution of dangerous operations:

Low risk

A simple confirmation dialog with the command name and a single Execute button. Suitable for routine, easily reversible operations.

Standard risk

The dialog shows the command name, description, type badge, category badge, and risk level badge. The user reviews the details and clicks Execute.

High risk

In addition to the standard details, the dialog displays an amber warning banner: "This is a high-risk command. Please verify the parameters before executing." Confirmation cannot be disabled for high-risk commands.

Critical risk

The dialog displays a red warning banner: "This is a critical command that may have irreversible effects." The user must type the exact command name into a confirmation field before the Execute button becomes active. This prevents accidental execution of commands that could cause equipment damage or safety hazards.

Command parameters

If the command definition includes a parameters schema, the execution dialog renders input fields for each parameter. For example, a "Set Power Setpoint" command might show a field for the target power value.

Parameter values are included in the execution request and forwarded to the edge command agent, which passes them to the device.

Execution lifecycle

Every command execution goes through a series of status transitions:

pending ──► dispatched ──► executing ──► completed
                │               │
                │               └──► failed
                │
                └──► expired
                │
                └──► cancelled

When a command is dispatched, a toast notification confirms that the command has been sent. The execution record is available immediately in the command history.

Timeout behavior

Each command has a timeout (configured in the command definition, default 30 seconds). If the edge agent does not report a result within this time, the execution is marked as Expired. This prevents commands from remaining in a pending state indefinitely if the edge gateway is unreachable or the device is unresponsive.

Requirements for execution

A command can only be executed if all of the following are true:

• The command instance is enabled on the asset
• The command has a binding configured with a valid connector address
• The asset's site has an edge deployment that is online
• The connector referenced in the binding is enabled

If any of these conditions are not met, the command will fail during dispatch.