> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/developer-docs/client-libraries/ilagent/event-mapping.md).

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

## Enriching events

Beyond the core event fields, ilagent can attach **labels**, a **severity**, a **routing key**, and **service references** to events. Each can be set as a static value applied to every event, or mapped from the message payload.

The static flags (`--label`, `--severity`, `--service`) also apply to a plain [HTTP proxy daemon](/developer-docs/client-libraries/ilagent/cli.md#http-proxy) that only receives events via `POST /api/events` — not just MQTT and Kafka consumers.

### Labels

| Flag                            | Description                                                                                | Example                              |
| ------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------ |
| `--label key=value`             | Static label stamped on every event (repeatable)                                           | `--label env=prod`                   |
| `--map_key_label name=jsonpath` | Pull a label value from the payload into a named label (repeatable, supports dot-notation) | `--map_key_label region=data.region` |

Static labels take precedence: if a `--label` and a `--map_key_label` resolve to the same key, the static value wins.

### Severity

| Flag                          | Description                                                                        | Example                         |
| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------- |
| `--severity N`                | Default severity (`1`–`5`), applied only when the event does not already carry one | `--severity 3`                  |
| `--map_key_severity jsonpath` | Extract severity from the payload, as a string or number (supports dot-notation)   | `--map_key_severity data.level` |

Severity values outside the `1`–`5` range are dropped without failing the event.

### Routing key

| Flag                             | Description                                                    | Example                           |
| -------------------------------- | -------------------------------------------------------------- | --------------------------------- |
| `--map_key_routing_key jsonpath` | Extract a routing key from the payload (supports dot-notation) | `--map_key_routing_key data.team` |

### Services

| Flag                   | Description                                 | Example                        |
| ---------------------- | ------------------------------------------- | ------------------------------ |
| `--service alias=NAME` | Attach a service by alias (repeatable)      | `--service alias=web-frontend` |
| `--service id=NUM`     | Attach a service by numeric id (repeatable) | `--service id=123`             |

{% hint style="info" %}
These enrichment flags are consumer / HTTP-daemon features. They are rejected at startup when combined with [edge connector mode](/developer-docs/client-libraries/ilagent/edge-connector.md) (`--edge_mode`), which is an exclusive daemon mode.
{% endhint %}

## 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ilert.com/developer-docs/client-libraries/ilagent/event-mapping.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.