inferrex-map-systems · Get SKILL.md

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

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.
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.
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.
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.
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.
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.
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.
Approve when the user says so. Call mappings_approve_mapping.
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.