Enrichment Nodes

Enrichment Nodes are used to update meta-data of the incoming Message.

• Calculate delta
• Customer attributes
• Device attributes
• Originator attributes
• Originator fields
• Related attributes
• Tenant attributes
• Originator telemetry
• Tenant details
• Customer details

Calculate delta

Calculates ‘delta’ based on the previous time-series reading and current reading and adds it to the message. Delta calculation is done in scope of the message originator, e.g. device, asset or customer. Useful for smart-metering use case. For example, when the water metering device reports the absolute value of the pulse counter once per day. To find out the consumption for the current day you need to compare value for the previous day with the value for current day.

Delta calculation is done in scope of the message originator, e.g. device, asset or customer.

Configuration parameters:

• Input value key (‘pulseCounter’ by default) - specifies the key that will be used to calculate the delta.
• Output value key (‘delta’ by default) - specifies the key that will store the delta value in the enriched message.
• Decimals - precision of the delta calculation.
• Use cache for latest value (‘enabled’ by default) - enables caching of the latest values in memory.
• Tell ‘Failure’ if delta is negative (‘enabled’ by default) - forces failure of message processing if delta value is negative.
• Add period between messages (‘disabled’ by default) - adds value of the period between current and previous message.

Rule node relations:

The rule node produces message with one of the following relations:

• Success - if the key configured via ‘Input value key’ parameter is present in the incoming message;
• Other - if the key configured via ‘Input value key’ parameter is not present in the incoming message;
• Failure - if the ‘Tell ‘Failure’ if delta is negative’ is set and the delta calculation returns negative value;

Let’s review the rule node behaviour by example. Let’s assume the following configuration:

Let’s assume next messages originated by the same device and arrive to the rule node in the sequence they are listed:

1
2
3
4
msg: {"pulseCounter": 42}, metadata: {"ts": "1616510425000"}
msg: {"pulseCounter": 73}, metadata: {"ts": "1616510485000"}
msg: {"temperature": 22}, metadata: {"ts": "1616510486000"}
msg: {"pulseCounter": 42}, metadata: {"ts": "1616510487000"}

The output will be the following:

1
2
3
4
msg: {"pulseCounter": 42, "delta": 0, "periodInMs": 0}, metadata: {"ts": "1616510425000"}, relation: Success
msg: {"pulseCounter": 73, "delta": 31, "periodInMs": 60000}, metadata: {"ts": "1616510485000"}, relation: Success
msg: {"temperature": 22}, metadata: {"ts": "1616510486000"}, relation: Other
msg: {"pulseCounter": 42}, metadata: {"ts": "1616510487000"}, relation: Failure

Customer attributes

Node finds Customer of the Message Originator entity and adds Customers Attributes or Latest Telemetry value into Message Metadata.

Administrator can configure the mapping between original attribute name and Metadata attribute name.

There is Latest Telemetry checkbox in the Node configuration. If this checkbox selected, Node will fetch Latest telemetry for configured keys. Otherwise, Node will fetch server scope attributes.

Outbound Message Metadata will contain configured attributes if they exist. To access fetched attributes in other nodes you can use this template ‘metadata.temperature’

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

If unsupported Originator type found, an error is thrown.

If Originator does not have assigned Customer Entity Failure chain is used, otherwise Success chain.

Note: Since TB Version 3.3.3 you can use ${metadataKey} for value from metadata, $[messageKey] for value from the message body.

Example: You have the following metadata {"country": "England"}. In addition, you have an attribute, which key is country name and value is capital city ({"England": "London"}).

The aim is to get capital city from attribute for the country from metadata and add result to metadata with the key “city”. To achieve this you can use ${country} as a Source attribute and the “city” as a Target attribute.

Result would be {"city": "London"}.

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

• Send Email

Device attributes

Node finds Related Device of the Message Originator entity using configured query and adds Attributes (client\shared\server scope) and Latest Telemetry value into Message Metadata.

Attributes are added into metadata with scope prefix:

• shared attribute -> shared_
• client attribute -> cs_
• server attribute -> ss_
• telemetry -> no prefix used

For example, shared attribute ‘version’ will be added into Metadata with the name ‘shared_version’. Client attributes will use ‘cs_’ prefix. Server attributes use ‘ss_’ prefix. Latest telemetry value added into Message Metadata as is, without prefix.

In ‘Device relations query’ configuration Administrator can select required Direction and relation depth level. Also Relation type can be configured with required set of Device types.

If multiple Related Entities were found, only the first Entity is used for attributes enrichment, other entities will be discarded.

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

If attribute or telemetry was not found, it is not added into Message Metadata and still routed via Success chain.

Outbound Message Metadata will contain configured attributes only if they exist.

To access fetched attributes in other nodes you can use this template ‘metadata.temperature’

Note: Since TB Version 2.3.1 the rule node has the ability to enable/disable reporting Failure if at least one selected key doesn’t exist in the outbound message.

Originator attributes

Add Message Originator Attributes (client\shared\server scope) and Latest Telemetry value into Message Metadata.

Attributes are added into metadata with scope prefix:

• shared attribute -> shared_
• client attribute -> cs_
• server attribute -> ss_
• telemetry -> no prefix used

For example, shared attribute ‘version’ will be added into Metadata with the name ‘shared_version’. Client attributes will use ‘cs_’ prefix. Server attributes use ‘ss_’ prefix. Latest telemetry value added into Message Metadata as is, without prefix.

