> ## Documentation Index
> Fetch the complete documentation index at: https://docs.warrn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Map customer impact

> Link alerts to the customers they affect, using the names or IDs your own systems already send.

When an alert carries a customer name or account ID, Warrn can link it to that customer automatically. Responders see who is affected on the alert and on any incident it becomes, and the customer's page shows every alert and incident that touched them.

Your source only needs to send what it already knows, such as `customer_name: "Acme"` or `customer_id: "0042"`. It never needs a Warrn ID.

## How recognition works

Warrn recognizes customers in two layers:

* **Organization default.** Under **Organization settings → Customers**, choose what happens when an alert carries a standard `customer_name` or `customer_id` field: show it as context only, link it to an existing customer, or link and create the customer when none exists.
* **Team alert rules.** A **Map customers** action on an alert rule gives you full control for a specific source: which field to read, how to match it, and whether to create records. A matching rule takes priority over the organization default, but it cannot create or link records if the organization default forbids it.

Most teams start with the organization default and add a rule only when a source uses its own field names, sends lists of affected customers, or needs an external ID from another system.

Any other `customer_*` field is shown on the alert as reported context. It is not copied to the customer's profile.

## Set up a mapping rule

<Steps>
  <Step title="Add the source's ID to the customer">
    Open **Customers**, pick a customer, and edit the profile. Under **External IDs**, add a **System** and the **External ID** that system uses for this customer, then save.

    For example: system `app/customer`, ID `0042`. Pick one stable system name per source. A customer can hold one ID per system across many systems. Pools have the same fields.

    Skip this step if your rule matches by name or selects a fixed set of customers.
  </Step>

  <Step title="Add a Map customers action">
    Open the team's **On-Call** tab, expand **Alert Rules**, and add or edit a rule. Set its integration scope and conditions, then add **Map customers** (or **Map customer pools**) under actions.

    Set **Match by** to **External ID**, **System** to `app/customer`, and **Expression** to `metadata.customer_id`. Optionally set a **Default impact** (Affected, Degraded, or Outage) for the links this rule creates.

    Expressions are JMESPath, evaluated against the normalized alert you see in the rule tester, including its `metadata`.
  </Step>

  <Step title="Preview, then save">
    Open **Test this rule** and paste a sample alert:

    ```json theme={null}
    {
      "name": "Replication delayed",
      "severity": "high",
      "metadata": {
        "customer_id": "0042",
        "customer_name": "Acme"
      }
    }
    ```

    The customer impact result tells you which customer would be linked, which would be created, or why nothing would happen. Previewing never creates or links anything.

    Save the rule. To see it alongside the team's other rules, paging, and notifications, use **Simulate alert routing** on the On-Call tab.
  </Step>
</Steps>

## Ways to match

| Match by            | What the expression should return                                                   | How it matches                                    |
| ------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Name**            | A name, or a list of names                                                          | Exact match, ignoring case and surrounding spaces |
| **External ID**     | An ID, or a list of IDs                                                             | Exact match within the selected system            |
| **Existing record** | A Warrn ID, or a list of them. Or leave it empty and select the customers directly. | Links exactly those customers                     |

Use **Existing record** when a source always belongs to the same customers, such as a dedicated single-tenant deployment. Use an expression like `metadata.affected_customers[].id` when the source sends a list.

Matching never crosses organizations and never guesses. If a name matches more than one customer, or a new external ID arrives with a name that already exists, Warrn reports the match as ambiguous and leaves it for you to resolve rather than linking the wrong record.

## Create customers automatically

Turn on **Create if missing** on a mapping action when the source sends reliable names and IDs. It is off by default.

* Matching by **Name** creates the customer with that name.
* Matching by **External ID** also needs a **Display name** expression, such as `metadata.customer_name`, so the new customer is not named after its ID. If both are lists, they must line up one to one.

Later alerts for the same customer reuse the record. Existing links, impact levels, and notes on an alert are never overwritten by a rule.

<Warning>
  If an external ID is new but its display name already belongs to another customer, Warrn does not create a duplicate and does not assume they are the same. Add the ID to the existing customer's profile and the next alert will link cleanly.
</Warning>

Mapping a pool links the pool to the alert. It does not add customers to the pool or link them individually.

## Use IDs from several systems

A customer can carry IDs from every system that refers to them:

| System         | Example            | Use                                                          |
| -------------- | ------------------ | ------------------------------------------------------------ |
| `app/customer` | `0042`             | Your own account or tenant ID                                |
| `hubspot`      | `123456`           | The ID Warrn's HubSpot import already uses                   |
| `zendesk`      | `ops@acme.example` | The requester email Warrn's Zendesk correlation already uses |
| `zendesk/org`  | `98765`            | Any additional ID you want rules to match on                 |

Adding an ID only makes it matchable. It does not connect an integration or start a sync. When a HubSpot or Zendesk integration later resolves the same ID, it reuses the customer instead of creating a second one.

IDs are stored as text, so `42` and `"42"` match but `"0042"` does not. Send IDs as strings to keep leading zeros and large numbers intact. System names and IDs are case-sensitive.

## When a mapping does not link

The preview and the alert's **Customer Impact Mapping** timeline event report one of these outcomes:

| Outcome       | Meaning                                                                       | What to check                                                                                   |
| ------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Missing**   | No customer matched and creation is off                                       | The expression, the system name, and the ID on the customer's profile                           |
| **Ambiguous** | More than one customer could match                                            | Match by external ID or existing record instead of name, or add the ID to the intended customer |
| **Invalid**   | The expression returned something unusable                                    | The expression path and value type. External ID creation also needs a display name.             |
| **Skipped**   | The alert was suppressed, or customer impact is disabled for the organization | Rule order and the organization default                                                         |
| **Error**     | Mapping failed                                                                | The timeline event details. The alert is still delivered and paged normally.                    |

Only the first matching rule runs. Customer mapping happens before notifications and paging, so a **Do not page anyone** rule still maps customers, and a suppressed alert maps none. To combine mapping with routing to Slack or a webhook, see [Route alerts without paging](/components/alerts/router).

## Suggestions and imports

When Warrn is confident an alert or imported incident mentions a customer but cannot link it safely, it shows a suggestion in the customer section. Approve it, pick a different customer, create a new one, or dismiss it. Choose **Remember this name for this source** so the same name from that source links automatically next time.

Imported Jira alerts go through the same recognition as live alerts, using the first matching rule's customer mapping only. Imported Slack incidents can suggest customers when import enrichment is on, and always ask before linking an uncertain match.