On this page

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

• Change originator
• Script Transformation Node
• To Email Node
• Duplicate To Group Node
• Duplicate To Related Node

Change originator

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.

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:

• 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 
}

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:

• Transform incoming telemetry
• Reply to RPC Calls

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:

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:

• Send Email

Duplicate To Group Node

IoT Hub Feature

Duplicates message to all entities belonging to specific Entity Group.

Entities are fetched from Entity Group detected according to the configuration.

Entity Group can be specified directly or can be message originator entity itself.

For each entity from group new message is created with entity as originator and message parameters copied from original message.

Configuration:

• Entity group is message originator - if set, message originator will be considered as Entity Group used to fetch entities. In this case incoming message will be routed via Failure chain if message originator type is not Entity Group.
• Target entity group - specific target Entity Group used to fetch entities.

New messages will be duplicated to group entities and forwarded via Success chain if target Entity Group is detected successfully and contains at least one entity. Otherwise original message will be forwarded via Failure chain.

Duplicate To Related Node

IoT Hub Feature

Duplicates message to related entities fetched by relation query.

Related Entities found using configured relation direction and Relation Type.

For each found related entity new message is created with related entity as originator and message parameters copied from original message.

Configuration:

• Relations query - query used to find new entities starting from incoming message originator. 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.

New messages will be duplicated to found entities and forwarded via Success chain if at least one entity will be found using Relations Query. Otherwise original message will be forwarded via Failure chain.