"Message enrichments is the ability of an IoT hub to stamp messages with additional information before the messages are sent to the designated endpoint." (Overview of Azure IoT Hub message enrichments | Microsoft Docs).
Most of the time message enrichment is used when you need some additional property in your downstream pipeline. Those properties could be static strings or information derived by the device twin. That simplifies the downstream processing avoiding the retrieval of that information eventually via API call to the IoT Hub Device register and caching it in the event processor application.
By default, you can add up to ten (or two) "enrichments" according to the IoT Hub tier and you can use only simple type.
Ooooh yep, no hierarchical objects (aka complex JSON). If this is not enough for your solution, don't feel so bad! I have a solution for you!
The simple idea is the following: instead of having a simple value in your enrichment you can have an escaped JSON and let parse it as a hierarchical object in your downstream service.
For example, in your Twin Tags, you can enter a literal value that represents your escaped JSON payload like this:
Of course, you need to remember the limits on the size of the Tags:
- The total message size, including the enrichments, can't exceed 256 KB:
https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-message-enrichments-overview#limitations - Twins limits: Tags and Properties has their own maximum lengths:
Understand Azure IoT Hub device twins | Microsoft Docs
Anyway, those limits accommodate easily serializing values like GPS position or Street Address.
Then you can configure the message enrichment Value to point to this tag:
This is going to augment your telemetry with an additional custom property with the literal string value obtained by the device tag.
Now of course to get the most of the payload you need to parse the content of this escaped JSON.
A simple solution is to leverage Azure Stream Analytics by adding a simple custom UDF (function in JavaScript):
That function parses the escaped JSON and returns the object.
Now the trick is to get the User property out of the Input of your ASA Job which you configure to obtain the value out of the IoT Hub embedded endpoint (see above: we configure the message enrichment for the "event" endpoint which is the event hub compatible embedded endpoint of IoT Hub).
That's the query:
SELECT
TestValue,
udf.parseJson(GetMetadataPropertyValue([hubTelemetry], '[User].[hierarchicalProp]') ) as hierarchicalPropParsed
INTO
[outStorage]
FROM
[hubTelemetry]
And this is the outcome:
{"TestValue":"TestMessage","hierarchicalPropParsed":{"nestedProp1":1,"nestedProp2":2}}
As you can see now the nestedProp 1 and 2 are parsed properly as full-blown JSON properties.
You can leverage those properties in the ASA Job query to filter against / aggregate or perform other operations as needed.
Summary
In this article, we saw a simple method to augment the capabilities of your enriched messages.
I found this quite important especially when you have correlated information that you want to host in the same Tag value, such as Geographical position (Lat / Lon) or an address.
This approach allows you to scale out the number of User properties you want to stream with your device telemetry reducing the data volume your device needs to send over the wire and going beyond the maximum number of configurable properties.
