Field Mapping¶

Field mapping defines how data is translated between a connector's native format and the Canonical Data Model (CDM). Good mappings are the foundation of reliable integrations.

How Field Mapping Works¶

Every connector in DIBOP has a set of field mappings that translate between the external system's field names and the CDM's standardised fields.

Inbound Mapping (System to CDM)¶

When data arrives from an external system, the inbound mapping translates native field names to CDM fields:

Mercedes-Benz OneAPI          CDM (Vehicle)
────────────────────          ─────────────
fin                    →      vin
marke                  →      make
modell                 →      model
erstzulassung          →      first_registration_date
kilometerstand         →      mileage_km

Outbound Mapping (CDM to System)¶

When DIBOP sends data to an external system, the outbound mapping translates CDM fields to the system's native format:

CDM (Vehicle)                 DMS
─────────────                 ───
vin                    →      stock_vin
make                   →      veh_make
model                  →      veh_model
year                   →      model_year
mileage_km             →      odometer_reading

Bidirectional¶

Many mappings are bidirectional -- the same pair of fields is used for both inbound and outbound. DIBOP manages the direction automatically based on whether data is being read from or written to the system.

AI-Assisted Mapping¶

DIBOP's AI can analyse a sample API response and suggest CDM mappings automatically.

How to Use AI Mapping¶

Navigate to the connector's Field Mapping configuration
Click AI Assist
Paste a sample JSON response from the external system:

{
  "fahrzeug_id": "WDB1234567890",
  "marke": "Mercedes-Benz",
  "modell": "C-Class",
  "baujahr": 2024,
  "kilometerstand": 15000,
  "kraftstoffart": "Diesel",
  "farbe_aussen": "Obsidian Black",
  "preis": 45000.00
}

Click Analyse
The AI suggests mappings:

Source Field	Suggested CDM Field	Confidence	Status
`fahrzeug_id`	`vin`	High	Assumed
`marke`	`make`	High	Assumed
`modell`	`model`	High	Assumed
`baujahr`	`year`	High	Assumed
`kilometerstand`	`mileage_km`	High	Assumed
`kraftstoffart`	`fuel_type`	Medium	Assumed
`farbe_aussen`	`exterior_colour`	Medium	Assumed
`preis`	`list_price`	Medium	Assumed

Review each suggestion and click Verify to confirm, or Edit to correct

Mapping Confidence¶

The AI assigns a confidence level to each suggestion:

Confidence	Meaning
High	The field name or content strongly suggests the mapping (e.g., a 17-character string is almost certainly a VIN)
Medium	The mapping is likely but could be wrong (e.g., "preis" could be list price or sale price)
Low	The AI is guessing; manual review is recommended

Verified vs Assumed Mappings¶

Each mapping has a verification status:

Status	Meaning	Visual Indicator
Verified	A human has confirmed this mapping is correct	Green checkmark
Assumed	The mapping was suggested by AI and not yet confirmed	Amber question mark
Unmapped	The field has no mapping to the CDM	Grey dash

Verify Before Production

Assumed mappings are likely correct but should be verified before using them in production orchestrations. An incorrect mapping could send data to the wrong field in a target system.

Manual Mapping¶

You can also configure mappings manually:

Navigate to the connector's Field Mapping configuration
Click Add Mapping
Select the source field (from the connector's schema)
Select the target CDM field (from the CDM domain)
Optionally configure a transformation:
- Direct: The value is copied as-is
- Type Cast: Convert between types (e.g., string to number)
- Format: Apply a format transformation (e.g., date format conversion)
- Lookup: Map values using a lookup table (e.g., "DE" to "Germany")
Click Save

Transformation Functions¶

Some mappings require more than a simple field rename. DIBOP supports transformation functions:

Type Conversions¶

Function	Description	Example
`to_string`	Convert to string	`12345` to `"12345"`
`to_number`	Convert to number	`"45000.00"` to `45000.00`
`to_integer`	Convert to integer	`"2024"` to `2024`
`to_boolean`	Convert to boolean	`"true"` to `true`
`to_datetime`	Parse a date string	`"2024-01-15"` to DateTime

String Functions¶

Function	Description	Example
`uppercase`	Convert to uppercase	`"mercedes"` to `"MERCEDES"`
`lowercase`	Convert to lowercase	`"MERCEDES"` to `"mercedes"`
`trim`	Remove leading/trailing whitespace	`" Mercedes "` to `"Mercedes"`
`concat`	Concatenate fields	`first + " " + last` to `"Jane Smith"`
`substring`	Extract part of a string	`"WDB1234567890"[0:3]` to `"WDB"`

Date Functions¶

Function	Description	Example
`parse_date`	Parse a date with a specific format	`"15/01/2024"` with `DD/MM/YYYY`
`format_date`	Format a date to a specific string	DateTime to `"2024-01-15"`
`epoch_to_datetime`	Convert Unix timestamp	`1705276800` to `2024-01-15T00:00:00Z`

Lookup Tables¶

For fields where values need to be translated (not just renamed):

{
  "source": "kraftstoffart",
  "target": "fuel_type",
  "lookup": {
    "Benzin": "Petrol",
    "Diesel": "Diesel",
    "Elektro": "Electric",
    "Hybrid": "Hybrid"
  },
  "default": "Unknown"
}

Coverage Matrix¶

The coverage matrix shows how completely each connector maps to each CDM domain:

                  Vehicle  Customer  Order  Workshop  Part
MB OneAPI         ████░    ░░░░░     ░░░░░  ░░░░░     ░░░░░
DMS Connector     ████░    ████░     ███░░  ████░     ████░
CRM Connector     ░░░░░    ████░     ██░░░  ░░░░░     ░░░░░
Finance           ░░░░░    ███░░     ████░  ░░░░░     ░░░░░

Symbol	Meaning
Full bar	All fields mapped (required + optional)
Partial bar	Required fields mapped, some optional fields mapped
Empty bar	No mapping for this domain

View the coverage matrix in the Canonical Explorer to identify gaps before building orchestrations.

Best Practices¶

Verify all AI suggestions before using them in production
Map required fields first -- ensure all required CDM fields have mappings before optional ones
Use lookup tables for value translations (e.g., country codes, status values)
Document unclear mappings -- add notes explaining why a mapping was made
Check coverage before building orchestrations to avoid runtime errors from unmapped fields
Test with real data -- run a sample orchestration to verify mappings produce correct results

Next Steps¶

Available Domains -- see all CDM fields to map to
Canonical Explorer -- browse and verify mappings in the UI
What is the CDM? -- understand the CDM concept
AI Composer -- use mapped fields in AI-generated orchestrations