Actions

Actions are operations that the Hiclaro automation engine can invoke on your plugin — things like toggling a device, playing a sound, or triggering a reset.

What is an action?

An action is a named operation declared in your plugin manifest that the automation engine can call when a user-defined rule fires. Once declared, your action appears in the automation builder as a selectable step. When the engine triggers it, Hiclaro publishes an MQTT message to your plugin and your service handles it.

Actions can optionally carry a value (e.g. a target state or a ringtone name) and can optionally be scoped to a specific device. A perDevice action lets the user pick which asset to target in the automation builder — Hiclaro then includes the device's port address in the payload so your service knows which hardware to act on.

Declaring actions in the manifest

Add an actions array to your plugin.json. Each entry becomes available as an automation step immediately after the plugin is installed.

"actions": [
  {
    "key": "set_plug_state",
    "label": "Set Plug State",
    "hasValue": true,
    "valueType": "string",
    "perDevice": true,
    "acceptedValues": [
      { "value": "on",  "label": "On"  },
      { "value": "off", "label": "Off" }
    ]
  },
  { "key": "restart_device", "label": "Restart Device", "hasValue": false, "perDevice": false }
]

The optional acceptedValues field declares a fixed set of allowed values for the action. When present, the automation builder renders a Select instead of a free-text input, preventing invalid values from being submitted. Each item can be a plain string or an object with value and label keys to display a friendlier label to the user while sending the raw value to your service. Omit the field entirely when the value is free-form (e.g. a target temperature).

See the Plugin Manifest reference for the full field list for each action entry (key, label, hasValue, valueType, perDevice, acceptedValues).

Receiving actions over MQTT

When the automation engine triggers an action it publishes to:

eims/actions/<plugin_key>/<action_key>

Subscribe to these topics in your service's on_connect handler using qos=1 so messages survive a brief reconnect.

def on_connect(client, userdata, flags, rc):
    client.subscribe("eims/actions/my-plugin/set_plug_state", qos=1)
    client.subscribe("eims/actions/my-plugin/restart_device",  qos=1)

The action payload is double-encoded. The raw MQTT message is a JSON object with a data field whose value is itself a JSON-encoded string — so you must parse twice. This is an artifact of how the Hiclaro API publishes through the NestJS MQTT microservice transport, which serialises the inner payload as a string before wrapping it.

After the two-step parse, the inner object contains:

value — the string value supplied by the automation, present when hasValue: true.

address — the port address (MAC or IP) of the targeted asset, present when perDevice: true and the user selected a device.

def on_message(client, userdata, msg):
    if msg.topic == "eims/actions/my-plugin/set_plug_state":
        outer = json.loads(msg.payload)
        inner = json.loads(outer["data"])
        state   = inner.get("value")    # e.g. "on" or "off"
        address = inner.get("address")  # device MAC/IP, present when perDevice: true
        set_plug_state(state, address)

    elif msg.topic == "eims/actions/my-plugin/restart_device":
        outer = json.loads(msg.payload)
        inner = json.loads(outer["data"])
        restart_device()