Rule Engine
Rule engine allows you to process messages from devices with a configurable set of rules. With Rule Engine you can:
- send an email when device attribute changes.
- create an alarm when telemetry value exceeds a certain threshold.
- forward telemetry data to Kafka, RabbitMQ or external RESTful server.
- and much more using other rules and plugins.
规则引擎提供了一组帮助你处理设备消息的规则。你可以使用这些规则进行如下操作：
- 设备属性改变时发送邮件。
- 当遥测数据高于某个临界值时创建警报。
- 将数据推送到Kafka, RabbitMQ或外部RESTful服务器。
- 使用其他规则和插件。
Please Note we recommend to get familiar with basic ThingsBoard features - ( Attributes, Telemetry and RPC ) before you proceed.
我们建议使用规则引擎之前先了解ThingsBoard功能-（属性、遥测和PRC）。
Rule engine operates with two main components: Rules and Plugins. The job of Rule Engine is to sequentially apply configured rules to incoming messages. Although rules are applied sequentially, rule execution is asynchronous and is based on actors. This allows processing of messages from the device in the same order in which they are received without sacrificing performance.
规则引擎包含两个主要组件：规则和插件。规则引擎主要负责将规则顺次应用到传入的数据上。顺次应用，异步执行的规则允许在不降低性能的情况下处理同时传入的消息。
The results of processing may or may not be delivered back to device application. This depends on rule configuration. For example, you may push incoming telemetry data to internal Cassandra DB, and simultaneously send it to Kafka. You are able to configure to ignore Kafka errors or report an error back to the device. In this case, the device may either retry the operation, re-send the data to a different server or simply ignore the error.
规则配置决定是否将消息处理结果返回给设备应用。例如，你可以将输入的遥测数据添加到内部Cassandra数据库，同时也可以将数据发送给Kafka。可以设置忽略Kafka异常或者将异常报告给设备。设备收到异常消息时，可以重新操作，重新发送数据到不同的服务器，也可以选择忽略异常。
Rule vs Plugin
We will review following example to explain the difference between Rule and Plugin. Let’s assume you want to send an email to an engineer when the engine temperature is too high. In this case, Rule is responsible for analyzing telemetry data and building email (body, to, cc, etc). However, the plugin is responsible for actual communication with the email server and sending emails. So, multiple rules may use the same email plugin that is configured once.
假设当发动机温度过高时，您想要向工程师发送电子邮件。在这种情况下，规则负责分析遥测数据和构建电子邮件。但是，插件负责与电子邮件服务器的实际通信并发送电子邮件。因此，多个规则可以使用一次配置的同一个电子邮件插件。
作用域
Rules and Plugins may be operating on System and Tenant levels. System level rules and plugins are managed by System Administrator. They process messages from all devices. Tenant level rules and plugins are managed by corresponding Tenant Administrator. They process messages from devices that belong to particular tenant. Tenant level rules are able to target system level plugins. For example, you can configure plugin that sends notifications on the system level. You will need to specify your email account in the plugin configuration. However, all tenant level rules may use this plugin to send email notifications.
规则和插件可作用于系统和租户。 系统级规则和插件由系统管理员管理。他们处理所有设备的消息。 租户层级规则和插件由相应的租户管理员管理。他们从属于特定租户的设备处理消息。租户级规则能够定位系统级插件。例如，您可以配置在系统级发送通知的插件。您需要在插件配置中指定您的电子邮件帐户。但是，所有租户级别的规则都可以使用此插件发送电子邮件通知。
生命周期
ThingsBoard Rules and Plugins components have same lifecycle events: Created - component is provisioned, but is not processing any messages yet. Activated - component is able to receive and process new device messages. Suspended - component is not able to receive new device messages. Deleted - component is stopped and deleted from the database.
UlyncThings规则和插件组件具有相同的生命周期事件：
- 已创建 - 组件已配置，但尚未处理任何消息。
- 激活 - 组件能够接收和处理新的设备消息。
- 已暂停 - 组件无法接收新的设备消息。
- 已删除 - 组件已停止并从数据库中删除。
规则
ThingsBoard Rule consists of three main components: Filters, Processor and Action. Depending on implementation, each component may require certain configuration before it can be used. In order to configure Rule, you need to specify at least one filter and one action. Rule Processors are optional. Let’s review role of each component.
UlyncThings规则由三个主要组件组成：过滤器，处理器和动作。根据实现情况，每个组件可能需要一定的配置才能使用。为了配置规则，您需要至少指定一个过滤器和一个动作。规则处理器是可选的。
过滤器
Rule Filter is responsible for filtering incoming messages. You can treat it as a boolean function that has device attributes and message as parameters: boolean filter(DeviceAttributes attributes, FromDeviceMessage message) ThingsBoard provides the following Rule filters out of the box: Message Type Filter - allows to filter incoming messages by type. Device Attributes Filter - allows to filter incoming messages based on current device attributes. You can define filter using javascript. See filter documentation for more details. Device Telemetry Filter - allows to filter incoming “Post Telemetry” message based on it’s values. You can define filter using javascript. See filter documentation for more details. Method Name Filter - allows to filter incoming “RPC Request” message based on it’s method name. Single Rule may contain multiple filters. Usually, one can filter based on message type and device attributes first and then apply additional filtering based on content of the message.
规则过滤器负责过滤传入的消息。
- 消息类型过滤器 - 允许按类型过滤传入消息。
- 设备属性过滤器 - 允许根据当前设备属性过滤传入的消息。
- 设备遥测过滤器 - 允许根据其值来过滤传入的“后置遥测”消息。
- 方法名称过滤器 - 允许根据其方法名称过滤传入的“RPC请求”消息。
单一规则可能包含多个过滤器。通常可以首先基于消息类型和设备属性过滤，然后根据消息的内容应用附加过滤。
处理器
Rule Processor is responsible for processing incoming message and adding metadata to it. You can treat it as a function that has device attributes and message as parameters and returns certain metadata: MessageMetadata process(DeviceAttributes attributes, FromDeviceMessage message) ThingsBoard provides the following Rule processors out of the box: Alarm Deduplication Processor generates and persists unique alarms. Populates certain metadata tag to identify new alarms. See filter documentation for more details.
规则处理器负责处理传入的消息并向其添加元数据。 现提供： 报警重复数据消除处理器生成并保持唯一的报警。填充某些元数据标签以识别新的警报。 Actions
Plugin Action is responsible for converting incoming message and metadata to new custom message that is forwarded to certain plugin. Action may be oneway or twoway. In case of oneway action, rule is not expecting any reply from plugin. In case of twoway action, rule is expecting a reply from plugin within a certain timeout. If there is no reply within a configured timeout, Rule will report an error to the device.
For example, storing data into the internal storage is twoway action, however, pushing data into external system may be oneway (optional).
Although particular Action is a part of the corresponding Rule, you can also treat it as part of the corresponding Plugin. So, you can treat an action as the following interface between Rule and Plugin:
RuleToPluginMessage
ToDeviceMsg convert(PluginToRuleMsg
boolean isOneWay() ThingsBoard provides the following Actions out of the box: Telemetry Plugin Action - system action that push data to system Telemetry Plugin. Send Mail Action - action that allows to send emails. You can specify templates for email body and recipients. During templates evaluation, you may substitute device attributes and data from incoming messages. See action documentation for more details. Kafka Plugin Action - action that allows to push messages to kafka topics. You can specify template for message body. During templates evaluation you may substitute device attributes and data from incoming messages. See action documentation for more details. RabbitMQ Plugin Action - similar to Kafka action but pushes data to RabbitMQ. REST API Call Plugin Action - similar to Kafka action but executes a REST API call. RPC Plugin Action - forwards device RPC call to corresponding plugin.
插件
ThingsBoard Plugins allow you to configure and customize system behavior. Although plugins are able to process messages from Rules, they also provide APIs to integrate with your server-side applications. With Plugin you can:
- process messages from devices
- process REST API calls from server side applications
- communicate with server-side applications using websockets.
- communicate between instances of the same plugin in the ThingsBoard cluster using asynchronous RPC calls.
- persist and query events, telemetry data, and device attributes.
ThingBoard允许配置和定制系统行为。插件能够处理来自规则的消息，也提供了与服务器端应用程序集成的API。可以使用插件进行如下操作:
- 处理设备消息。
- 处理服务端应用REST API调用。
- 使用websockets与服务端通信。
- 使用异步RPC实现ThingsBoard集群中相同插件实例间通信。
- 保留并查询事件、遥测数据和设备属性。
As we already discussed, Rules may communicate with Plugins using Actions. Let’s review other Plugin APIs.
规则可以使用Actions与插件沟通。
REST API
Plugins are able to process REST API calls from authorized users - customers and system or tenant administrators. This may be useful for server-side integrations. For example, System RPC Plugin allows executing RPC calls to devices using REST API.
Websocket API
Plugins are able to handle websocket messages from authorized users - customers and system or tenant administrators. This may be useful for integrations with server-side applications that want to receive real-time updates. For example, System Telemetry Plugin allows subscribing to device attributes and timeseries data changes using websockets.
Clustering API
When plugin is provisioned, ThingsBoard creates an instance of the plugin actor on each ThingsBoard server in the cluster. In order to implement complex use-cases, plugin instances may require a way to communicate with each other.
For example, let’s assume that we have a three node cluster (nodes A, B and C). A device may be connected via MQTT session to node A. Customer users may open a Web UI to observe telemetry data in real time and load balancer will forward their browsers to different nodes (B and C in our case). Telemetry plugin needs to keep track of websocket subscriptions for particular device in order to push update to customer’s browser.
