Event Mapping

Mapping and filtering MQTT or Kafka message payloads to ilert event properties.

When consuming messages from MQTT or Kafka, ilagent can map custom JSON fields in your payloads to ilert event properties. This is useful when your message format does not match the ilert event API directly.

Filtering messages

Only process messages that contain a specific JSON key or key-value pair:

--filter_key 'type' --filter_val 'ALARM'

The example above will only process payloads matching { "type": "ALARM" }. If only --filter_key is set (without --filter_val), any message containing that key will be accepted.

Setting a fixed integration key

When mapping custom events, your payloads may not include an integrationKey field. Use --event_key to set a fixed integration key for every mapped event:

--event_key 'il1api123...'

Mapping required event fields

All mapping flags support dot-notation for nested fields (e.g. data.message to access { "data": { "message": "..." } }).

Flag	Maps to	Example
--map_key_alert_key 'mCode'	alertKey	{ "mCode": "123" } → alertKey: 123
--map_key_alert_key 'data.alertId'	alertKey	{ "data": { "alertId": "abc" } } → alertKey: abc
--map_key_summary 'comment'	summary	{ "comment": "A comment" } → summary: A comment
--map_key_summary 'data.message'	summary	{ "data": { "message": "..." } } → summary: ...
--map_key_etype 'state'	eventType	{ "state": "ACK" } → eventType: ACK

If you are using custom mapping and fail to set the summary for ALERT events, a default summary will be generated using the message topic name.

Mapping eventType values

If your event type values do not match ilert's ALERT, ACCEPT, and RESOLVE, map them:

Flag	Mapping	Example
--map_val_etype_alert 'SET'	SET → ALERT
--map_val_etype_accept 'ACK'	ACK → ACCEPT
--map_val_etype_resolve 'CLR'	CLR → RESOLVE

Forwarding the full message payload

By default, only mapped fields are included in the event. The original message payload is not preserved. Use --forward_message_payload to include the complete original JSON payload as customDetails:

--forward_message_payload

When enabled:

• The full original payload becomes the customDetails of the event

• The original payload is preserved as-is — no metadata is injected

• If the payload already contains an explicit customDetails field, it is preserved as-is

This is useful when you need downstream visibility into the full message while still mapping specific fields to ilert event properties.

Example with nested mapping and forwarded payload

Given this MQTT payload on topic factory/alerts:

{
    "eventType": "alertCreated",
    "source": "monitoringService",
    "data": {
        "alertId": "f9e8d7c6-...",
        "message": "Anomaly detected on pump unit 2",
        "priority": 2
    }
}

With this config:

--event_key 'il1api123...' \
--map_key_etype 'eventType' \
--map_val_etype_alert 'alertCreated' \
--map_key_summary 'data.message' \
--map_key_alert_key 'data.alertId' \
--forward_message_payload

The resulting ilert event will have:

• eventType: ALERT (mapped from alertCreated)

• summary: Anomaly detected on pump unit 2 (from data.message)

• alertKey: f9e8d7c6-... (from data.alertId)

• customDetails: the full original payload as-is

Complete example

ilagent daemon -v -v \
    -m 127.0.0.1 -q 1883 -n ilagent -e '#' \
    --mqtt_username 'my-user' --mqtt_password 'my-pass' \
    --event_key 'il1api112115xxx' \
    --map_key_alert_key 'mCode' \
    --map_key_summary 'comment' \
    --map_key_etype 'state' \
    --map_val_etype_alert 'SET' \
    --map_val_etype_accept 'ACK' \
    --map_val_etype_resolve 'CLR' \
    --filter_key 'type' \
    --filter_val 'ALARM'

Increase log verbosity with multiple -v flags to understand how events are mapped.