Rule Node Development Guide

• Overview
• Prerequisites
• Customization
  • Methods flow
    • Method init()
    • Method onMsg()
    • Method destroy()
  • Build
  • Import executable jar-file to your ThingsBoard instance
    • Thingsboard using IDE:
    • Thingsboard as a service:
  • UI configuration
    • Running Rule Node UI container in hot redeploy mode
• Next steps

Overview

In this tutorial, you will learn how to create your custom nodes, namely:

• Filter node that will check whether the key from telemetry data of the inbound message exists. If the selected key exists - send Message via True chain, otherwise False chain is used.

• Enrichment node that will calculate Sum of the telemetry data, separately for each device, when fields begin with the specified Input Key and add the result into Message Metadata with Output Key.

• Transformation node that will calculate Sum of the telemetry data, separately for each device, when fields begin with the specified Input Key and add Sum to the new Message payload with Output Key.

Prerequisites

We assume you have completed the following guides and reviewed the articles listed below:

• Getting Started guide.
• Rule Engine Overview article.
• Rule Engine Architecture article.

Customization

In order to create new rule node, you should implement the TbNode interface:

package org.thingsboard.rule.engine.api;

...

public interface TbNode {

    void init(TbContext ctx, TbNodeConfiguration configuration) throws TbNodeException;

    void onMsg(TbContext ctx, TbMsg msg) throws ExecutionException, InterruptedException, TbNodeException;

    void destroy();

}

and annotate your implementation with the following multi-value annotation that refers to the runtime:

org.thingsboard.rule.engine.api.RuleNode 

Also each rule node may have a configuration class that implement NodeConfiguration interface.

package org.thingsboard.rule.engine.api;

public interface NodeConfiguration<T extends NodeConfiguration> {

    T defaultConfiguration();

}

• TbKeyFilterNodeConfiguration class:

    package org.thingsboard.rule.engine.node.filter;
    
    import lombok.Data;
    import org.thingsboard.rule.engine.api.NodeConfiguration;
    
    @Data
    public class TbKeyFilterNodeConfiguration implements NodeConfiguration<TbKeyFilterNodeConfiguration> {
    
        private String key;
    
        @Override
        public TbKeyFilterNodeConfiguration defaultConfiguration() {
            TbKeyFilterNodeConfiguration configuration = new TbKeyFilterNodeConfiguration();
            configuration.setKey(null);
            return configuration;
        }
    }

• TbCalculateSumNodeConfiguration class:

    package org.thingsboard.rule.engine.node.transform;
    
    import lombok.Data;
    import org.thingsboard.rule.engine.api.NodeConfiguration;
    
    
    @Data
    public class TbCalculateSumNodeConfiguration implements NodeConfiguration<TbCalculateSumNodeConfiguration> {
    
        private String inputKey;
        private String outputKey;
    
        @Override
        public TbCalculateSumNodeConfiguration defaultConfiguration() {
            TbCalculateSumNodeConfiguration configuration = new TbCalculateSumNodeConfiguration();
            configuration.setInputKey("temperature");
            configuration.setOutputKey("TemperatureSum");
            return configuration;
        }
    }

• TbGetSumIntoMetadataConfiguration class:

    package org.thingsboard.rule.engine.node.enrichment;
    
    import lombok.Data;
    import org.thingsboard.rule.engine.api.NodeConfiguration;
    
    @Data
    public class TbGetSumIntoMetadataConfiguration implements NodeConfiguration<TbGetSumIntoMetadataConfiguration> {
    
        private String inputKey;
        private String outputKey;
    
    
        @Override
        public TbGetSumIntoMetadataConfiguration defaultConfiguration() {
            TbGetSumIntoMetadataConfiguration configuration = new TbGetSumIntoMetadataConfiguration();
            configuration.setInputKey("temperature");
            configuration.setOutputKey("TemperatureSum");
            return configuration;
        }
    }

Configuration classes defines in Rule node classes.

Methods flow

In this section, we explain the purpose of each implemented method from TbNode interface:

Method init()

void init(TbContext ctx, TbNodeConfiguration configuration) throws TbNodeException;

Method to initialize rule node after its creation. Body of init method for each above mention rule node is almost the same. We convert the incoming JSON configuration to the specific NodeConfiguration implementation.

• check key node:

    private TbKeyFilterNodeConfiguration config;
    private String key;
            
    @Override
    public void init(TbContext tbContext, TbNodeConfiguration configuration) throws TbNodeException {
        this.config = TbNodeUtils.convert(configuration, TbKeyFilterNodeConfiguration.class);
        key = config.getKey();
    }

• calculate sum node:

    private TbCalculateSumConfiguration config;
    private String inputKey;
    private String outputKey;
    
    @Override
    public void init(TbContext ctx, TbNodeConfiguration configuration) throws TbNodeException {
        this.config = TbNodeUtils.convert(configuration, TbCalculateSumConfiguration.class);
        inputKey = config.getInputKey();
        outputKey = config.getOutputKey();
    }

• get sum into metadata node:

    private TbGetSumIntoMetadataConfiguration config;
    private String inputKey;
    private String outputKey;
    
    @Override
    public void init(TbContext ctx, TbNodeConfiguration configuration) throws TbNodeException {
        this.config = TbNodeUtils.convert(configuration, TbGetSumIntoMetadataConfiguration.class);
        inputKey = config.getInputKey();
        outputKey = config.getOutputKey();
    }

