Message Translator

Le pattern le plus omniprésent de toute intégration EDI : convertir un message d'un schéma source vers un schéma cible. Hohpe l'a canonisé en 2003 ; le code n'a pas beaucoup changé depuis — la discipline, si.

Problème

L'EDI est défini par la pluralité de ses formats : EDIFACT en Europe, X12 en Amérique du Nord, cXML chez Coupa et Ariba, UBL chez PEPPOL, IDoc côté SAP. Aucun partenaire ne parle un seul format. Pour intégrer dans son ERP les ORDERS reçus de 200 fournisseurs sous 4 formats différents, il faut traduire — souvent vers un modèle canonique interne — puis re-traduire vers la cible.

Forces

Sémantique inégale. Deux formats peuvent porter « la même information » dans des structures radicalement différentes. EDIFACT regroupe quantité et unité dans QTY+21:24:PCE, JSON les sépare. UBL utilise cbc:BaseQuantity avec attribut unitCode.
Information manquante. La cible peut imposer un champ que la source ne porte pas. Soit on enrichit (cf. Content Enricher), soit on calque une valeur par défaut documentée.
Perte d'information. Inversement, la source peut porter des champs que la cible ignore. Décision : les conserver dans un champ de trace, ou les jeter explicitement. Jamais en silence.
Maintenabilité. Une « map » de traduction est un actif logiciel qui survit aux versions. Elle doit être versionnée, testée, audit-clos.

Solution

Hohpe (EIP §85) prescrit un composant pur, sans état métier, qui prend un message du format A et renvoie le même message au format B — rien de plus. La traduction est structurelle (le schéma change) et parfois sémantique (les valeurs sont transformées : une date EDIFACT « 20260514 » devient « 2026-05-14 » ISO, une quantité avec unité PCE devient EA selon une table de correspondance UN/CEFACT REC 20).

plaintext topology.txt

EDIFACT ORDERS                  Canonical JSON
   ──────────────                  ──────────────
   UNH+1+ORDERS:...      ┌──────┐  {
   BGM+220+PO-001        │ M.T. │    "header": {
   DTM+137:20260514   ──▶│      │──▶   "type": "ORDER",
   NAD+BY+8712345600014  │      │      "number": "PO-001",
   LIN+1++4006381...     └──────┘      ...
   QTY+21:24:PCE                     }

Topologie

Deux topologies principales :

Point-to-point. Une traduction directe entre chaque paire source/cible. Simple à mettre en place pour 2-3 partenaires, devient ingérable au-delà — c'est le célèbre problème de mapping n × m.
Hub-and-spoke (canonique). Chaque format est traduit en un canonique commun, puis chaque format cible est généré depuis ce canonique. Le coût d'ajout d'un partenaire devient O(1) au lieu de O(n). Voir le pattern Canonical Model.

Implémentation EDI

L'exemple le plus emblématique : traduire un ORDERS EDIFACT D.96A vers un JSON canonique interne.

edifact orders-edifact.edi

UNH+1+ORDERS:D:96A:UN:EAN008'
BGM+220+PO-12345+9'
DTM+137:20260514:102'
NAD+BY+8712345600014::9'
NAD+SU+5412345600015::9'
LIN+1++4006381333931:EN'
QTY+21:24:PCE'
PRI+AAA:12.50'
UNT+8+1'

L'équivalent canonique :

json order-canonical.json

{
  "schemaVersion": "1.0",
  "header": {
    "type": "ORDER",
    "number": "PO-12345",
    "date": "2026-05-14",
    "buyer": { "gln": "8712345600014" },
    "supplier": { "gln": "5412345600015" }
  },
  "lines": [
    {
      "position": 1,
      "item": { "gtin": "4006381333931" },
      "quantity": { "value": 24, "uom": "PCE" },
      "price": { "value": 12.50, "currency": "EUR" }
    }
  ],
  "sourceTrace": {
    "format": "EDIFACT/D96A/ORDERS",
    "interchange": "ORD202605140001"
  }
}

Trois traductions intéressantes :

Date. DTM+137:20260514:102 → 2026-05-14. Le qualifieur 102 indique le format CCYYMMDD ; il faut reformater en ISO 8601.
Identifiant partenaire. NAD+BY+8712345600014::9 → buyer.gln. Le composite C082 contient l'identifiant + qualifieur d'agence (9 = EAN/GS1). On peut soit conserver le qualifieur dans la cible, soit l'élider si la cible n'a qu'un type d'identifiant.
Quantité avec unité. QTY+21:24:PCE → { "value": 24, "uom": "PCE" }. Le qualifieur 21 (Ordered quantity) est ici implicite par le contexte (segment QTY dans un ORDERS LIN).

Réversibilité

Une traduction est réversible si l'on peut reconstruire la source à partir de la cible sans perte. En EDI, la réversibilité pure est rare : les formats source ont souvent des champs optionnels ou redondants que la traduction normalise. La règle pragmatique : on n'a pas besoin de réversibilité au niveau byte, mais on doit pouvoir reconstituer un message équivalent sémantiquement. Cela permet de re-générer un INVOIC EDIFACT depuis le canonique pour répondre à un partenaire qui ne parle qu'EDIFACT.

Anti-patterns

Traduction directe partenaire à partenaire. 200 partenaires × 4 formats = 200 × 199 traductions possibles. Le canonique réduit à 200 entrées + 200 sorties.
Magic strings dans le code. Les correspondances (qualifieur EDIFACT → champ canonique) doivent être déclaratives — tables ou DSL — pas du code procédural enfoui.
Silence sur champs jetés. Si la traduction abandonne des informations, le journal doit le tracer explicitement. Sinon l'audit ne saura jamais pourquoi tel champ EDIFACT disparaît.
Tester par cas spécifique uniquement. Les tests doivent couvrir la combinatoire — qualifieurs, segments optionnels, cardinalités. Les bugs de traduction se nichent dans les combinaisons rares.
Versionning implicite. EDIFACT D.96A et D.01B n'ont pas la même structure NAD. Une seule traduction « EDIFACT » qui ignore la version finit toujours par casser.

Patterns liés

Canonical Model — le format pivot vers lequel on traduit.
Normalizer — le pattern qui orchestre plusieurs Message Translators selon le format détecté.
Content Enricher — quand la traduction nécessite des données externes.

Sources

Hohpe G., Woolf B. — Enterprise Integration Patterns, pattern Message Translator (§85). enterpriseintegrationpatterns.com — Message Translator
UN/CEFACT — Recommendation 20. Codes d'unités de mesure (PCE, EA, KGM...) et tables de correspondance internationales. unece.org — Recommendation 20
OASIS UBL 2.1 — Annex C. Tables de mapping sémantique entre concepts UBL et EDIFACT (Cross Industry Invoice).
SAP — IDoc ORDERS05. Documentation des structures IDoc cible et de leur correspondance avec ORDERS EDIFACT (note OSS 23).

Fondamentaux

Standards

Messages phares

Outils