IoT Hub
IoT Hub Documentation
Transformation Nodes
Getting Started Documentation Guides API FAQ

On this page

Transformation Nodes

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

Change originator

Since TB Version 2.0

image

All incoming Messages in the IoT Hub 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:

  • Originator’s Customer
  • Originator’s Tenant
  • Related Entity that is identified by Relations Query

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.

image

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

Since TB Version 2.0

image

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

JavaScript function receives 3 input parameters:

  • msg - is a Message payload.
  • metadata - is a Message metadata.
  • msgType - is a 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 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.


Example

Node receives Message with payload:

1
2
3
4
{
    "temperature": 22.4,
    "humidity": 78
}

Original Metadata:

1
{ "sensorType" : "temperature" }

Original Message Type - POST_TELEMETRY_REQUEST

The following modifications should be performed:

  • change message type to ‘CUSTOM_UPDATE’
  • add additional attribute version into payload with value v1.1
  • change sensorType attribute value in Metadata to roomTemp

The following transform function will perform all necessary modifications:

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

Since TB Version 2.0

image

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.

image

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:

1
 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 IoT Hub.


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