It is invoked only after rule node creation or updating and takes two input parameters:

• TbContext is an interface that gives access for rule node to majority of services, e.g for save telemetry to DB and notify over WebSockets to all subscriptions of entity data changes:

ctx.getTelemetryService().saveAndNotify(msg.getOriginator(), tsKvEntryList, ttl, new TelemetryNodeCallback(ctx, msg));

• TbNodeConfiguration TbNodeConfiguration is a simple class that has only one field that processed on rule node web UI:

private final JsonNode data;

Method onMsg()

void onMsg(TbContext ctx, TbMsg msg) throws ExecutionException, InterruptedException, TbNodeException;

Method for processing received messages. It is invoked each time when messages arrive in the node. and also takes two input parameters:

• TbMsg is a final serialized class that gives access to fields from the message and also allows you to copy the message, convert the message to ByteBuffer and other way round.

  gives access to fields:

          msg.getData();
          msg.getMetaData();
          msg.getOriginator();
          msg.getType();
          msg.getId();
          msg.getRuleNodeId();
          msg.getRuleChainId();
          msg.getClusterPartition();
          msg.getDataType();

copy message:

        TbMsg copy = msg.copy(UUIDs.timeBased(), entityId, targetId, DEFAULT_CLUSTER_PARTITION);
        
        ***NOTE*** using in cluster mode. 

• TbContext interface also has methods that route outbound messages over the chain, e.g

true & false:

        ctx.tellNext(msg, mapper.readTree(msg.getData()).has(key) ? "True" : "False");

failure:

        ctx.tellFailure(msg, e);
        
        ctx.tellNext(msg, FAILURE, new Exception());

tellSelf and updateSelf methods:

        ctx.tellSelf(tickMsg, curDelay);
        
        ctx.updateSelf(ruleNode);

***NOTE*** Method tellSelf() use in rule nodes that based on a specific delay. Method updateSelf() used on each update the rule node.

Also, TbContext allow to create new message:

        String data = "{temperature:20, humidity:30}"
     
        ctx.newMsg(msg.getType(), msg.getOriginator(), msg.getMetaData(), data);

and transform message:

     ctx.transformMsg(origMsg, origMsg.getType(), origMsg.getOriginator(), metaData, origMsg.getData());

***NOTE*** The difference between these methods that:
    
       TbMsg newMsg() create a new message with a new messageId;
    
       TbMsg transformMsg() convert an already existing message;

Method destroy()

void destroy();

This method that invoked only after rule node stops or update and don’t have input parameters.

Build

• Clone Rule node examples project:

git clone git@github.com:thingsboard/rule-node-examples.git

• Execute the following command from the rule-node-examples folder to build the project:

  • Note First you need to execute this command from your Thingsboard folder.

mvn clean install

Import executable jar-file to your ThingsBoard instance

Import jar-file to your Thingsboard project as dependency library, that should be here:

./target/rule-engine-1.0.0-custom-nodes.jar

NOTE if you have changed the package name from org.thingsboard.rule.engine to your company package name, e.g. com.example.rule.engine, you need also to add your package name in thingsboard.yml file in plugins section:

# Plugins configuration parameters
plugins:
  # Comma separated package list used during classpath scanning for plugins
  scan_packages: "${PLUGINS_SCAN_PACKAGES:org.thingsboard.server.extensions,org.thingsboard.rule.engine,com.example.rule.engine}"

Thingsboard using IDE:

• See separate instructions for IDEA and Eclipse.

Restart ThingsBoard server-side container. Please, refer to the following link to see how to do this: Running server-side container.

**Once ThingsBoard was restarted you need to clear browser cache and refresh the web page to reload UI of Rule Nodes**

Thingsboard as a service:

• first, you need to execute the following command to migrate jar-file to Thingsboard extensions:

sudo mv rule-engine-1.0.0-custom-nodes.jar /usr/share/thingsboard/extensions/

• next, execute the following to change the owner to thingsboard:

sudo chown thingsboard:thingsboard /usr/share/thingsboard/extensions/*

Restart Thingsboard service:

sudo service thingsboard restart

**Once ThingsBoard was restarted you need to clear browser cache and refresh the web page to reload UI of Rule Nodes**

UI configuration

The ThingsBoard rule nodes UI is configured with another project in the official github repo. Please, refer to the following link to see build instructions.

Running Rule Node UI container in hot redeploy mode

To run Rule Node UI container in hot redeploy mode:

• first you need to change constant ruleNodeUiforwardPort from 8080 to 5000 in file proxy.conf.js that should be here:

cd ${TB_WORK_DIR}/ui-ngx/proxy.conf.js

• second, you need to run UI container in hot redeploy mode. Please, refer to the following link to see how to do this: Running UI container in hot redeploy mode.

• last step is to execute the following command from your local directory TB_RULE_NODE_UI_WORK_DIR:

   npm start
  

Next steps

• Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.

• Installation guides - Learn how to setup ThingsBoard on various available operating systems.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.

• Data processing & actions - Learn how to use ThingsBoard Rule Engine.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.

• Advanced features - Learn about advanced ThingsBoard features.