Rule Events

Actions are the matching rules that connect MQTT messages with external data systems, covering data processing and mapping. MQTT-protocol devices connect to the MQTT service to deliver messages, and actions provide the association for integrating data into external data systems, enabling seamless integration between devices and other business systems.

1. Rule Events

The rule engine can handle message publishing, and it can also handle events such as client online/offline and client subscriptions. For events, the event topic follows the FROM clause in the SQL statement.

The following describes all client events.

Connection Established Event

Event identifier: $events/client_connected

Triggered when a client successfully connects to the MQTT service.

Available fields

Field	Description
clientId	client id
proto_name	protocol type name
ip_address	client IP
node	node IP
port	client port
ts	event trigger time
keepalive	heartbeat interval
clean_start	whether to clear the session
status	whether online

SQL rule example

select
  *
from
"$events/client_connected"

Example JSON output

{
	"proto_name": "MQTT",
	"node": "127.0.0.1",
	"clientId": "S&testD664Q81G8092&41&1",
	"ip_address": "127.0.0.1",
	"port": 52865,
	"ts": 1735455370388,
	"keepalive": 60,
	"clean_start": true,
	"status": true
}

Selected fields example

select
  clientId,
  status,
  keepalive
from
"$events/client_connected"

Output data

{
	"clientId": "S&testD664Q81G8092&41&1",
	"keepalive": 60,
	"status": true
}

Connection Disconnected Event

Event identifier : $events/client_disconnected

Triggered when a client disconnects.

Available fields

Field	Description
offline_reason	Reason the client disconnected: normal: the client disconnected actively kicked: kicked out by the server keepalive_timeout: heartbeat timeout not_authorized: authentication failed tcp_closed: the peer closed the network connection discarded: another client connected with the same clientId
clientId	client id
status	device status
port	client port
ip_address	client IP
ts	event trigger time
node	node IP

SQL rule example

select
*
from
"$events/client_disconnected"

Example output

{
	"proto_name": "MQTT",
	"node": "127.0.0.1",
	"clientId": "S&testD664Q81G8092&41&1",
	"ip_address": "127.0.0.1",
	"port": 0,
	"ts": 1735456294357,
	"offline_reason": "kicked",
	"status": false
}

Message Publish Event

Event identifier: $events/message_publish

Available fields

Field	Description
proto_name	protocol name
clientId	client id
id	message id
topic	topic
peerhost	client IP
payload	MQTT message body
node	node IP
qos	message QoS
port	client port
datatype	data type, json/hex/base64/cbor
publish_received_at	time the message arrived at the MQTT service
ts	event trigger time

SQL rule example

select
*
from
"$events/message_publish"

Example output

{
  "proto_name" : "MQTT",
  "ts" : 1735486854867,
  "clientId" : "S&testD664Q81G8092&41&1",
  "id" : "1873393767773118464",
  "topic" : "/D1832O34Z6M9/property/post",
  "qos" : 0,
  "payload" : [ 123, 13, 10, 32, 32, 34, 109, 115, 103, 34, 58, 32, 34, 104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 34, 13, 10, 125 ],
  "peerhost" : "127.0.0.1",
  "clientPort" : 65385,
  "node" : "127.0.0.1",
  "publish_received_at" : 1735486854868,
  "datatype" : "json"
}

Client Subscription Succeeded Event

Event identifier: $events/session_subscribed

Triggered when a client subscribes successfully.

Available fields

Field	Description
clientId	destination Client ID of the message
proto_name	protocol name
peerhost	client IPAddress
topic	MQTT topic
qos	MQTT event subscribe
event	SUBSCRIBE Properties (5.0 only)
timestamp	event trigger time (unit: milliseconds)
node	node where the event was triggered

SQL rule example

select
*
from
"$events/session_subscribed"

Example output

{
    "node": "127.0.0.1",
    "clientId": "860061061621885",
    "peerhost": "127.0.0.1",
    "qos": 0,
    "topic": "/860061061621test/property/post",
    "proto_name": "MQTT",
    "event": "subscribe",
    "timestamp": 1736217855399
}

Client Unsubscription Succeeded Event

Event identifier: $events/session_unsubscribed

Triggered when a client unsubscribes successfully.

Available fields

Field	Description
clientId	destination Client ID of the message
proto_name	protocol name
peerhost	client IPAddress
topic	MQTT topic
ts	event trigger time (unit: milliseconds)
event	SUBSCRIBE Properties (5.0 only)
node	node where the event was triggered

SQL rule example

select
*
from
"$events/session_unsubscribed"

Example output

{
    "node": "127.0.0.1",
    "clientId": "860061061621885",
    "peerhost": "127.0.0.1",
    "topic": "/860061061621test/property/post",
    "proto_name": "MQTT",
    "event": "unSubscribe",
    "ts": 1736217858065
}

Message Acknowledged Event

Event identifier: $events/message_acked

Triggered when a message is sent to a client and the client's ack reply is received; only QoS 1 and QoS 2 trigger it.

Field	Description
id	MQTT message ID
from_clientid	source Client ID of the message
from_username	source username of the message
clientId	destination Client ID of the message
username	destination username of the message
payload	MQTT message body
peerhost	client IPAddress
topic	MQTT topic
qos	QoS of the MQTT message
node	node where the event was triggered
timestamp	event trigger time (unit: milliseconds)

SQL rule example

SELECT
  from_clientid,
  from_username,
  topic,
  qos,
  node,
  timestamp
FROM
  "$events/message_acked"

Example output

{
  "topic": "t/a",
  "timestamp": 1645002965664,
  "qos": 1,
  "node": "127.0.0.1",
  "from_username": "fastbee",
  "from_clientid": "fastbee"
}

Session Keepalive Event

Event identifier: $events/session_ping

Triggered when a device heartbeat keepalive occurs.

Available fields

Field	Description
clientId	destination Client ID of the message
proto_name	protocol name
port	client port
node	node where the event was triggered
ts	event trigger time (unit: milliseconds)
ip_address	client IP

SQL rule example

SELECT
  *
FROM
  "$events/session_ping"

Example output

{
    "proto_name": "MQTT",
    "node": "127.0.0.1",
    "clientId": "860061061621885",
    "ip_address": "127.0.0.1",
    "port": 51182,
    "ts": 1736219438405
}

Message Delivered Event

Event identifier: $events/client_delivered

Triggered when a message is placed into the underlying socket.

Available fields

Field	Description
id	MQTT message ID
from_clientid	source Client ID of the message
from_username	source username of the message
clientId	destination Client ID of the message
username	destination username of the message
payload	MQTT message body
peerhost	client IPAddress
topic	MQTT topic
qos	QoS of the MQTT message
node	node where the event was triggered
timestamp	event trigger time (unit: milliseconds)

SQL rule example

SELECT
  from_clientid,
  from_username,
  topic,
  qos,
  node,
  timestamp
FROM
  "$events/client_delivered"

Example output

{
  "topic": "t/a",
  "timestamp": 1645002965664,
  "qos": 1,
  "node": "127.0.0.1",
  "from_username": "fastbee",
  "from_clientid": "fastbee"
}