Mapping

The artifact that materialises the 'BTNR of 850 X12 corresponds to BGM01 of ORDERS EDIFACT' — without it, no partner integration.

Problem

The same business concept (PO number, GLN, currency) carries different names and positions per the partner standard. How to materialise these correspondences in an auditable and reusable way?

Forces

• Mappings must live as code (versioned, tested, deployed).
• A single source field may feed several target fields (split / fan-out).
• Defaults, transforms (uppercase, padding, lookup) must be explicit.
• A mapping must be testable via bilateral fixtures.

Solution

Define the mapping in a structured format: (1) XSLT for XML→XML, (2) DataWeave (MuleSoft) or JSLT/jq (JSON→JSON), (3) Smooks / FreeMarker for EDIFACT/X12. Each rule has a source, a target, an optional transform, and a fallback. The mapping is versioned in Git, tested via fixtures (input.x12 + expected.json), and deployed as an artifact distinct from app code. The Canonical Model pattern strongly depends on it: N mappings to canonical instead of N×N between formats.

EDI implementation

In EDI, a typical mapping links an ORDERS EDIFACT D.96A to a canonical `Order` JSON: `BGM[1010] → order.number`; `NAD+BY[3035=BY]/3039 → order.buyer.gln`; `DTM+137 → order.documentDate (yyyymmdd → ISO 8601)`. Common tools: IBM DataPower XI52, Software AG webMethods Mapper, Apache Camel marshal/unmarshal with data formats, or custom Smooks libs. Each mapping must have Walmart-realistic and Stellantis-realistic fixtures at minimum.

Anti-patterns

• Mapping in plain Java/Python code — not independently testable, change requires redeploy.
• Mapping without fixtures — every evolution silently breaks prod.
• Mapping that assumes implicit parser defaults — parser refactor breaks prod.
• N×N mappings instead of a canonical model — combinatorial explosion.

Related patterns

• Message Translator — engine applying the mapping.
• Canonical Model — pivot target schema.
• Normalizer — router that picks the mapping.

Sources

• Hohpe G., Woolf B. — EIP, Message Translator (p. 85) (Mapping is the base-level abstraction). www.enterpriseintegrationpatterns.com/patterns/messaging/MessageTranslator.html
• MuleSoft — DataWeave language guide. docs.mulesoft.com/dataweave/