Star
Try it now
Solutions
Customers
Use Cases
Partners
About Us
Pricing Docs Guides

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

Action Nodes

Action Nodes execute various actions based on incoming Message.

Create Alarm Node

Since TB Version 2.0

image

This Node tries to load latest Alarm with configured Alarm Type for Message Originator. If Uncleared Alarm exist, then this Alarm will be updated, otherwise a new Alarm will be created.

Node Configuration:

Note: Since TB Version 2.3.0 the rule node has the ability to:

Note: Since TB Version 2.4.3 the rule node has the ability to:

Alarm Details Builder script used for generating Alarm Details JsonNode. It is useful for storing additional parameters inside Alarm. For example you can save attribute name/value pair from Original Message payload or Metadata.

Alarm Details Builder script should return details object.

image

Optional: previous Alarm Details can be accessed via metadata.prevAlarmDetails. If previous Alarm does not exist, this field will not be present in Metadata. Note that metadata.prevAlarmDetails is a raw String field and it needs to be converted into object using this construction:

var details = {};
if (metadata.prevAlarmDetails) {
    details = JSON.parse(metadata.prevAlarmDetails);
}

Alarm Details Builder script function can be verified using Test JavaScript function.

Example of Details Builder Function

This function takes count property from previous Alarm and increment it. Also put temperature attribute from inbound Message payload into Alarm details.

var details = {temperature: msg.temperature, count: 1};

if (metadata.prevAlarmDetails) {
    var prevDetails = JSON.parse(metadata.prevAlarmDetails);
    if(prevDetails.count) {
        details.count = prevDetails.count + 1;
    }
}

return details;

Alarm created/updated with those properties:

Outbound message will have the following structure:

After new Alarm created, Outbound message will contain additional property inside Metadata - isNewAlarm with true value. Message will be passed via Created chain.

After existing Alarm updated, Outbound message will contain additional property inside Metadata - isExistingAlarm with true value. Message will be passed via Updated chain.

Here is an example of Outbound Message payload

{
  "tenantId": {
    "entityType": "TENANT",
    "id": "22cd8888-5dac-11e8-bbab-ad47060c9bbb"
  },
  "type": "High Temperature Alarm",
  "originator": {
    "entityType": "DEVICE",
    "id": "11cd8777-5dac-11e8-bbab-ad55560c9ccc"
  },
  "severity": "CRITICAL",
  "status": "ACTIVE_UNACK",
  "startTs": 1526985698000,
  "endTs": 1526985698000,
  "ackTs": 0,
  "clearTs": 0,
  "details": {
    "temperature": 70,
    "ts": 1526985696000
  },
  "propagate": true,
  "id": "33cd8999-5dac-11e8-bbab-ad47060c9431",
  "createdTime": 1526985698000,
  "name": "High Temperature Alarm"
}

More details about Alarms in the Thingsboard can be found in this tutorial

You can see the real life example, where this node is used, in the next tutorial:


Clear Alarm Node

Since TB Version 2.0

image

This Node loads the latest Alarm with configured Alarm Type for Message Originator and Clear the Alarm if it exist.

Node Configuration:

Note: Since TB Version 2.3.0 the rule node has the ability to get alarm type using pattern with fields from message metadata:

image

Alarm Details Builder script used for updating Alarm Details JsonNode. It is useful for storing additional parameters inside Alarm. For example you can save attribute name/value pair from Original Message payload or Metadata.

Alarm Details Builder script should return details object.

image

Note that metadata.prevAlarmDetails is a raw String field and it needs to be converted into object using this construction:

var details = {};
if (metadata.prevAlarmDetails) {
    details = JSON.parse(metadata.prevAlarmDetails);
}

Alarm Details Builder script function can be verified using Test JavaScript function.

Example of Details Builder Function

This function takes count property from previous Alarm and increment it. Also put temperature attribute from inbound Message payload into Alarm details.

var details = {temperature: msg.temperature, count: 1};

if (metadata.prevAlarmDetails) {
    var prevDetails = JSON.parse(metadata.prevAlarmDetails);
    if(prevDetails.count) {
        details.count = prevDetails.count + 1;
    }
}

return details;

This Node updates Current Alarm:

In case when Alarm does not exist or it is already Cleared Alarm, original Message will be passed to the next nodes via False chain.

Otherwise new Message will be passed via Cleared chain.

Outbound message will have the following structure:

Here is an example of Outbound Message payload

