Enable and run management actions

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.

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.

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.

Prerequisites

• A deployed Azure IoT Operations instance on an Arc-connected cluster.

• The Azure CLI with the azure-iot-ops extension installed. To install or update the extension, run:

  az extension add --upgrade -n azure-iot-ops
  

Enable management actions

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 in the CLI extension repository.

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:

az iot ops mgmt-actions enable \
    --instance <instance-name> \
    --resource-group <resource-group> \
    --eg-resource-id <event-grid-namespace-resource-id>

The following table describes the optional parameters:

Verify the management actions configuration

After you enable management actions, verify that the configuration is correct and all sub-resources are in place:

az iot ops mgmt-actions show \
    --instance <instance-name> \
    --resource-group <resource-group>

The output shows the current state of the management actions infrastructure, including the Event Grid endpoint, data flows, and role assignments.

Execute a management action

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:

• Uses an asset that was created by the management actions quickstart script in the CLI extension repository.
• 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:

az iot ops mgmt-actions execute \
    --instance <instance-name> \
    --resource-group <resource-group> \
    --asset method-call-asset \
    --group managementGroup \
    --action Switch \
    --payload '{"On": true}'

Not all call actions require a payload. For example, the ONVIF GetDeviceInformation action doesn't require any input parameters, so you can execute it without a payload:

az iot ops mgmt-actions execute \
    --instance <instance-name> \
    --resource-group <resource-group> \
    --asset onvif-asset \
    --group Device \
    --action GetDeviceInformation

In this scenario, the following command returns a Could not resolve the request schema for action 'GetDeviceInformation'... error because the CLI attempts to validate the request against a non-existent schema:

az iot ops mgmt-actions execute \
    --instance <instance-name> \
    --resource-group <resource-group> \
    --asset onvif-asset \
    --group Device \
    --action GetDeviceInformation \
    --show-schema

Action types

The payload depends on the action type and the target asset's management group definition:

• Call actions invoke a method on the asset. If the method expects input parameters, the payload contains them.
• Write actions write a value to the target URI on the asset. The payload contains the value to write.
• Read actions read a value from the target URI. Use an empty payload '{}' for read actions.

For more information about how to define action types in an asset's management group, see Control OPC UA servers.

How management actions work

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.

Request flow

When you execute a management action, the following sequence occurs:

1. The az iot ops mgmt-actions execute command calls the executeAction endpoint of the asset in the Azure Device Registry namespace. The namespace then publishes the action request for the asset 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.

2. 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.

3. The processed message is published to the internal MQTT broker on the topic azure-iot-operations/asset-operations/<asset-name>/<management-group>/<action-name>.

4. 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.

Response flow

After the southbound asset executes the operation and returns a response to the connector, the following sequence occurs:

1. The connector publishes the action response to the internal MQTT broker on a topic under actions/responses/<instance-name>/.

2. The response data flow subscribes to actions/responses/<instance-name>/# on the internal broker and forwards the message to the Event Grid namespace.

3. The Azure Device Registry namespace subscribes to the response topic space in the Event Grid namespace. When the namespace receives the response message, it notifies the original executeAction caller to complete the request-response cycle.

For details on how the connector interacts with OPC UA servers and the supported action types, see Control OPC UA servers.

Disable management actions

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:

az iot ops mgmt-actions disable \
    --instance <instance-name> \
    --resource-group <resource-group>

Related content

• Control OPC UA servers
• Connect to MQTT endpoints
• Connect to ONVIF-compliant cameras
• Understand assets and devices
• Management actions quickstart scripts