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

# Entity mappings

> Link Chatbot conversations to business entities using deterministic mappings from signed host claims or successful approved API/MCP source outputs.

Use **Topics → Entity mappings** to connect a conversation to durable business entities such as orders, accounts, subscriptions, shipments, or other external records.

Entity mapping is deliberately deterministic.

> [!WARNING]
>
> The AI classifier cannot invent an external entity link.

A link can be created only from supported trusted inputs such as:

* a **signed host claim**; or
* a successful **approved SOURCE output** from API/MCP retrieval.

## Mapping sources

The current editor supports source kinds including:

* API tool;
* MCP source; and
* Signed host claim.

For API/MCP mappings, identify the approved source/tool whose successful output contains the entity data.

For a host-claim mapping, the value must come from a claim your host-signed visitor identity configuration allows RAUM to receive.

## Entity type

Define a stable lower-case business entity type such as:

* order
* subscription
* account
* shipment

Use a type meaningful across conversations rather than a UI label likely to change next month.

## JSON pointers

A mapping can define structured pointers for:

* items/collection location;
* external entity ID;
* display label;
* HTTPS URL; and
* allowlisted attributes.

Attribute pointers are configured as a JSON object mapping approved attribute names to RFC 6901 pointers.

Only explicitly mapped attributes are persisted as entity attribution data.

## Why deterministic attribution matters

Topics classification answers **what the conversation is about**.

Entity mapping answers **which external record the trusted data actually identified**.

Those should not be conflated. A visitor mentioning “order 123” in prose does not grant the model authority to assert that order 123 belongs to them.

## Host-signed claims

When your website provides a verified host identity, RAUM can map allowlisted signed claims to an external entity.

This is useful when the visitor is already authenticated on your site and your server knows their account/customer identifiers.

[Visitor identity →](https://docs.raum.am/chatbot/visitor-identity.md)

## Approved source outputs

A public SOURCE tool can return customer-safe bounded data after its widget, identity, input, output, and Shared Knowledge policies pass.

Entity mapping can extract a deterministic entity from that successful result.

[Public connections →](https://docs.raum.am/chatbot/public-connections.md)

## Activate/deactivate

Mappings can be deactivated when they should stop creating new links.

Historical entity attribution remains part of the retained conversation record according to retention policy; deactivation does not rewrite history.

## Use in analytics

Conversation administration can filter by external entity, and Chatbot Analytics can report entity-attribution dimensions when enabled.

This gives you a route from an aggregate support topic back to the actual business object involved without teaching the classifier to hallucinate database joins.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.