|
| 1 | +--- |
| 2 | +title: Enable and run management actions |
| 3 | +description: Enable management actions on an Azure IoT Operations instance so that you can invoke operations on southbound assets from the cloud or edge, and understand the message flow through the system. |
| 4 | +author: dominicbetts |
| 5 | +ms.author: dobett |
| 6 | +ms.service: azure-iot-operations |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 03/18/2026 |
| 9 | +ai-usage: ai-assisted |
| 10 | + |
| 11 | +#CustomerIntent: As an IT or OT operator, I want to enable management actions on my Azure IoT Operations instance so that I can invoke operations such as method calls, writes, and reads on southbound assets from the cloud or edge. |
| 12 | +--- |
| 13 | + |
| 14 | +# Enable and run management actions |
| 15 | + |
| 16 | +Management actions let you invoke operations on southbound assets connected to your Azure IoT Operations instance. You can call methods, write values, and read values on assets such as OPC UA servers, ONVIF cameras, and MQTT devices. Management actions use Azure Event Grid to route requests and responses between the cloud and the internal MQTT broker The connector subscribes to a known topic on the internal MQTT broker and then executes the operation on the target asset. |
| 17 | + |
| 18 | +When you enable management actions, the Azure CLI provisions the infrastructure that connects Event Grid to the MQTT broker. This infrastructure includes an Event Grid data flow endpoint, a request data flow that uses a WebAssembly (WASM) module to process incoming messages, a response data flow that routes replies back through Event Grid, and the required topic spaces and permission bindings. After the infrastructure is in place, you can execute actions on any asset that has a management group and action defined. |
| 19 | + |
| 20 | +This article explains how to enable management actions, execute actions on assets, and how the message flow works through the system. The management actions CLI commands are protocol-agnostic. The examples in this article use an OPC UA asset, but the same commands work for any protocol that supports management actions. |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +- A deployed [Azure IoT Operations](../deploy-iot-ops/howto-deploy-iot-operations.md) instance on an Arc-connected cluster. |
| 25 | +- The Azure CLI with the `azure-iot-ops` extension installed. To install or update the extension, run: |
| 26 | + |
| 27 | + ```azurecli |
| 28 | + az extension add --upgrade -n azure-iot-ops |
| 29 | + ``` |
| 30 | + |
| 31 | +## Enable management actions |
| 32 | + |
| 33 | +For a complete end-to-end setup script that creates the Event Grid namespace, device, asset, and enables management actions in one step, see the [management actions quickstart](https://github.com/Azure/azure-iot-ops-cli-extension/blob/mgmt_actions_quickstart/scripts/mgmt-actions/README.md) in the CLI extension repository. |
| 34 | + |
| 35 | +The `az iot ops mgmt-actions enable` command in the quickstart script provisions the management actions infrastructure on your Azure IoT Operations instance. The command creates the following resources: |
| 36 | + |
| 37 | +| Resource | Purpose | |
| 38 | +|----------|--------| |
| 39 | +| Event Grid topic space | Includes the `actions/requests/` and `actions/responses/` topics for message routing. | |
| 40 | +| Event Grid permission bindings | Grants the Azure IoT Operations instance publish and subscribe access to the topic space. | |
| 41 | +| Event Grid data flow endpoint | Connects the Azure IoT Operations data flow runtime to the Event Grid namespace. | |
| 42 | +| Request data flow graph | Routes messages from Event Grid to the MQTT broker, applying a WASM module to rewrite topic paths. | |
| 43 | +| Response data flow | Routes responses from the MQTT broker back to Event Grid. | |
| 44 | +| Role assignments | Grants the data flow identity and the Azure Device Registry namespace the required permissions. | |
| 45 | + |
| 46 | +```azurecli |
| 47 | +az iot ops mgmt-actions enable \ |
| 48 | + --instance <instance-name> \ |
| 49 | + --resource-group <resource-group> \ |
| 50 | + --eg-resource-id <event-grid-namespace-resource-id> |
| 51 | +``` |
| 52 | + |
| 53 | +The following table describes the optional parameters: |
| 54 | + |
| 55 | +| Parameter | Description | |
| 56 | +|-----------|-------------| |
| 57 | +| `--mi-user-assigned` | Full resource ID of a user-assigned managed identity to use for the Event Grid data flow endpoint. If omitted, the system-assigned managed identity is used. | |
| 58 | +| `--skip-ra` | Skip role assignment creation during enable. Use this flag if role assignments were preconfigured or you lack permissions to create them. | |
| 59 | +| `--registry-endpoint` | Name of a registry endpoint to use for downloading the WASM data flow graph artifact. Use this flag if you need a non-default container registry. | |
| 60 | + |
| 61 | +> [!TIP] |
| 62 | +> The data flow graph and response data flow may take a few seconds to reconcile after the `enable` command completes. Run `az iot ops mgmt-actions show` to confirm all sub-resources are available before you execute an action. |
| 63 | +
|
| 64 | +## Verify the management actions configuration |
| 65 | + |
| 66 | +After you enable management actions, verify that the configuration is correct and all sub-resources are in place: |
| 67 | + |
| 68 | +```azurecli |
| 69 | +az iot ops mgmt-actions show \ |
| 70 | + --instance <instance-name> \ |
| 71 | + --resource-group <resource-group> |
| 72 | +``` |
| 73 | + |
| 74 | +The output shows the current state of the management actions infrastructure, including the Event Grid endpoint, data flows, and role assignments. |
| 75 | + |
| 76 | +## Execute a management action |
| 77 | + |
| 78 | +Run an action on an asset that has a management group and action defined. You specify the asset name, management group, action name, and a JSON payload. The following example: |
| 79 | + |
| 80 | +- Uses an asset that was created by the [management actions quickstart](https://github.com/Azure/azure-iot-ops-cli-extension/blob/mgmt_actions_quickstart/scripts/mgmt-actions/README.md) script in the CLI extension repository. |
| 81 | +- Invokes the `Switch` action on the `method-call-asset` asset in the `managementGroup` management group, which calls a method on an OPC UA server to switch a boiler on: |
| 82 | + |
| 83 | +```azurecli |
| 84 | +az iot ops mgmt-actions execute \ |
| 85 | + --instance <instance-name> \ |
| 86 | + --resource-group <resource-group> \ |
| 87 | + --asset method-call-asset \ |
| 88 | + --group managementGroup \ |
| 89 | + --action Switch \ |
| 90 | + --payload '{"On": true}' |
| 91 | +``` |
| 92 | + |
| 93 | +> [!TIP] |
| 94 | +> If an asset reports a request schema in its status object for the target action, by default the CLI validates the request against the schema before sending it. Use `--show-schema` to see the schema if it exists, and `--no-validate` to disable validation. |
| 95 | +
|
| 96 | +> [!TIP] |
| 97 | +> The `--payload` parameter supports inline JSON or a local file path that contains the JSON payload. |
| 98 | +
|
| 99 | +### Action types |
| 100 | + |
| 101 | +The payload depends on the action type and the target asset's management group definition: |
| 102 | + |
| 103 | +- **Call** actions invoke a method on the asset. The payload contains the method's input parameters. To call a method that takes no parameters, set the payload to `'{}'`. |
| 104 | +- **Write** actions write a value to the target URI on the asset. The payload contains the value to write. |
| 105 | +- **Read** actions read a value from the target URI. Use an empty payload `'{}'` for read actions. |
| 106 | + |
| 107 | +For more information about how to define action types in an asset's management group, see [Control OPC UA servers](howto-control-opc-ua.md). |
| 108 | + |
| 109 | +## How management actions work |
| 110 | + |
| 111 | +Management actions use two data flows and Azure Event Grid to connect a cloud client to a connector running in the Azure IoT Operations cluster. The following sections describe the request and response message flows in detail. |
| 112 | + |
| 113 | +:::image type="content" source="media/howto-use-management-actions/architecture.svg" alt-text="Diagram that shows the architecture of management actions request and response flows through Event Grid, data flows, MQTT broker, and connector to a southbound asset." lightbox="media/howto-use-management-actions/architecture.png"::: |
| 114 | + |
| 115 | +### Request flow |
| 116 | + |
| 117 | +When you execute a management action, the following sequence occurs: |
| 118 | + |
| 119 | +1. The `az iot ops mgmt-actions execute` command publishes the action request as an MQTT message to the Event Grid namespace. The message is published to a topic in the topic space created by the quickstart script, with the asset name, management group, and action name as subtopics. |
| 120 | + |
| 121 | +1. The **request data flow** subscribes to the `actions/requests/<instance-name>/#` topic on the Event Grid namespace. When a message arrives, the data flow passes it through a WASM graph module that strips the Event Grid topic prefix and rewrites the topic to the internal MQTT broker format. |
| 122 | + |
| 123 | +1. The processed message is published to the internal MQTT broker on the topic `azure-iot-operations/asset-operations/<asset-name>/<management-group>/<action-name>`. |
| 124 | + |
| 125 | +1. The connector subscribes to the `azure-iot-operations/asset-operations/` topics on the internal MQTT broker. When it receives the request, it identifies the target asset and executes the operation (call, write, or read) on the southbound asset. |
| 126 | + |
| 127 | +### Response flow |
| 128 | + |
| 129 | +After the southbound asset executes the operation and returns a response to the connector, the following sequence occurs: |
| 130 | + |
| 131 | +1. The connector publishes the action response to the internal MQTT broker on a topic under `actions/responses/<instance-name>/`. |
| 132 | + |
| 133 | +1. The **response data flow** subscribes to `actions/responses/<instance-name>/#` on the internal broker and forwards the message to the Event Grid namespace. |
| 134 | + |
| 135 | +1. The Event Grid namespace delivers the response to the waiting client, completing the request-response cycle. |
| 136 | + |
| 137 | +For details on how the connector interacts with OPC UA servers and the supported action types, see [Control OPC UA servers](howto-control-opc-ua.md). |
| 138 | + |
| 139 | +## Disable management actions |
| 140 | + |
| 141 | +When you no longer need management actions, disable them to tear down the provisioned infrastructure. The disable command removes the data flows, Event Grid topic space, permission bindings, and data flow endpoint: |
| 142 | + |
| 143 | +```azurecli |
| 144 | +az iot ops mgmt-actions disable \ |
| 145 | + --instance <instance-name> \ |
| 146 | + --resource-group <resource-group> |
| 147 | +``` |
| 148 | + |
| 149 | +## Related content |
| 150 | + |
| 151 | +- [Control OPC UA servers](howto-control-opc-ua.md) |
| 152 | +- [Connect to MQTT endpoints](howto-use-mqtt-connector.md) |
| 153 | +- [Connect to ONVIF-compliant cameras](howto-use-onvif-connector.md) |
| 154 | +- [Understand assets and devices](concept-assets-devices.md) |
| 155 | +- [Management actions quickstart scripts](https://github.com/Azure/azure-iot-ops-cli-extension/blob/mgmt_actions_quickstart/scripts/mgmt-actions/README.md) |
0 commit comments