Mappings#

The Mappings section defines reusable lookup tables that translate raw input values (typically coming from MQTT payloads or topics) into human‑readable or semantically meaningful values. Mappings are primarily used inside expressions through the Map(from, name) function.

Mappings allow you to:

convert numeric IDs into descriptive labels
normalize inconsistent device identifiers
enrich OpenTelemetry attributes with meaningful values
avoid hard‑coding lookup logic inside processors

Structure#

A Mappings block contains one or more named mapping tables, consisting of the following fields:

Parameter	Description
Name	The name of the mapping table. Used when calling Map().
Entries	A list of key/value pairs. Each entry defines one mapping rule.
Entries[].From	The raw value to match (e.g., device ID, payload field).
Entries[].To	The translated value returned by Map().

How Mapping Works#

Mappings are accessed through the Map(from, mappingName) function inside expressions.

The function searches the mapping table with the given mappingName. If mappingName is not found, the original value is returned.
It compares the from value with each Entries[].From. If no matching From value is found, the original value is returned.

If a match is found, the corresponding Entries[].To value is returned.

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Mappings:
  - Name: "IdToName"
    Entries: 
      - From: "1234"
        To: "sensor one"
      - From: "4321"
        To: "sensor two"


Processors:
  - Name: "Processor Temperature"
    Description: "Reads the sensor id from the topic and converts it into a human readable form using mappings."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/raw"
    Otel:
      Metrics:
        - Name: "Processor.Temperature"
          Description: "The current processor temperature."
          Instrument: Gauge
          Attributes:
            - Key: "Sensor name"
              Value: "$(Map(TopicPath('[1]'), 'IdToName'))"
          Value: "PAYLOAD()"