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

Action Nodes

Action Nodes execute various actions based on incoming Message.

Math Function Node

Since TB Version 3.4.2

The rule node applies math function and saves the result into the message and/or database. See table of supported functions below:

Function Number of arguments Description Reference
ADD 2 x + y  
SUB 2 x - y  
MULT 2 x * y  
DIV 2 x / y  
SIN 1 Returns the trigonometric sine of an angle. Math.sin
SINH 1 Returns the hyperbolic sine of a double value. The hyperbolic sine of x is defined to be (ex - e-x)/2 where e is Euler’s number. Math.sinh
COS 1 Returns the trigonometric cosine of an angle. Math.cos
COSH 1 Returns the hyperbolic cosine of a double value. The hyperbolic cosine of x is defined to be (ex + e-x)/2 where e is Euler’s number. Math.cosh
TAN 1 Returns the trigonometric tangent of an angle. Math.tan
TANH 1 Returns the hyperbolic tangent of a double value. Math.tanh
ACOS 1 Returns the arc cosine of a value; the returned angle is in the range 0.0 through pi. Math.acos
ASIN 1 Returns the arc sine of a value; the returned angle is in the range -pi/2 through pi/2. Math.asin
ATAN 1 Returns the arc tangent of a value; the returned angle is in the range -pi/2 through pi/2. Math.atan
ATAN2 2 Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta). Math.atan2
EXP 1 Returns the value ex, where e is the base of the natural logarithms. Math.exp
EXPM1 1 Returns ex-1. Note that for values of x near 0, the exact sum of expm1(x) + 1 is much closer to the true result of ex than exp(x). Math.expm1
SQRT 1 Returns the correctly rounded positive square root of a double value. Math.sqrt
CBRT 1 Returns the cube root of a double value. Math.cbrt
GET_EXP 1 Returns the unbiased exponent used in the representation of a double. Math.getExponent
HYPOT 2 Returns sqrt(x2 +y2) without intermediate overflow or underflow. Math.getExponent
LOG 1 Returns the natural logarithm (base e) of a double value. Math.log
LOG10 1 Returns the base 10 logarithm of a double value. Math.log10
LOG1P 1 Returns the natural logarithm of the sum of the argument and 1. Note that for small values x, the result of log1p(x) is much closer to the true result of ln(1 + x) than the floating-point evaluation of log(1.0+x). Math.log1p
CEIL 1 Returns the smallest (closest to negative infinity) double value that is greater than or equal to the argument and is equal to a mathematical integer. Math.ceil
FLOOR 1 Returns the largest (closest to positive infinity) double value that is less than or equal to the argument and is equal to a mathematical integer. Math.floor
FLOOR_DIV 2 Returns the largest (closest to positive infinity) long value that is less than or equal to the algebraic quotient. Math.floorDiv
FLOOR_MOD 2 Returns the floor modulus of the long arguments. Math.floorMod
ABS 1 Returns the absolute value of a double value. Math.abs
MIN 2 Returns the smaller of two double values. Math.min
MAX 2 Returns the greater of two double values. Math.max
POW 2 Returns the value of the first argument raised to the power of the second argument. Math.pow
SIGNUM 1 Returns the signum function of the argument; zero if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero. Math.signum
RAD 1 Converts an angle measured in degrees to an approximately equivalent angle measured in radians. Math.toRadians
DEG 1 Converts an angle measured in radians to an approximately equivalent angle measured in degrees. Math.toDegrees
CUSTOM 1-16 Use this function to specify complex math expressions. For example, transform Fahrenheit to Celsius using (x - 32) / 1.8) exp4j

You may use 5 types of arguments:

  • Constant;
  • Value from the message body;
  • Value from the message meta data;
  • Value of the attribute that belongs to the message originator (device, asset, etc). Value should be of Numeric type or string that is convertible to float;
  • Value of the latest time-series that belongs to the message originator (device, asset, etc). Value should be of Numeric type or string that is convertible to float;

