# Encoder/Decoder Format Conventions and Examples

BuildingPro Suites offers powerful tools like **JSONPath** and **MQTT Wildcards** to dynamically and precisely assign incoming data to the correct assets. While JSONPath allows for flexible selection of values from JSON data, MQTT wildcards enable the use of dynamic values from topic structures. This documentation shows how you can effectively use both methods 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 a 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:**

\[here goes the code]

**JSONPath Queries and Results:**

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

   \[here goes the code]
2. **Query the temperature of all devices**: **JSONPath**: `$.devices[*].wifiSwitchTemp` **Result**:

   \[here goes the code]
3. **Query a device with a specific ID**: **JSONPath**: `$.devices[?(@.id=="A8032A13B850")]` **Result**:

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

\[here goes the code]

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2F7ah3wD056uspgpzMiyCZ%2Fimage.png?alt=media&#x26;token=74d2b880-4efc-48dc-b71b-5c25a22a5b5d" alt=""><figcaption><p>Example for when you want a specific device.</p></figcaption></figure>

***

## Example: Function for generating a GAI/Associated ID when the payload does not contain an identifier

If an incoming payload does not contain a unique identifier or the identifier depends on several 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:

\[here goes the code]

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

### Solution: Create a function

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

**Code example: Generate identifier from multiple fields**

\[here goes the code]

***

#### Configuration in BuildingPro Suites

1. **Create function:**
   * Go to the **"Create function"** option in the menu.
   * Give the function a name, e.g., `parsePayloadCustom`.
   * Insert the code above into the **Code Editor**.
2. **Connect function with a format:**
   * In the "Configure Format" menu, select the corresponding format.
   * Add the function with the **"Append function"** button.
3. **Use identifier:**

   * 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 to be.

   <img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FjiRRXVxt62vfQCkVHTrj%2Fimage.png?alt=media&#x26;token=8852cac4-2196-424e-a4e3-5ea4fc9e3350" alt="" data-size="original">

***

## Using MQTT Wildcards for GAI/Associated ID Creation

### **MQTT Topic Structure in the example:**

\[here goes the code]

### **Wildcards in MQTT**

MQTT supports two wildcard types that can be used in the 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 and below."
   * 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 several `+` wildcards in a topic, you can access them in BuildingPro Suites using numbers (`1`, `2`, etc.). Example: In the topic `building_01/+/+`, it represents:
  * `1`: the first part that was replaced by `+`.
  * `2`: the second part that was replaced by `+`.
* **`#` wildcard:** Captures all values and levels from the position where it stands. Everything that takes the place of `#` in the topic can be referenced directly via `#` in BuildingPro Suites.

***

### **Examples of MQTT wildcard usage**

#### **Example 1: Using `#` to capture rooms**

**Subscription topic:** `building_01/#`

**Received message:** `building_01/floor_01/room_01`

**Configuration in BuildingPro Suites:**

* **Identifier**: `#`

**Result:** The topic `floor_01/room_01` is used as the GAI/Associated ID.

***

### **Example 2: Using `+` to identify a level**

**Subscription topic:** `building_01/+/room_01`

**Received message:** `building_01/floor_02/room_01`

**Configuration in BuildingPro Suites:**

* **Identifier**: `1`

**Result:** The value `floor_02` (the level that was replaced by the first `+`) is used as the GAI/Associated 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 BuildingPro Suites:**

* **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/Associated ID.

***

## **Important Notes**

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

   <figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FRdNeTJgkVp3OyorkKM5J%2Fimage.png?alt=media&#x26;token=9ebdb53d-1f78-424e-b35b-43adfffe1b58" alt=""><figcaption></figcaption></figure>
2. **Automatic processing in BuildingPro Suites:**
   * BuildingPro Suites automatically replaces wildcards with the actual values of the topic.
   * No additional processing is required.
3. **Note the numbering of the `+` wildcards:**
   * Use the corresponding number (`1`, `2`, etc.) to access the specific values.