Product Mapping with arrays

Currently IoT Data Engine is supporting DTDL v3 and array support is coming with it.

This document will explain how to create array mapping on UI and how does it work in the background.

Primitive Arrays

Primitive arrays are fully supported.

["value1", "value2", "value3"]

To define in mapping that in a field is a primitive array, the field name should end with [].

In this case your input JSON should look like:

{
    "primitiveArray": ["value1", "value2", "value3"]
}

and output will look like:

{
    "CurrentValue": {
        "stringArray": ["value1", "value2", "value3"]
    }
}

The conversion of types will work same as for any other field, therefore in this case if one of elements of primitiveArray would be a number: 123, it will become a string: "123".

Complex Arrays

Complex arrays are not fully supported.

IoT Data Engine (Twin Mapper) will detect that there is a complex array on source path and set it on the destination path without looking inside of it.

⚠️ Source and Destination Path of fields inside the array should be exactly the same in order to ensure the payload compliance with DTDL model. The name of array can be changed.

{
    "complexArray": [
    {
        "deviceID": "entrance1",
        "humidity": 50,
        "temperature": 123.45
    },
    {
        "deviceID": "exit1",
        "humidity": 52,
        "temperature": 54.321
    }]
}

To define in mapping for a complex array, all object fields should be properly defined in the mappping. The field name of array should end with [].

In this case your input JSON should look like:

{
    "complexArray": [
    {
        "deviceID": "entrance1",
        "humidity": 50,
        "temperature": 123.45
    },
    {
        "deviceID": "exit1",
        "humidity": 52,
        "temperature": 54.321
    }]
}

and output will look like:

{
    "CurrentValue": {
        "groupedSensors": [
        {
            "deviceID": "entrance1",
            "humidity": 50,
            "temperature": 123.45
        },
        {
            "deviceID": "exit1",
            "humidity": 52,
            "temperature": 54.321
        }]
    }
}

It is necessary to define all the fields of object inside of an array in order to define correct DTDL model (done by Backoffice-Backend service).

Twin Mapper processing Primitive vs Complex arrays

Twin Mapper when processing a message once it will encounter a mapping with [] it will consider it as an array field:

• if mapping ends with [] - it will process it as a primitive array
• if mapping has [], but doesn't end with it - it will process it as a complex array - currently it will take the whole field from source to destination path without processing its contents.

An incoming message is an array

In case the message coming from IoT Hub will be an array:

[
    {
        "deviceID": "entrance1",
        "humidity": 50,
        "temperature": 123.45
    },
    {
        "deviceID": "exit1",
        "humidity": 52,
        "temperature": 54.321
    }
]

Twin Mapper will automatically detect that it's an array, loop over each element and send it as a separate message to the Azure Digital Twin. In this case the Product Mapping should be set as mapping of object inside of an array.