Primary use case for this rule node is to take one or more values from the database and modify them based on data from the message. For example, you may increase totalWaterConsumption based on the deltaWaterConsumption reported by device.

Alternative use case is the replacement of simple JS script nodes with more light-weight and performant implementation. For example, you may transform Fahrenheit to Celsius (C = (F - 32) / 1.8) using CUSTOM operation and expression: (x - 32) / 1.8).

The execution is synchronized in scope of message originator (e.g. device) and server node. If you have rule nodes in different rule chains, they will process messages from the same originator synchronously in the scope of the server node.

The result of the function may be added to the message body or metadata. You may also save the result to the database as an attribute or time-series.

Create Alarm Node

Since TB Version 2.0

image

This Node tries to load the 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:

  • Alarm Details Builder script
  • Alarm Type - any string that represents Alarm Type
  • Alarm Severity - {CRITICAL | MAJOR | MINOR | WARNING | INDETERMINATE}
  • is Propagate - whether Alarm should be propagated to all parent related entities.

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

  • read alarm config from message:

  • get alarm type using pattern with fields from message metadata:

    image

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

  • filter propagation to parent entities by relation types:

    image

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

  • Message payload can be accessed via msg property. For example msg.temperature
  • Message metadata can be accessed via metadata property. For example metadata.customerName
  • Message type can be accessed via msgType property. For example msgType

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:

1
2
3
4
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.

1
2
3
4
5
6
7
8
9
10
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:

  • Alarm details - object returned from Alarm Details Builder script
  • Alarm status - if new alarm -> ACTIVE_UNACK. If existing Alarm -> does not changed
  • Severity - value from Node Configuration
  • Propagation - value from Node Configuration
  • Alarm type - value from Node Configuration
  • Alarm start time - if new alarm -> current system time. If existing Alarm -> does not changed
  • Alarm end time - current system time

Outbound message will have the following structure:

  • Message Type - ALARM
  • Originator - the same originator from inbound Message
  • Payload - JSON representation of new Alarm that was created/updated
  • Metadata - all fields from original Message Metadata

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "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:

  • Alarm Details Builder script
  • Alarm Type - any string that represents Alarm Type

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

  • Message payload can be accessed via msg property. For example msg.temperature
  • Message metadata can be accessed via metadata property. For example metadata.customerName
  • Message type can be accessed via msgType property. For example msgType
  • Current Alarm Details can be accessed via metadata.prevAlarmDetails.

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

1
2
3
4
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.

1
2
3
4
5
6
7
8
9
10
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:

  • change alarm status to CLEARED_ACK if it was already acknowledged, otherwise to CLEARED_UNACK
  • set clear time to current system time
  • update Alarm details with new object returned from Alarm Details Builder script

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:

  • Message Type - ALARM
  • Originator - the same originator from inbound Message
  • Payload - JSON representation of Alarm that was cleared
  • Metadata - all fields from original Message Metadata. Also additional property inside Metadata will be added -> isClearedAlarm with true value.

Here is an example of Outbound Message payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "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 (deprecated)

Since TB Version 2.1

Delays incoming messages for configurable period.

Configuration:

image

  • Period in seconds - specifies the value of the period during which incoming message should be suspended
  • Maximum pending messages - specifies the amount of maximum allowed pending messages (queue of suspended messages)

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:

  • Message generation frequency in seconds
  • Message originator
  • JavaScript function that will generate the actual message.

JavaScript function receive 3 input parameters:

  • prevMsg - is a previously generated Message payload.
  • prevMetadata - is a previously generated Message metadata.
  • prevMsgType - is a previously generated Message type.

Script should return the following structure:

