Transformations

MAPS Transformations allow you to modify, enrich, or convert event payloads inline as they move through the system.

---

Capabilities

• Field mapping – rename, extract, or drop fields.
• Unit conversion – e.g., Fahrenheit → Celsius.
• Enrichment – add metadata such as serverId, geo tags, or custom attributes.
• Format conversion – JSON ↔ Avro ↔ Protobuf ↔ CSV (schema-driven).
• Protocol message conversion – encode/decode full events into different wire representations.

---

Schema Awareness

• With a schema, MAPS applies type-aware transforms (numeric conversions, field extraction, validation).
• Without a schema, only opaque, byte-level transformations are possible.

---

Transformation Flow

---

Built-in Transformations

Transformation	Description
JSONToXML	Converts JSON payloads into XML documents.
XMLToJSON	Converts XML payloads into JSON.
JsonToValue	Extracts a specific value from a JSON object by key.

---

Example: Schema-Aware Unit Conversion

transformations:
  - field: temperatureF
    convertTo: temperatureC
    function: fahrenheitToCelsius

---

Example: Topic/Protocol-Scoped Transformations

transformations:
  data:
    - pattern: "*://*/*/*"
      transformation: ""

    - pattern: "*://*/mqtt/thermometer"
      transformation: JsonToValue
      key: temperature
      
    - pattern: "*://*/mqtt/xml_source"
      transformation: XMLtoJSON

    - pattern: "*://*/mqtt/xml_sink"
      transformation: JSONToXML

These rules apply per topic/protocol/host pattern, allowing localized transformations.

---

Protocol Message Transformations

At the event ingress/egress boundary, transformations can be applied to entire protocol messages:

Transformation	Description
none	No transformation applied.
JMSProtocol	Converts events into Apache AMQP JMS-style messages.
JsonMessage	Encodes the full MAPS event as JSON (including headers, payload, metadata).
BinaryMessage	Encodes the event into a binary representation (efficient transfer).
SchemaToJson	Used for server↔server schema exchange and replication.
CloudEvent-Json	Converts events to CloudEvent format and, if schema known, converts the data to a json object.
CloudEvent-Native	Converts events to CloudEvent format and if a JSON object packs accordingly or uses a BASE64 encoding.
CloudEvent-Envelope	Converts events to CloudEvent format envoloping the entire message in a BASE64 encoding

---

Protocol Transformations — Where and How They’re Used

Protocol transformations in MAPS Messaging are pluggable components operating at the connection layer.
They define how events are converted when entering or leaving the internal message engine, enabling seamless interoperability between MAPS servers and external systems (MQTT, AMQP, STOMP, CoAP, etc.).

---

Inbound Transformation

When a client or another MAPS server publishes to the system, the configured inbound transformer is applied before the event is injected into the engine.

• The transformer decodes the incoming payload into a fully structured MAPS message object
  (headers, metadata, payload, route info, timestamps, etc.).
• Once inside the engine, all events share a common internal format, independent of the incoming protocol or encoding.

Example:

• A remote MAPS node sends a BinaryMessage payload via MQTT.
• The local MAPS server’s connection applies the BinaryMessage transformer.
• The payload is unpacked and converted into a native MAPS message before routing.

---

Outbound Transformation

When messages are delivered to subscribers or external brokers, the outbound transformer performs the reverse operation:

• The internal MAPS message is serialized into the target format (binary, JSON, CloudEvent, JMS, etc.) before transmission.
• This enables flexible bridging — e.g., MAPS→MAPS using BinaryMessage or JsonMessage,
  or MAPS→External using CloudEvent or JMSProtocol.

---

Typical Use Cases

Scenario	Purpose
Server-to-Server Links	Use BinaryMessage or JsonMessage to preserve full fidelity (headers, timestamps, route).
External Broker Integration	Apply CloudEvent or JMSProtocol to align with external message formats.
Schema Synchronization	Use SchemaToJson when replicating schemas between servers.
Protocol Translation Gateways	Configure inbound/outbound transformers per connection for bridging (e.g., MQTT ↔ AMQP, STOMP ↔ MAPS).

---

Flow Summary

Flow Explanation

1. Inbound: Raw protocol message → Transformer decodes → Internal MAPS event
2. Processing: Message routed internally with consistent structure
3. Outbound: MAPS event → Transformer encodes → Protocol-specific payload

---

Key Benefits

• Unified event model across all protocols
• Seamless bridging between heterogeneous messaging systems
• Full route tracking for chained MAPS servers
• Optional lossless or compact encodings depending on use case