---
name: inferrex-map-systems
description: Match two connected systems in Inferrex, review the proposed field-to-field links with the user, record their decisions and approve the mapping. Use when the user asks to map, match or line up the data of two systems, or to review or change an existing mapping.
---

# Map two systems in Inferrex

A mapping says which objects in one system correspond to objects in another, and which fields feed which. Every edit saves a new version. A flow keeps the version it was turned on with until you move it.

## When to use

- "Map our order system to finance."
- "Show me which fields are not mapped yet."
- "Approve the customer links and leave out the notes field."

To turn the mapping into something that runs, use `inferrex-build-flow` afterwards.

## Prerequisites

- **InferrexMCP** at `https://mcp.inferrex.com/mcp` (sign-in or API key in a header), or **InferrexAPI** at `https://api.inferrex.com` with `X-API-Key: $INFERREX_API_KEY`.
- Key scopes: `connections:read`, `connections:write`, `mappings:read`, `mappings:write`, `jobs:read`.
- Both systems are connected and approved. Check with `connection_list`: each must have `status` `approved` or `active`. If one is `awaiting-review`, use `inferrex-connect-system` first.

## Steps

1. **Find the two systems.** Call `connection_list`. Match the user's names to `display_name` and keep each `id`. If a name matches more than one system, ask which. Two accounts with the same vendor are two different systems.
2. **Look for an existing mapping.** Call `mappings_list`. If one already joins these two systems, ask whether to review that one. Do not make a second.
3. **Match.** Call `connections_match` with `id` (the source system) and `targetConnectionId`.
   - If the answer has a `mappingId`, use it.
   - If it has only a `jobId`, call `jobs_get_job` until `status` is `succeeded`, then read `result.mappingId`. If `status` is `failed`, report `error` and stop.
4. **Read the mapping.** Call `mappings_get_mapping`. For each pair of objects, group the field links into:
   - approved (`customerApproved` true),
   - rejected (`customerRejected` true),
   - left out (`omitted` true),
   - still to decide (none of the above), lowest `confidence` first.
5. **Find what is not linked.** Call `mappings_list_mappable_fields`. List required target fields that no link uses. A flow cannot write a record that lacks a required field.
6. **Show real data.** For any link the user is unsure of, call `mappings_fetch_mapping_sample` with `side` and `entity` to show one real record. Do not paste sensitive values back unless the user asks.
7. **Record the user's decisions.**
   - One link: `mappings_update_field_mapping` with `fieldMappingId` and `approved: true`, `approved: false` or `omitted: true`.
   - Many links: `mappings_bulk_update_field` with `fieldMappingIds` and `action`: `approve`, `reject`, `omit`, `restore` or `amend`.
   - A link Inferrex did not suggest: `mappings_create_field_mapping`.
   - The fields that identify the same record in the target, such as an email address or invoice number: `mappings_set_entity_match` with `targetEntityId` and `matchOn`. Ask the user for these. Without them a sync can create duplicates.
8. **Approve when the user says so.** Call `mappings_approve_mapping`.
9. **Check running flows.** Call `mappings_list_mapping_pipelines`. For each flow where `upToDate` is false, tell the user it still runs the older version. Moving it is a separate decision (`pipelines_apply_mapping_to_pipeline`, in `inferrex-build-flow`).

## Checks before any write

- Show the user the list from step 4 before any approve, reject or leave-out call.
- **Reject** means the link is wrong. **Leave out** means do not sync this field. Confirm which the user means.
- Before a bulk action, state how many links it touches and name the action. A bulk action is one version, so it can be undone in one step with `mappings_revert_mapping`.
- Never approve links only because their `confidence` is high. The user decides.

## Equivalents

| Step | InferrexMCP tool | InferrexAPI |
|---|---|---|
| List systems | `connection_list` | `GET /v1/connections` |
| List mappings | `mappings_list` | `GET /v1/mappings` |
| Match | `connections_match` | `POST /v1/connections/:id/match` |
| Job | `jobs_get_job` | `GET /v1/jobs/:id` |
| Read mapping | `mappings_get_mapping` | `GET /v1/mappings/:id` |
| Fields in both systems | `mappings_list_mappable_fields` | `GET /v1/mappings/:id/fields` |
| One real record | `mappings_fetch_mapping_sample` | `GET /v1/mappings/:id/sample` |
| Change one link | `mappings_update_field_mapping` | `PATCH /v1/mappings/:id/field-mapping` |
| Change many links | `mappings_bulk_update_field` | `PATCH /v1/mappings/:id/field-mappings` |
| Add a link | `mappings_create_field_mapping` | `POST /v1/mappings/:id/field-mapping` |
| Identify the same record | `mappings_set_entity_match` | `PATCH /v1/mappings/:id/entity-match` |
| Approve | `mappings_approve_mapping` | `POST /v1/mappings/:id/approve` |
| Versions | `mappings_list_mapping_versions` | `GET /v1/mappings/:id/versions` |
| Compare versions | `mappings_compare_mapping_versions` | `GET /v1/mappings/:id/compare` |
| Revert | `mappings_revert_mapping` | `POST /v1/mappings/:id/revert` |
| Flows using it | `mappings_list_mapping_pipelines` | `GET /v1/mappings/:id/pipelines` |

## Report back

- The mapping's id and the two systems it joins.
- How many links are approved, rejected, left out and still to decide.
- Required target fields with no link.
- Whether the entity match is set, and on which fields.
- Flows still running an older version.

## Never

- Never approve a mapping the user has not reviewed.
- Never treat reject and leave out as the same thing.
- Never create a second mapping between two systems that already have one without asking.
- Never move a running flow to a new mapping version as a side effect of editing the mapping.
- Never archive a mapping (`mappings_archive_mapping`) unless the user asks for exactly that.