Outbound Message Metadata will contain configured attributes if they exist.

To access fetched attributes in other nodes you can use this template ‘metadata.cs_temperature’

Note: Since TB Version 2.3.1 the rule node has the ability to enable/disable reporting Failure if at least one selected key doesn’t exist in the outbound message.

You can see the real life example, where this node is used, in the following tutorials:

• Transform telemetry using previous record
• Send Email

Originator fields

Node fetches fields values of the Message Originator entity and adds them into Message Metadata. Administrator can configure the mapping between field name and Metadata attribute name. If specified field is not part of Message Originator entity fields it will be ignored.

Following Message Originator types are allowed: Tenant, Customer, User, Asset, Device, Alarm, Rule Chain.

Failure chain is used If unsupported Originator type found, otherwise - Success chain.

If field value was not found, it is not added into Message Metadata and still routed via Success chain.

Outbound Message Metadata will contain configured attributes only if they exist.

To access fetched attributes in other nodes you can use this template ‘metadata.devType’

Related attributes

Node finds Related Entity of the Message Originator entity using configured query and adds Attributes or Latest Telemetry value into Message Metadata.

Administrator can configure the mapping between original attribute name and Metadata attribute name.

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.

There is Latest Telemetry checkbox in the Node configuration. If this checkbox selected, Node will fetch Latest telemetry for configured keys. Otherwise, Node will fetch server scope attributes.

If multiple Related Entities are found, only first Entity is used for attributes enrichment, other entities are discarded.

If no Related Entity found Failure chain is used, otherwise Success chain.

Outbound Message Metadata will contain configured attributes if they exist.

To access fetched attributes in other nodes you can use this template ‘metadata.tempo’

Note: Since TB Version 3.3.3 you can use ${metadataKey} for value from metadata, $[messageKey] for value from the message body.

An example of this feature you can see in the description for the Customer attributes node.

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

• Reply to RPC Calls

Tenant attributes

Node finds Tenant of the Message Originator entity and adds Tenant Attributes or Latest Telemetry value into Message Metadata.

Administrator can configure the mapping between original attribute name and Metadata attribute name.

There is Latest Telemetry checkbox in the Node configuration. If this checkbox selected, Node will fetch Latest telemetry for configured keys. Otherwise, Node will fetch server scope attributes.

Outbound Message Metadata will contain configured attributes if they exist. To access fetched attributes in other nodes you can use this template ‘metadata.tempo’

Following Message Originator types are allowed: Tenant, Customer, User, Asset, Device, Alarm, Rule Chain.

If unsupported Originator type found, an error is thrown.

Failure chain is used if Originator does not have assigned Tenant Entity, otherwise - Success chain.

Note: Since TB Version 3.3.3 you can use ${metadataKey} for value from metadata, $[messageKey] for value from the message body.

An example of this feature you can see in the description for the Customer attributes node.

Originator telemetry

Adds Message Originator telemetry values from particular time range that was selected in node configuration to the Message Metadata.

Telemetry values added to Message Metadata without prefix.

The rule node has three fetch modes:

• FIRST: retrieves telemetry from the database that is closest to the beginning of the time range

• LAST: retrieves telemetry from the database that is closest to the end of the time range

• ALL: retrieves all telemetry from the database, which is in the specified time range.

If selected fetch mode FIRST or LAST, Outbound Message Metadata would contain JSON elements(key/value)

Otherwise if the selected fetch mode ALL, telemetry would be fetched as an array.

This array will contain JSON objects with the timestamp and value.

If selected checkbox: Use metadata interval patterns, rule node will use Start Interval and End Interval patterns from metadata.

Patterns units sets in the milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)

• If any pattern will be absent in the Message metadata, the outbound message will be routed via failure chain.

• In addition, if any pattern will have invalid data type, the outbound message will be also routed via failure chain.

Outbound Message Metadata will contain configured telemetry fields if they exist and belong to the selected range.

If attribute or telemetry was not found, it is not added into Message Metadata and still routed via Success chain.

To access fetched telemetry in other nodes you can use this template: JSON.parse(metadata.temperature)

Note: Since TB Version 2.3 the rule node has the ability to choose telemetry sampling order when selected Fetch mode: ALL.

You can see the real-life example, where this node is used, in the following tutorials:

• Telemetry delta calculation

Tenant details

Rule Node Adds fields from Tenant details to the message body or metadata.

There is Add selected details to the message metadata checkbox in the Node configuration. If this checkbox selected, existing fields will be added to the message metadata instead of message data.

Selected details are added into metadata with prefix: tenant_. Outbound Message will contain configured details if they exist.

To access fetched details in other nodes you can use one of the following template:

• metadata.tenant_address

• msg.tenant_address

Failure chain is used if Originator does not have assigned Tenant Entity, otherwise - Success chain.

Customer details

Rule Node Adds fields from Customer details to the message body or metadata.

There is Add selected details to the message metadata checkbox in the Node configuration. If this checkbox selected, existing fields will be added to the message metadata instead of message data.

Selected details are added into metadata with prefix: customer_. Outbound Message will contain configured details if they exist.

To access fetched details in other nodes you can use one of the following template:

• metadata.customer_email

• msg.customer_email

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

If unsupported Originator type found, an error is thrown.

If Originator does not have assigned Customer Entity Failure chain is used, otherwise Success chain.