Topic Message Overrides

MAPS converts messages from every supported protocol into a common internal message model. Topic message overrides let an operator enforce selected properties at the destination boundary, regardless of the protocol used to publish the message.

Typical uses include:

• applying a short expiry to telemetry while retaining longer-lived command messages;
• enforcing a delivery quality for a namespace;
• setting retain or offline-delivery behaviour;
• attaching default metadata used by filtering, routing, or transformation;
• assigning a content type or schema when the publisher cannot provide one.

Overrides apply consistently to direct publishes, MQTT QoS 1 and QoS 2 publishes, and explicit transactions.

Processing order

A message is processed in this order:

1. The publishing protocol creates the internal message.
2. Optional protocol-level messageDefaults are applied.
3. Matching destination-level messageOverrides are resolved.
4. The resulting message is stored and delivered.

Configured scalar fields replace the value already present on the message. Metadata and data-map entries are defaults: they are added only when the message does not already contain the key.

Destination matching

Destination overrides are configured in DestinationManager.yaml. The root mapping / matches every destination. More-specific namespace mappings match the exact destination and child paths.

For example, /fleet/drone matches:

• /fleet/drone
• /fleet/drone/status

It does not match /fleet/droneBackup.

All matching override blocks are combined from the least-specific namespace to the most-specific namespace. A more-specific scalar value replaces its parent value. Metadata and data maps are merged, with the more-specific configuration winning when both configurations define the same key.

Configuration example

DestinationManager:
  data:
    - name: root
      directory: "{{MAPS_DATA}}/destinations"
      namespace: /
      type: Partition
      itemCount: 1000
      maxPartitionSize: 1G
      messageOverrides:
        expiry: 300000
        meta:
          deployment: edge

    - name: drone-telemetry
      directory: "{{MAPS_DATA}}/drone-telemetry"
      namespace: /fleet/drone/telemetry
      type: Partition
      itemCount: 1000
      maxPartitionSize: 256M
      messageOverrides:
        expiry: 30000
        qos: AT_LEAST_ONCE
        storeOffline: true
        contentType: application/json
        meta:
          dataClass: telemetry

Messages published to /fleet/drone/telemetry/position receive the root metadata and the more-specific telemetry settings. Their expiry is 30 seconds rather than the root value of 5 minutes.

A destination mapping also selects the backing-store configuration, so each additional namespace entry must contain the required storage settings.

Supported properties

YAML property	REST field	Meaning
expiry	expiry	Time-to-live in milliseconds. 0 means no expiry. For delayed messages, expiry begins after the delay.
priority	priority	Internal priority from LOWEST through HIGHEST.
qos	qualityOfService	AT_MOST_ONCE, AT_LEAST_ONCE, or EXACTLY_ONCE.
responseTopic	responseTopic	Default response or reply topic.
contentType	contentType	MIME content type, such as application/json.
schemaId	schemaId	Schema identifier associated with the message.
retain	retain	Whether the message is retained on the destination.
storeOffline	storeOffline	Whether hibernating or offline subscriptions retain access to the message.
meta	meta	String metadata added for keys not already supplied by the message.
dataMap	dataMap	Typed values added for keys not already supplied by the message.

Every property is optional. Omitting a scalar property leaves the current message value unchanged.

Precedence example

Given these values:

# Protocol-level defaults
messageDefaults:
  expiry: 120000
  qos: AT_MOST_ONCE

# Destination-level override
messageOverrides:
  expiry: 10000

the stored message has a 10-second expiry and retains AT_MOST_ONCE quality of service. The destination changes only the property it declares.

Operational notes

• Use milliseconds for expiry; protocol wire formats may express expiry in other units.
• Configuration enum values are case-sensitive.
• Use messageOverrides in YAML. The REST representation uses the singular field name messageOverride for each destination configuration.
• Restart the server after changing an override for an existing destination. Overrides are resolved when destinations are created or reloaded.
• Existing stored messages are not rewritten. Changes affect only newly published messages.