> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/english-v14/connectivity-as-a-service/gerate-mit-abb-buildingpro-verbinden/ein-format-konfigurieren/format-konventionen-und-beispiele.md). # Format conventions and examples Eliona offers powerful tools such as **JSONPath** and **MQTT wildcards**, to 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. **`[]`**: Allows access to an element by index or condition. 4. **`?()`**: Filter expression to select elements by 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:** ```json { "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**: ```json [ { "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**: ```json [23.75, 23.93] ``` 3. **Query a device with a specific ID**:\ **JSONPath**: `$.devices[?(@.id=="A8032A13B850")]`\ **Result**: ```json [ { "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**: ```json [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 payload: ```json { "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 several WiFi switches, but the combination of **Buildings**, **floor** and **room** can be used to create a unique identifier. ### Solution: Create function Use a custom function in Eliona to generate the identifier from the components of the payload. **Code example: identifier** **generated from multiple fields** ```javascript javascriptCode copy function 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 present 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`. * Insert the above code in the **Code editor** in. 2. **Connect the function to a format:** * Select the corresponding format in the "Configure format" menu. * Add the function with the button **"Attach function"** to your rating in 3. Identifier **use:** * The format uses the generated identifier (`eliona.uin`), to map incoming data to the correct asset. For this, either **External for the associated ID or GAI** can be selected depending on where you want the ID. *** ## Using MQTT wildcards to create a GAI/related ID ### **MQTT topic structure in the example:** {% @mermaid/diagram content="graph TD A(building\_01) --> B(building\_01/floor\_01) A --> C(building\_01/floor\_02) B --> D(building\_01/floor\_01/room\_01) B --> E(building\_01/floor\_01/room\_02) C --> F(building\_01/floor\_02/room\_01) C --> G(building\_01/floor\_02/room\_02) " %} ### **MQTT wildcards** MQTT supports two wildcard types that can be used in topics: 1. **`+` (single-level wildcard)** * Represents "all values at this topic level". * Example:\nThe 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 and below". * Can **only be used at the end** of a topic. * Example:\nThe 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 by numbers (`1`, `2`, etc.)\nExample: In the topic `building_01/+/+`, represents: * `1`: the first part replaced by `+` it. * `2`: the second part replaced by `+` it. * **`#`-wildcard:**\ Captures all values and levels from the position where it stands. Anything 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 GAI/related ID. *** ## **Important notes** 1. **MQTT wildcards only work with the topic mode:**\ Select **"Topic"** in identification, 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. **Pay attention to the numbering of `+`-wildcards:** * Use the corresponding number (`1`, `2`, etc.) to access the specific values. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.buildings.ability.abb/collection/english-v14/connectivity-as-a-service/gerate-mit-abb-buildingpro-verbinden/ein-format-konfigurieren/format-konventionen-und-beispiele.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.