1
2
3
4
5
{   
    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

  • metadata - is a Message metadata.
  • msg - is a Message payload.
  • msgType - is a Message type.

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:

  • MQTT
  • HTTP
  • CoAP

Message payload example:

1
2
3
4
5
6
7
{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

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

  • Inbound Message originator is not a Device entity
  • Request id is not present in the Message metadata
  • Inbound Message payload is empty

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:

1
2
3
4
5
6
7
{
  "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:

  • Inbound Message originator is not a Device entity
  • Inbound Message has missed method or params fields
  • If Node will not receive a response during configured timeout

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:

  • Client attributes
  • Shared attributes
  • Server attributes

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:

1
2
3
4
{
  "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

Additionally, you could disable updating values for incoming keys for the latest timeseries data (ts_kv_latest table) if ‘Skip latest persistence’ flag is set to true. This could be helpful for highly loaded use-cases to decrease the pressure on the DB. Please note, this feature could be enabled when the use-case does not require advanced filtering on the Dashboards. For getting the latest value, the historical data could be fetched with limit 1 and DESC order.

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.

Since TB Version 3.3.3 you can enable ‘useServerTs’ param to use the timestamp of the message processing instead of the timestamp from the message. Useful for all sorts of sequential processing if you merge messages from multiple sources (devices, assets, etc).

In the case of sequential processing, the platform guarantees that the messages are processed in the order of their submission to the queue. However, the timestamp of the messages originated by multiple devices/servers may be unsynchronized long before they are pushed to the queue. The DB layer has certain optimizations to ignore the updates of the “attributes” and “latest values” tables if the new record has a timestamp that is older than the previous record.

So, to make sure that all the messages will be processed correctly, one should enable this parameter for sequential message processing scenarios.

Expected Message Payload example:

1
2
3
4
5
6
{  
  "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 $entityId, 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 in the data of the message or is not a JSON Primitive, the outbound message will be routed via Failure chain, otherwise, the message will be routed via Success chain.

NOTE: Please make sure that you are not using metadata keys in the configuration - only data keys are possible.


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

  • Customer name pattern - can be set direct customer name or pattern can be used, that will be resolved to the real customer name using Message metadata.
  • Create new customer if not exists - if checked will create new customer if it doesn’t exist.
  • Customers cache expiration time - specifies maximum time interval is seconds allowed to store found customers records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target customer doesn’t exist and Create customer if not exists is unchecked.

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

  • Customer name pattern - can be set direct customer name or pattern can be used, that will be resolved to the real customer name using Message metadata.
  • Customers cache expiration time - specifies maximum time interval is seconds allowed to store found customers records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target customer doesn’t exist.

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:

  • entity name pattern;

  • entity type pattern.

Otherwise, only name pattern should be set.

Configuration:

image

  • Direction - following types are allowed: From, To.
  • Relation type - type of directed connections to message originator entity. Default types Contains and Manages can be selected from the drop-down list.
  • Name pattern and Type pattern - can be set direct entity name/type or pattern can be used, that will be resolved to the real entity name/type using Message metadata.
  • Entities cache expiration time - specifies maximum time interval is seconds allowed to store found target entity records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target entity doesn’t exist.

In other cases Message will be routed via Success chain.

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

  • remove current relations from the originator of the incoming message based on direction and type:

    image

  • change the originator of the incoming message to the selected entity and process outboud messages as messages from another entity:

    image


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

  • Direction - following types are allowed: From, To.
  • Relation type - type of directed connections to message originator entity. Default types Contains and Manages can be selected from the drop-down list.
  • Name pattern - can be set direct entity name or pattern can be used, that will be resolved to the real entity name using Message metadata.
  • Entities cache expiration time - specifies maximum time interval is seconds allowed to store found target entity records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target entity doesn’t exist.

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: Polygon and Circle

Metadata of the incoming message must include key with name perimeter and following data structure:

  • Polygon
1
[[latitude1,longitude1],[latitude2,longitude2], ... ,[latitudeN,longitudeN]]
  • Circle
1
{"latitude":"value1","longitude":"value2","radius":"value3","radiusUnit":"KILOMETER"}

Keys “latitude” and “longitude” it’s coordinates of the point.

The “radius” key - it’s the distance from the coordinate point to the circle.

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

The “radiusUnit” 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:

  • Polygon

image

  • Circle

image

Event Types

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

  • Entered — is reporting whenever latitude and longitude from the incoming message to belong the required perimeter area for the first time;
  • Left — is reporting whenever latitude and longitude from the incoming message not belong the required perimeter area for the first time;
  • Inside and Outside events are used to report current status.

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:

  • incoming message has no configured latitude or longitude key in data or metadata.
  • missing perimeter definition;


REST Call Reply Node

Since TB Version 2.1

image

Sends reply to REST API call that was originally sent to rule engine.

Expects messages with any message type. Forwards incoming message as a reply to REST API call sent to rule engine.

Configuration:

image


Push to cloud

Since TB Version 3.3

image

Push messages from edge to cloud. This node used only on edge to push messages from edge to cloud. Once message arrived into this node it’s going to be converted into cloud event and saved to the local database. Node doesn’t push messages directly to cloud, but stores event(s) in the cloud queue. Supports next originator types:

  • DEVICE
  • ASSET
  • ENTITY_VIEW
  • DASHBOARD
  • TENANT
  • CUSTOMER
  • EDGE

As well node supports next message types:

  • POST_TELEMETRY_REQUEST
  • POST_ATTRIBUTES_REQUEST
  • ATTRIBUTES_UPDATED
  • ATTRIBUTES_DELETED
  • ALARM

In case successful storage edge event to database message will be routed via Success route.

image

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

  • Node was not able to save edge event to database
  • Unsupported originator type arrived
  • Unsupported message type arrived

Push to edge

Since TB Version 3.3

image

Push messages from cloud to edge. Message originator must be assigned to particular edge or message originator is EDGE entity itself. This node used only on cloud instances to push messages from cloud to edge. Once message arrived into this node it’s going to be converted into edge event and saved to the database. Node doesn’t push messages directly to edge, but stores event(s) in the edge queue. Supports next originator types:

  • DEVICE
  • ASSET
  • ENTITY_VIEW
  • DASHBOARD
  • TENANT
  • CUSTOMER
  • EDGE

As well node supports next message types:

  • POST_TELEMETRY_REQUEST
  • POST_ATTRIBUTES_REQUEST
  • ATTRIBUTES_UPDATED
  • ATTRIBUTES_DELETED
  • ALARM

In case successful storage edge event to database message will be routed via Success route.

image

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

  • Node was not able to save edge event to database
  • Unsupported originator type arrived
  • Unsupported message type arrived

Add To Group Node

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports PE Action Nodes feature.
Use ThingsBoard Cloud or install your own platform instance.

Since TB Version 2.0.2

image

Adds Message Originator Entity to Entity Group.

Following Message Originator types are allowed: Customer, Asset, Device.

Finds target Entity Group by group name pattern and then adds Originator Entity to this group. Will create new Entity Group if it doesn’t exist and Create new group if not exists is set to true.

Configuration:

image

  • Group name pattern - can be set direct group name or pattern can be used, that will be resolved to the real group name using Message metadata.
  • Create new group if not exists - if checked will create new entity group if it doesn’t exist.
  • Groups cache expiration time - specifies maximum time interval is seconds allowed to store found entity group records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target entity group doesn’t exist and Create new group if not exists is unchecked.

In other cases Message will be routed via Success chain.


Remove From Group Node

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports PE Action Nodes feature.
Use ThingsBoard Cloud or install your own platform instance.

Since TB Version 2.0.2

image

Removes Message Originator Entity from Entity Group.

Following Message Originator types are allowed: Customer, Asset, Device.

Finds target Entity Group by group name pattern and then removes Originator Entity from this group.

Configuration:

image

  • Group name pattern - can be set direct group name or pattern can be used, that will be resolved to the real group name using Message metadata.
  • Groups cache expiration time - specifies maximum time interval is seconds allowed to store found entity group records. 0 value means that records will never expire.

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

  • When Originator entity type is not supported.
  • Target entity group doesn’t exist.

In other cases Message will be routed via Success chain.


Generate Report Node

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports PE Action Nodes feature.
Use ThingsBoard Cloud or install your own platform instance.

Since TB Version 2.1

image

Generates report files by capturing target dashboard with specific configuration.

This node can be configured to use specific report configuration or take it from incoming message body.

Mode when report configuration is taken from message body usually is used when message is generated by Generate Report Scheduler Event.

Generate Report node invokes Reports Server to generate report file using specified dashboard.

Resulting report file is stored in DataBase using File Storage feature and reference to this file is stored in attachments field of output message metadata.

attachments metadata field can be used by other Rule Nodes to get actual file from DataBase. For instance To Email Node detects presence of this field and prepares email attachments used by Send Email Node to send email with attachments.

Configuration:

image

  • Use system reports server - if set, Reports Server endpoint URL will be taken from system configuration (thingsboard.yml).
  • Reports server endpoint URL - endpoint URL of Reports Server.
  • Use report config from message - if set, report generation configuration will be taken from incoming message body.
  • Base URL - base URL of ThingsBoard UI that should be accessible by Report Server.
  • Dashboard - dashboard that will be used for report generation.
  • Dashboard state parameter value - used to specify target dashboard state for report generation. Can be set automatically by clicking on right most button of the field and invoking Select dashboard state dialog.
  • Timezone - timezone in which target dashboard will be presented in report.
  • Use dashboard timewindow - if set, timewindow configured in the target dashboard will be used during report generation.
  • Timewindow - specific dashboard timewindow that will be used during report generation.
  • Report name pattern - file name pattern of generated report, can contain date-time pattern in form of %d{date-time pattern}. See SimpleDateFormat documentation for date-time pattern details.
  • Report type - report file type, can be PDF | PNG | JPEG.
  • Use current user credentials - if set, credentials of user created this report configuration will be used to open dashboard UI during report generation.
  • Customer user credentials - target customer user whose credentials will be used to open dashboard UI during report generation.

Generate Test Report button is used for testing purposes. It invokes report generation process with provided configuration. Resulting report file will be automatically downloaded if the report generation will be successful.

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

  • When Use report config from message is set and incoming message does not contain valid report configuration JSON object.
  • When Reports Server is unavailable at the specified endpoint URL.
  • When Reports Server will fail generate report and return corresponding error message.

In other cases Message will be routed via Success chain.


Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports PE Action Nodes feature.
Use ThingsBoard Cloud or install your own platform instance.

Since TB Version 2.0.2

image

Forwards Message to selected Integration as downlink message.

Message will be pushed to the selected integration downlink queue.

Configuration:

image

  • Integration - target Integration for downlink message processing.

Failure chain is used if Message push to Integration will fail, otherwise Success chain.


Change Owner Node

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports PE Action Nodes feature.
Use ThingsBoard Cloud or install your own platform instance.

Since TB Version 2.3.1

image

Changes Owner of the Originator entity to the selected Owner by type:

  • Tenant

image

  • Customer

image

Rule node finds target Owner by owner name pattern and then change the owner of the originator entity.

  • Owner name pattern - can be set direct customer name or pattern can be used, that will be resolved to the real customer name using Message metadata.
  • Create new owner if not exists - if checked will create new owner(customer) if it doesn’t exist.
  • Owner cache expiration time - specifies maximum time interval is seconds allowed to store found owners(customers) records. 0 value means that records will never expire.

If an entity already belongs to this owner or entity owner is successfully changed - Message sent via Success chain, otherwise, Failure chain will be used.