{
  "tenantId": {
    "entityType": "TENANT",
    "id": "22cd8888-5dac-11e8-bbab-ad47060c9bbb"
  },
  "type": "High Temperature Alarm",
  "originator": {
    "entityType": "DEVICE",
    "id": "11cd8777-5dac-11e8-bbab-ad55560c9ccc"
  },
  "severity": "CRITICAL",
  "status": "CLEARED_UNACK",
  "startTs": 1526985698000,
  "endTs": 1526985698000,
  "ackTs": 0,
  "clearTs": 1526985712000,
  "details": {
    "temperature": 70,
    "ts": 1526985696000
  },
  "propagate": true,
  "id": "33cd8999-5dac-11e8-bbab-ad47060c9431",
  "createdTime": 1526985698000,
  "name": "High Temperature Alarm"
}

More details about Alarms in the Thingsboard can be found in this tutorial

You can see the real life example, where this node is used, in the next tutorial:


Delay Node

Since TB Version 2.1

image

Delays incoming messages for configurable period.

Configuration:

image

When delay period for particular incoming message will be reached it will be removed from pending queue and routed to the next nodes via Success chain.

Each next message will be routed via Failure chain if the maximum pending messages limit will be reached.


Generator Node

Since TB Version 2.0

image

Generates Messages with configurable period. JavaScript function is used for message generation.

Node Configuration:

JavaScript function receive 3 input parameters:

Script should return the following structure:

{   
    msg: new payload,
    metadata: new metadata,
    msgType: new msgType 
}

image

All fields in resulting object are optional and will be taken from previously generated Message if not specified.

Outbound Message from this Node will be new Message that was constructed using configured JavaScript function.

JavaScript generator function can be verified using Test JavaScript function.

This node can be used for Rule Chain debugging purposes.


Log Node

Since TB Version 2.0

image

Transform incoming Message with configured JavaScript function to String and log final value into the Thingsboard log file.

INFO log level is used for logging.

JavaScript function receive 3 input parameters

Script should return String value.

image

JavaScript transform function can be verified using Test JavaScript function.

You can see the real life example, where this node is used, in the next tutorial:

RPC Call Reply Node

Since TB Version 2.0

image

Sends response to the RPC Call originator. All incoming RPC requests are passed through Rule Chain as Messages. Also all RPC requests have request ID field. It is used for mapping requests and responses. Message Originator must be a Device entity because RPC response is initiated to the Message Originator.

Node configuration has special request ID field mapping. If the mapping is not specified, requestId metadata field is used by default.

image

RPC request can be received via different transports:

Message payload example:

