Format conventions and examples

Eliona offers powerful tools such as JSONPath and MQTT wildcardsto dynamically and precisely assign incoming data to the correct assets. While JSONPath enables flexible selection of values from JSON data, MQTT wildcards allow the use of dynamic values from topic structures. This documentation shows how you can use both methods effectively to optimize your data processing.

JSONPath convention

JSONPath is a syntax for selecting and processing values in a JSON document. The basic structure and symbols of JSONPath:

1. $: The root node of the JSON document.

2. .: Access to a child element.

3. []: Enables access to an element by index or condition.

4. ?(): Filter expression to select elements based on a condition.

5. @: Represents the current element in the filter expression.

6. *: Wildcard to select all elements of an array or object.

7. ..: Recursive access to find all instances of a specific name in the hierarchy.

---

Example 1: Simple query from a JSON payload

JSON data:

{
    "devices": [
        {
            "id": "A8032A13B850",
            "name": "WiFi Switch 4",
            "type": "ws2",
            "wifiSwitchTemp": 23.75
        },
        {
            "id": "F008D1C4B034",
            "name": "WiFi Switch 3",
            "type": "ws2",
            "wifiSwitchTemp": 23.93
        }
    ]
}

JSONPath queries and results:

1. Query all device data: JSONPath: $.devices[*] Result:

   [
       {
           "id": "A8032A13B850",
           "name": "WiFi Switch 4",
           "type": "ws2",
           "wifiSwitchTemp": 23.75
       },
       {
           "id": "F008D1C4B034",
           "name": "WiFi Switch 3",
           "type": "ws2",
           "wifiSwitchTemp": 23.93
       }
   ]

2. Query the temperature of all devices: JSONPath: $.devices[*].wifiSwitchTemp Result:

   [23.75, 23.93]

3. Query a device with a specific ID: JSONPath: $.devices[?(@.id=="A8032A13B850")] Result:

   [
       {
           "id": "A8032A13B850",
           "name": "WiFi Switch 4",
           "type": "ws2",
           "wifiSwitchTemp": 23.75
       }
   ]

4. Query only the temperature of a specific device: JSONPath: $.devices[?(@.id=="A8032A13B850")].wifiSwitchTemp Result:

[23.75]

Example for when you want a specific device.

---

Example: Function to generate a GAI/related ID when the payload does not contain an identifier

If an incoming payload does not contain a unique identifier, or if the identifier depends on multiple elements in the payload, a custom function can be used to generate the identifier.

Scenario: No identifier in the payload

Let’s imagine the following example for a payload:

{
    "device": {
        "name": "WiFi Switch",
        "type": "ws2",
        "status": "active",
        "location": {
            "building": "Building_01",
            "floor": "Floor_02",
            "room": "Room_01"
        }
    }
}

In this example, the payload does not contain a direct identifier because there may be multiple WiFi switches, but the combination of Buildings, floor and room can be used to create a unique identifier.

Solution: Create a function

Use a custom function in Eliona to generate the identifier from the components of the payload.

Code example: Generate identifier from multiple fields

javascriptCode copyfunction parsePayloadCustom(json, context) {
    const input = JSON.parse(json);

    // Initialize object structure
    let obj = {
        "eliona": {
            "uin": null // The identifier is stored here
        }
    };

    // Check whether the required data is available
    if (
        input.device &&
        input.device.location &&
        input.device.location.building &&
        input.device.location.floor &&
        input.device.location.room
    ) {
        // Generate identifier from the fields in the payload
        obj.eliona.uin = `${input.device.location.building}_${input.device.location.floor}_${input.device.location.room}`;
    } else {
        // Fallback: set default value if fields are missing
        obj.eliona.uin = null;
    }

    return obj;
}

---

Configuration in Eliona

1. Create function:

   • Go to the option "Create function" in the menu.

   • Give the function a name, e.g. parsePayloadCustom.

   • Add the above code in the Code editor it.

2. Connect function with a format:

   • In the "Configure format" menu, select the appropriate format.

   • Add the function using the button "Attach function" add.

3. Identifier use:

   • The format uses the generated identifier (eliona.uin) to assign incoming data to the correct asset. For this, either Externally for the related ID or GAI can be selected depending on where you want the ID to be.

   

---

Using MQTT wildcards for GAI/related ID creation

MQTT topic structure in the example:

Unexpected error with integration mermaid: Integration is not installed on this space

Wildcards in MQTT

MQTT supports two wildcard types that can be used in topics:

1. + (single-level wildcard)

   • Represents "all values at this topic level".

   • Example: The topic building_01/+/room_01 matches the following topics:

     • building_01/floor_01/room_01

     • building_01/floor_02/room_01

2. # (multi-level wildcard)

   • Represents "all values from this level downward".

   • Can only be used at the end of a topic.

   • Example: The topic building_01/# matches the following topics:

     • building_01/floor_01

     • building_01/floor_01/room_01

     • building_01/floor_02/room_02

---

How MQTT wildcards work

• +-wildcard: Each +-wildcard replaces exactly one part of the topic. If there are multiple +-wildcards in a topic, you can access them in Eliona using numbers (1, 2, etc.). Example: In the topic building_01/+/+, represents:

  • 1: the first part replaced by + .

  • 2: the second part replaced by + .

• #-wildcard: Captures all values and levels from the position where it stands. Everything in the topic that takes the place of # can be referenced directly in Eliona via # .

---

Examples of using MQTT wildcards

Example 1: Using # to capture rooms

Subscription topic: building_01/#

Received message: building_01/floor_01/room_01

Configuration in Eliona:

• Identifier: #

Result: The topic floor_01/room_01 is used as the GAI/related ID.

---

Example 2: Using + to identify a level

Subscription topic: building_01/+/room_01

Received message: building_01/floor_02/room_01

Configuration in Eliona:

• Identifier: 1

Result: The value floor_02 (the level replaced by the first + ) is used as the GAI/related ID.

---

Example 3: Combination of + and # to capture multiple levels

Subscription topic: building_01/+/+/#

Received message: building_01/floor_01/room_02/sensor_01

Configuration in Eliona:

• Identifier:

  • 1 → floor_01 (first +-wildcard)

  • 2 → room_02 (second +-wildcard)

  • # → sensor_01 (all values that replace # )

Result: The values floor_01, room_02 and sensor_01 can be used individually as the GAI/related ID.

---

Important notes

1. MQTT wildcards only work with topic mode: In identification, select "Topic" as shown in the following image:

   
2. Automatic processing in Eliona:

   • Eliona automatically replaces wildcards with the actual values of the topic.

   • No additional processing is required.

3. Numbering of the +-wildcards note:

   • Use the corresponding number (1, 2, etc.) to access the specific values.