Connect your systems

Field mapping

Translating their field names into yours, and using the mapping as the place where field ownership is enforced.

A mapping says which field in the source becomes which attribute here, and what happens to the value on the way. It is configuration, but it is also where the decisions from system of record stop being a wiki page and start being enforced.

Before you begin. You need a connected system, a sample payload with real data in it, and your field-ownership table. Map from the sample, never from the other system's documentation; documentation describes the fields that exist, the sample shows the ones that are filled.

The one rule

Map only the fields the source owns. Everything you leave unmapped is protected by construction: no run can overwrite what it was never told about.

This is the strongest control you have, and it is free. A source system that happens to send a description column does not get to write descriptions merely because the column is there.

Build the mapping

Go to Data Exchange › Import & Export and open (or create) the profile for this feed. A profile describes a file's or a payload's structure and its mapping to platform fields.
Load the sample payload. The source fields appear with their example values, which is what you map against.
For each field the source owns, choose the target attribute. Match on the attribute code (thread_size) rather than the label ("Gewindegröße").
Set the identifier. This is the field that decides whether a record is created or updated: the SKU for products, the customer number for organisations. Get it right and re-runs converge; get it wrong and re-runs duplicate.

Add a transformation where the value does not arrive in the shape you store it in. The common ones:

Situation	Transformation
`0004711` here, `4711` there	Strip leading zeros, on one side only, consistently
`10,5` from a German ERP	Decimal separator to `.` before it is stored as a number
`10 bar` in one string	Split into value and unit for a measurement attribute
`ST`, `Stk.`, `Stück` all meaning piece	Map to one option code via a value list
`J` / `N`	Map to boolean
`31.12.2026`	Parse to a date with an explicit format
HTML in a description	Strip tags for channels that reject markup

Decide the write behaviour per field: always update, create only, or only if empty here. Use create only for fields where the source is a reasonable starting point without being the owner; an article name is the usual case.
Set the behaviour for missing fields. An absent field and an empty field are not the same thing. An absent field usually means "no information", and should leave the existing value alone. An empty field may genuinely mean "clear this". Choose deliberately, because getting it backwards is how a feed blanks 12,000 descriptions in one run.
Save and run a preview against the sample.

Read the preview before you run anything

The preview shows what each mapped record would look like after the run. Read it for the things that do not throw errors:

Would any owned field be overwritten? Search the preview for your protected fields. If a description appears there, your mapping is wrong regardless of whether it validates.
Do the identifiers match existing records? If the preview shows 12,000 creates on a catalog that already holds 12,000 articles, the identifier format does not match. Stop.
Are units and decimals right? 4.2 kg and 4,2 and 4200 are three different products as far as a shipping calculation is concerned.
Are select values matching options, or arriving as new ones? A mapping that invents a new option for every spelling variant produces a filter with 40 entries that all mean "stainless steel".

What to check after the first real run

Run against a restricted scope first: one product group, or fifty articles. Then check three things by hand:

Open three records in the Cockpit and compare them field by field against the source system on a second screen. The values, rather than the counts.
Check a record that was already here before the run. Did anything change that should not have?
Re-run the same scope unchanged. The result should be zero creates and either zero updates or the same updates again; see the idempotency rules in Integration patterns.

When it does not work

Symptom	Cause	Fix
Unknown attribute	Mapped to a label instead of a code	Use the attribute code
Invalid option	Source value has no matching option	Add the option, or map it in a value list
Everything creates, nothing updates	Identifier format differs, usually leading zeros or a prefix	Normalise the identifier on one side
Numbers a thousand times too large or small	Decimal separator read as a thousands separator	Set the source locale explicitly
Values blank after a run	Absent fields treated as "clear"	Change missing-field behaviour, restore from the previous version
Enriched text keeps reverting	The field is mapped and should not be	Remove it from the mapping

Build a workflow: schedule the mapping and let it run.
Common sync errors: the failures you will see.

Edit this page

Connect a system

Credentials, endpoints and the first handshake, and the checks that stop a connection failing in week three instead of on day one.

Set up a punchout

Create the channel, the assortment and the credentials for one customer's OCI or cXML connection, and test it against their real system.