ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.
ThingsBoard Professional Edition with White-labeling and Platform Integrations Learn More

Transformation Nodes

Transformation Nodes are used for changing incoming Message fields like Originator, Message Type, Payload and Metadata.

Change originator


All incoming Messages in the Thingsboard have originator field that identifies an entity that submits Message. It could be a Device, Asset, Customer, Tenant, etc.

This node is used in cases when a submitted message should be processed as a message from another entity. For example, Device submits telemetry and telemetry should be copied into higher level Asset or to a Customer. In this case, Administrator should add this node before Save Timeseries Node.

The originator can be changed to:

In ‘Relations query’ configuration Administrator can select required Direction and relation depth level. Also set of Relation filters can be configured with required Relation type and Entity Types.


If multiple Related Entities are found, only the first Entity is used as new originator, other entities are discarded.

Failure chain is used if no Related Entity / Customer / Tenant was found, otherwise - Success chain.

Outbound Message will have new originator Id.

Script Transformation Node


Changes Message payload, Metadata or Message type using configured JavaScript function.

JavaScript function receives 3 input parameters:

Script should return the following structure:

    msg: new payload,
    metadata: new metadata,
    msgType: new msgType 


All fields in resulting object are optional and will be taken from original message if not specified.

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

JavaScript transform function can be verified using Test JavaScript function.


Node receives Message with payload:

    "temperature": 22.4,
    "humidity": 78

Original Metadata:

{ "sensorType" : "temperature" }

Original Message Type - POST_TELEMETRY_REQUEST

The following modifications should be performed:

The following transform function will perform all necessary modifications:

var newType = "CUSTOM_UPDATE";
msg.version = "v1.1";
metadata.sensorType = "roomTemp"
return {msg: msg, metadata: metadata, msgType: newType};

You can see real life example, how to use this node in those tutorials:

To Email Node


Transforms message to Email Message by populating email fields using values derived from Message metadata. Set ‘SEND_EMAIL’ output Message type that can be accepted later by Send Email Node. All email fields can be configured to use values from metadata.


For example incoming message has deviceName field in metadata and email body should contain its value.

In this case value of deviceName can be referenced as ${deviceName} like in the following example:

 Device ${deviceName} has high temperature

Additionally this node can prepare email attachments if incoming message metadata contains attachments field with reference to files stored in DataBase.

NOTE: This is part of File Storage feature supported by ThingsBoard Professional Edition.

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