Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
Cloud
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Rule engine > Getting Started
Getting Started
Devices Library Guides API FAQ
On this page

Getting Started with Rule Engine

What is ThingsBoard Rule Engine?

Rule Engine is an easy to use framework for building event-based workflows. There are 3 main components:

  • Message - any incoming event. It can be an incoming data from devices, device life-cycle event, REST API event, RPC request, etc.
  • Rule Node - a function that is executed on an incoming message. There are many different Node types that can filter, transform or execute some action on incoming Message.
  • Rule Chain - nodes are connected with each other with relations, so the outbound message from rule node is sent to next connected rule nodes.

Typical Use Cases

ThingsBoard Rule Engine is a highly customizable framework for complex event processing. Here are some common use cases that one can configure via ThingsBoard Rule Chains:

  • Data validation and modification for incoming telemetry or attributes before saving to the database.
  • Copy telemetry or attributes from devices to related assets so you can aggregate telemetry. For example data from multiple devices can be aggregated in related Asset.
  • Create/Update/Clear alarms based on defined conditions.
  • Trigger actions based on device life-cycle events. For example, create alerts if Device is Online/Offline.
  • Load additional data required for processing. For example, load temperature threshold value for a device that is defined in Device’s Customer or Tenant attribute.
  • Trigger REST API calls to external systems.
  • Send emails when complex event occurs and use attributes of other entities inside Email Template.
  • Take into account User preferences during event processing.
  • Make RPC calls based on defined condition.
  • Integrate with external pipelines like Kafka, Spark, AWS services, etc.

Hello-World Example

Let’s assume your device is using DHT22 sensor to collect and push temperature to the ThingsBoard. DHT22 sensor can measure temperature from -40°C to +80°C.

In this tutorial we will configure ThingsBoard Rule Engine to store all temperature within -40 to 80°C range and log all other readings to the system log.

Adding temperature validation node

In Thingsboard UI go to Rule Chains section and open Root Rule Chain.

image

Drag and Drop Script Filter rule node to the chain. Node configuration window will be opened.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

TBELRecommended
JavaScript

We will use this script for data validation:

1
2

return msg.temperature == null
|| (msg.temperature >= -40 && msg.temperature <= 80);

image

We will use this script for data validation:

1
2

return typeof msg.temperature === 'undefined'
|| (msg.temperature >= -40 && msg.temperature <= 80);

image

If temperature property not defined or temperature is valid - script will return True, otherwise it will return False. If script returns True incoming message will be routed to the next nodes that are connected with True relation.

Now we want that all telemetry requests pass through this validation script. We need to remove the existing Post Telemetry relation between Message Type Switch node and Save Telemetry node:

image

And connect Message Type Switch node with Script Filter node using Post Telemetry relation:

image

image

Next, we need to connect Script Filter node with Save Telemetry node using True relation. So all valid telemetry will be saved:

image

Also, we will connect Script Filter node with Log Other node using False relation. So that all not valid telemetry will be logged in the system log:

image

Press Save button to apply changes.

Validate results

For validating results we will need to create Device and submit telemetry to the Thingsboard. So go to Devices section and create new Device:

image

For posting device telemetry we will use Rest API. To do this this we will need to copy device access token from the device DHT22.

image


Use terminal for will send a message with temperature readings = 99. Replace $ACCESS_TOKEN with actual device token.

1

curl -v -X POST -d '{"temperature":99}' https://thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

image

We will see that telemetry was not added in Device Latest Telemetry section:

image


Now send a message with temperature readings = 24.

1

curl -v -X POST -d '{"temperature":24}' https://thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

image

We will see that telemetry was saved successfully.

image

See Also

You can use the next links for learning more about Thingsboard Rule Engine:



Next steps