Canonical Mapping

Le mapping comme artefact concret du Canonical Model — l'unité de travail élémentaire d'une équipe d'intégration B2B.

Problème

Un hub EDI a 80 partenaires (chacun avec son format : EDIFACT D.96A, EDIFACT D.21B, X12 4010, X12 6020, UBL 2.1, cXML 1.2, Factur-X) et 6 systèmes internes (SAP, Oracle, Sage, Salesforce, lake Snowflake, archive S3). Sans modèle canonique, chaque partenaire doit être mappé vers chaque système : 80 × 6 = 480 mappings à maintenir. Une évolution X12 6020 → 7050 oblige à re-tester 6 mappings. Pire : chaque équipe ERP a sa propre convention, deux mappings vers SAP sont incohérents l'un avec l'autre.

Forces

• Le nombre de partenaires croît. Un retailer ajoute un nouveau fournisseur tous les mois.
• Les formats évoluent. Versions UN/EDIFACT mineures, X12 versions, UBL 2.1 → 2.3.
• Les systèmes internes diffèrent. SAP, Oracle, Sage ont des conventions différentes.
• Le mapping est versionnable. Un mapping est un artefact codé qui peut être testé, revu, livré.

Solution

Définir un modèle canonique interne riche sémantiquement (couvrant les besoins de tous les partenaires et systèmes). Puis matérialiser, pour chaque format externe, un mapping bidirectionnel partenaire ↔ canonique. Symétriquement pour chaque système interne : mapping canonique ↔ système. Le mapping est codé : XSLT, Smooks DSL, MapForce, Camel transformer, Apache NiFi processor, ou simple code Java/Python avec tests unitaires. Versionné en git, propriété d'une équipe référente.

Sans mapping canonique (N × M) :       Avec mapping canonique (N + M) :

  EDIFACT INVOIC ─┐                       EDIFACT INVOIC ─┐
  X12 810        ─┼──▶ SAP                                │
  UBL            ─┘                       X12 810        ─┤
                                                          ├─▶  Canonical
  EDIFACT INVOIC ─┐                       UBL            ─┤    Invoice
  X12 810        ─┼──▶ Oracle EBS                         │       │
  UBL            ─┘                       Factur-X       ─┘       │
                                                                  ├──▶ SAP
  EDIFACT INVOIC ─┐                                                │
  X12 810        ─┼──▶ Sage                                        ├──▶ Oracle
  UBL            ─┘                                                │
                                                                  └──▶ Sage
  3 partenaires × 3 ERP = 9 mappings        3 + 3 = 6 mappings

Implémentation EDI

Cas concret : hub EDI avec canonique Invoice.v3 en JSON Schema. Mapping edifact-invoic-d96a.xslt convertit EDIFACT INVOIC vers ce JSON : UNH.S009 → messageType, BGM.C002 → invoiceTypeCode, DTM+137 → issueDate, RFF+ON → orderReference, NAD+BY → buyer, NAD+SE → seller, segments LIN/PIA/IMD → tableau lines[]. Mapping inverse canonical-to-x12-810.py pour générer le X12 vers Walmart. Le code mapping inclut des tests unitaires : « PRI+AAA:25.00:CA équivaut à canonical.lines[].priceExclTax = 25.00 EUR ». Outils : BizTalk Mapper, Sterling Mapper, Boomi Map, Smooks, MapForce, ou code natif. Documentation des correspondances dans un format human-readable (Markdown table) à côté du mapping. Catalogue de mappings versionnés tenu en artefactory.

Anti-patterns

• Mapping ad hoc dans chaque microservice. Pas de modèle canonique central, chaque consumer mappe lui-même : duplication, divergence des règles.
• Mapping comme appendice du code applicatif. Si le mapping vit dans le code Java, il est lié au cycle de release applicatif. Le sortir comme artefact séparé.
• Mapping inversible mais asymétrique. Pour parser EDIFACT vers canonique, on tolère des trous (pas de prix unitaire : OK). Pour sérialiser canonique vers EDIFACT, on doit imposer un schéma strict. Confondre les deux donne des EDIFACT invalides.
• Mapping sans tests. La moindre modification casse silencieusement les flux partenaires. Investir dans une suite de tests par mapping (entrée fixture → sortie attendue).
• Mapping qui contient business logic. « Si pays = FR, alors taxer à 20% » dans le mapping : la règle fiscale s'éparpille. Garder dans un service dédié.

Patterns liés

• Canonical Model — le modèle cible / source des mappings.
• Mapping — l'artefact lui-même (pattern parent).
• Message Translator — le composant runtime qui exécute le mapping.
• Anti-Corruption Layer — le canonical mapping est typiquement l'output d'un ACL.
• Normalizer — le composant qui choisit le mapping selon le format détecté.

Sources

• Hohpe G., Woolf B. — Enterprise Integration Patterns, Addison-Wesley 2003. Canonical Data Model. enterpriseintegrationpatterns.com — CanonicalDataModel
• OpenPEPPOL — BIS Billing 3.0. Le canonique européen de la facture B2B (UBL 2.1 invoicing). docs.peppol.eu — Billing 3.0
• EN 16931 — European e-invoicing semantic model. La norme européenne du modèle canonique facture. cen.eu
• Apache Camel — Data Format reference. Catalogue d'utilities mapping (Bindy, Dataformat). camel.apache.org — Data Formats
• Smooks — EDI mapping. Outil open-source de mapping EDI ↔ Java. smooks.org