# Event Mapping

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:

```sh
--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:

```sh
--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`              |

{% hint style="info" %}
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.
{% endhint %}

## 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`:

```sh
--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`:

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

With this config:

```sh
--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

```sh
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'
```

{% hint style="info" %}
Increase log verbosity with multiple `-v` flags to understand how events are mapped.
{% endhint %}