{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

Message will be routed via Failure chain in the following cases:

For more details how RPC works in the Thingsboard, please read RPC capabilities Article.

You can see the real life example, where this node is used, in the next tutorial:

RPC Call Request Node

Since TB Version 2.0

image

Sends RPC requests to the Device and routing response to the next Rule nodes. Message Originator must be a Device entity as RPC request can be initiated only to device.

Node configuration has Timeout field used to specify timeout waiting for response from device.

image

Message payload must have correct format for RPC request. It must contains method and params fields. Example:

{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

If Message Payload contains requestId field, its value used to identify RPC request to the Device. Otherwise random requestId will be generated.

Outbound Message will have same originator and metadata as in inbound Message. Response from the Device will be added into Message payload.

Message will be routed via Failure chain in the following cases:

Otherwise Message will be routed via Success chain.

For more details how RPC works in the Thingsboard, please read RPC capabilities article.


Save Attributes Node

Since TB Version 2.0

image

Stores attributes from incoming Message payload to the database and associate them to the Entity, that is identified by the Message Originator. Configured scope is used to identify attributes scope.

Supported scope types:

image

Expects messages with POST_ATTRIBUTES_REQUEST message type. If message Type is not POST_ATTRIBUTES_REQUEST, Message will be routed via Failure chain.

When attributes are uploaded over existing API (HTTP / MQTT / CoAP / etc.) Message with correct payload and type will be passed into Input node of the Root Rule Chain.

In cases when it is required to trigger attributes saving inside Rule Chain, the Rule Chain should be configured to transform Message payload to the expected format and set message type to POST_ATTRIBUTES_REQUEST. It could be done using Script Transformation Node.

Expected Message Payload example:

{
  "firmware_version": "1.0.1",
  "serial_number": "SN-001"
}

After successful attributes saving, original Message will be passed to the next nodes via Success chain, otherwise Failure chain is used.


Save Timeseries Node

Since TB Version 2.0

image

Stores Timeseries data from incoming Message payload to the database and associate them to the Entity, that is identified by the Message Originator. Configured TTL seconds is used for timeseries data expiration. 0 value means that data will never expire.

image

Expects messages with POST_TELEMETRY_REQUEST message type. If message Type is not POST_TELEMETRY_REQUEST, Message will be routed via Failure chain.

When timeseries data is published over existing API (HTTP / MQTT / CoAP / etc.) Message with correct payload and type will be passed into Input node of the Root Rule Chain.

In cases when it is required to trigger timeseries data saving inside Rule Chain, the Rule Chain should be configured to transform Message payload
to the expected format and set message type to POST_TELEMETRY_REQUEST. It could be done using Script Transformation Node.

Message Metadata must contain ts field. This field identifies timestamp in milliseconds of published telemetry.

Also, if Message Metadata contains TTL field, its value is used for timeseries data expiration, otherwise TTL from Node Configuration is used.

Expected Message Payload example:

{  
  "values": {
    "key1": "value1",
    "key2": "value2"
  }
}

After successful timeseries data saving, original Message will be passed to the next nodes via Success chain, otherwise Failure chain is used.


Save to Custom Table

Since TB Version 2.3.1

image

Node stores data from incoming Message payload to the Cassandra database into the predefined custom table that should have cs_tb_ prefix, to avoid the data insertion to the common TB tables.

Please note, that rule node can be used only for Cassandra DB.

Configuration:

Administrator should set the custom table name without prefix: cs_tb_.

image

Administrator can configure the mapping between the Message field names and Table columns name. If the mapping key is $entity_id, that is identified by the Message Originator, then to the appropriate column name(mapping value) will be write the message originator id.

image

If specified message field does not exist or is not a JSON Primitive, the outbound message will be routed via Failure chain, otherwise, the message will be routed via Success chain.


Assign To Customer Node

Since TB Version 2.2

image

Assign Message Originator Entity to Customer.

Following Message Originator types are allowed: Asset, Device, Entity View, Dashboard.

Finds target Customer by customer name pattern and then assign Originator Entity to this customer.

Will create new Customer if it doesn’t exists and Create new Customer if not exists is set to true.

Configuration:

image

Message will be routed via Failure chain in the following cases:

In other cases Message will be routed via Success chain.


Unassign From Customer Node

Since TB Version 2.2

image

Unassign Message Originator Entity from Customer.

Following Message Originator types are allowed: Asset, Device, Entity View, Dashboard.

Finds target Customer by customer name pattern and then unassign Originator Entity from this customer.

Configuration:

image

Message will be routed via Failure chain in the following cases:

In other cases Message will be routed via Success chain.


Create Relation Node

Since TB Version 2.2.1

image

Create the relation from the selected entity to originator of the message by type and direction.

Following Message Originator types are allowed: Asset, Device, Entity View, Customer, Tenant, Dashboard.

Finds target Entity by metadata key patterns and then create a relation between Originator Entity and the target entity.

If selected entity type Asset, Device or Customer rule node will create new Entity if it doesn’t exist and selected checkbox: Create new Entity if not exists.

Note: if selected entity type Asset or Device you need to set two patterns:

Otherwise, only name pattern should be set.

Configuration:

image

Message will be routed via Failure chain in the following cases:

In other cases Message will be routed via Success chain.

Note: Since TB Version 2.3 the rule node has the ability to:


Delete Relation Node

Since TB Version 2.2.1

image

Delete the relation from the selected entity to originator of the message by type and direction.

Following Message Originator types are allowed: Asset, Device, Entity View, Customer, Tenant, Dashboard.

Finds target Entity by entity name pattern and then delete a relation between Originator Entity and this entity.

Configuration:

image

Message will be routed via Failure chain in the following cases:

In other cases Message will be routed via Success chain.

Note: Since TB Version 2.3 the rule node has the ability to deletes relation from the originator of the incoming message to the specified entity or to the list of entities based on direction and type by disabling the following checkbox in the rule node configuration:

image


GPS Geofencing Events Node

Since TB Version 2.3.1

image

Produces incoming messages by GPS based parameters. Extracts latitude and longitude from incoming message data or metadata and returns different events based on configuration parameters (geo fence).

image

The rule node fetches perimeter information from message metadata by default. If Fetch perimeter information from message metadata is unchecked, additional information should be configured.


Fetch perimeter information from message metadata

There are two options of area definition based on the perimeter type:

[[lat1,lon1],[lat2,lon2], ... ,[latN,lonN]]
"centerLatitude": "value1", "centerLongitude": "value2", "range": "value3"

All values for these keys are in double-precision floating-point data type.

The "rangeUnit" key requires specific value from a list of METER, KILOMETER, FOOT, MILE, NAUTICAL_MILE (capital letters obligatory).
Fetch perimeter information from node configuration

There are two options of area definition based on the perimeter type:

image

image

Event Types

There are 4 types of events managed by geofencing rule node:

Administrator can configure duration time threshold for reporting inside or outside event. For example, whenever minimal inside time is set to 1 minute the message originator is considered as being inside the perimeter 60 seconds after entering the area. Minimal outside time defines whenever message originator is considered as out of the perimeter as well.

image

Failure chain will to be used when: