Éditeur XSL
L'Éditeur XSL est l'outil central de NomaUBL pour le mapping source → UBL. Il transforme la rédaction d'une transformation UBL — un travail habituellement long — en un mapping par formulaire entre les champs d'un spool XML source et les termes métier (codes BT) d'une facture UBL 2.1.
La page fonctionne quel que soit le système source — JD Edwards, SAP, NetSuite ou ERP personnalisé. Le même éditeur s'applique à tout spool XML bien formé qui transporte des données de facture.
Vue d'ensemble
Rôle de l'éditeur
Une transformation NomaUBL est un fichier XSLT qui dérive des variables TAG_* à partir du XML source ; tout le reste — espaces de noms, ordre des éléments, conformité EN 16931, extensions françaises — est délégué à un fichier ubl-template.xsl partagé fourni par NomaUBL. Personnaliser une transformation revient donc à mapper des chemins XML vers les variables TAG_, ce que l'éditeur propose sous forme de formulaire.
L'éditeur ne touche jamais directement à la sortie UBL — cela reviendrait à réimplémenter EN 16931 à chaque transformation. Il édite le mapping que le template UBL consommera ; le template, lui, reste inchangé.
Barre d'outils
L'en-tête de page comporte une barre d'outils fixe :
| Élément | Description |
|---|---|
| Sélecteur de fichier | Liste déroulante de tous les fichiers .xsl présents dans le répertoire XSL configuré (e-invoicing.ublXslt). Trois fichiers partagés (ubl-common.xsl, ubl-template.xsl, ubl-defaults.xsl) sont filtrés — ils contiennent la mécanique UBL et ne se modifient pas par template. |
| Badge de répertoire | Affiche le répertoire XSL résolu. Configuré dans Configuration → System → e-invoicing → ublXslt. |
| Load | Lit le fichier sélectionné depuis le disque vers l'éditeur (les deux onglets partagent le même tampon). |
| New Transform | Ouvre la modale New Transform — copie ubl-template.xsl sous un nouveau nom et le sélectionne. Sert à initialiser une transformation par client ou par type de document. |
Onglets
L'éditeur propose deux onglets qui travaillent sur le même fichier XSLT. L'onglet de gauche est le formulaire de mapping visuel ; celui de droite est la source XSLT brute.
Variable Mapping (par défaut)
Le formulaire de mapping — l'alternative visuelle à la rédaction XSLT manuelle.
Barre d'actions
| Bouton | Comportement |
|---|---|
| Load XML Source | Charge un échantillon XML (côté navigateur) et en extrait tous les chemins d'éléments. Les chemins alimentent les sélecteurs en regard de chaque champ — les valeurs se renseignent par clic plutôt que par saisie. |
| Charger un échantillon connecteur | Quand le modèle de document actif est en source = Connecteur, ce bouton appelle une fois la requête SQL ou l'endpoint REST configuré, puis injecte la réponse dans le même sélecteur de chemins. Les listes déroulantes XPath autocomplètent alors sur des données réelles — même expérience qu'avec un vrai spool XML, sans aucun fichier. Le bouton est masqué pour les modèles XML et UBL. |
| AI Auto-Map ✦ | Ouvre la modale AI Auto-Map. À partir d'un échantillon XML (et d'un PDF optionnel), l'IA renvoie un mapping JSON des variables TAG_* vers les chemins XML, correctement scopés. Voir AI Auto-Map ci-dessous. |
| Save Mappings | Réécrit dans le fichier XSLT les valeurs courantes de toutes les variables TAG_*. Le point indicateur (●) apparaît quand le mapping a changé sans avoir été enregistré. |
Sections
Le formulaire est organisé par zone du document UBL. Chaque section n'apparaît que si au moins une de ses variables TAG_* est présente dans le XSLT chargé — les sections absentes du template sous-jacent ne sont pas affichées.
| Section | Zone UBL | Variables principales |
|---|---|---|
| Document Root | Élément racine de la facture | TAG_ROOT — l'élément XML englobant une facture. |
| Custom Extension Fields | ext:UBLExtensions | Issue de secours pour des données sans équivalent EN 16931 — voir Champs d'extension plus bas. |
| Invoice Header | BT-1, BT-2, BT-3, BT-9, BT-10, BT-12, BT-13, BT-19 | Numéro, dates, références. |
| Billing References | BT-11, BT-14 à BT-18, BT-122 à BT-124 | Projet, contrat, expédition, justificatifs. |
| Preceding Invoices — répété (BG-3, 0..n) | BT-25, BT-26 | Parcourt un groupe source répétitif et génère un cac:BillingReference par facture antérieure (avec une date d'émission facultative), en complément de la référence unique BT-25/BT-26 déjà gérée dans Billing References. |
| Embedded Attachments (BT-125) | cac:AdditionalDocumentReference / EmbeddedDocumentBinaryObject | Joindre un document déjà encodé en base64 dans le spool source — jusqu'à quatre par facture. Voir Pièces jointes intégrées plus bas. |
| Seller / Supplier | BT-27 à BT-43 | Identification, adresse et contact du vendeur — plus, dans le panneau Seller Identifiers, jusqu'à quatre identifiants supplémentaires avec un schéma (BT-29), chacun un champ source + un code de la liste Scheme IDs. |
| Buyer / Customer | BT-44 à BT-58, BT-163 | Identification, adresse et contact de l'acheteur — plus, dans le panneau Buyer Identifiers, jusqu'à quatre identifiants supplémentaires avec un schéma (BT-46), chacun un champ source + un code de la liste Scheme IDs. |
| Agent Party | extended-ctc-fr | Tiers intermédiaire optionnel. |
| Delivery | BT-70 à BT-80 | Date et adresse de livraison. |
| Payment | BT-20, BT-81 à BT-91 | Moyen, IBAN, BIC, mandat, conditions. |
| VAT | BT-110, BT-116 à BT-121 | Détail TVA — voir scoping ci-dessous. |
| Invoice Lines | BT-126 à BT-161 | Lignes de facture, avec le pays d'origine (BT-159), le code de classification (BT-158) et la version de schéma (BT-158-2) par ligne — voir scoping ci-dessous. |
| Item Properties (BG-32) | BG-32 | Attributs produit attachés à une ligne. |
| Line Allowances/Charges (BG-27 / BG-28) | BG-27 / BG-28 | Remise ou charge par ligne. Pointer le TAG Item AC sur . (ou le laisser vide) quand les champs de remise se trouvent directement sur la ligne, sans élément parent — le moteur itère alors la ligne elle-même. Quand la source ne porte que le pourcentage, le montant et la base sont déduits du net de la ligne ; pourcentage + base déduit le montant, pourcentage + montant déduit la base. |
| Line Document References (BT-128, BT-132) | BT-128, BT-132 | Références de document par ligne — pièces justificatives (BT-128, schéma UNTDID 1153) et la ligne de bon de commande référencée via TAG_LINE_ORDER_LINE_REF → cac:OrderLineReference/cbc:LineID (BT-132, groupe EXT-FR-FE-BG-09, placé entre InvoicePeriod et DocumentReference selon la séquence UBL 2.1). |
| Line Preceding Invoice (EXT-FR-FE-136) | cac:BillingReference par ligne | Référence à une facture antérieure au niveau ligne — utile pour un avoir en ligne. Écrit cac:BillingReference / cac:InvoiceDocumentReference / cbc:ID (avec une date d'émission facultative) à l'intérieur de la ligne, à la bonne position dans le schéma. |
| Line Delivery (EXT-FR-FE-BG-10) | Extension française | Groupe livraison par ligne. |
| Line Notes (BT-127) | BT-127 | Notes libres attachées à une ligne. |
| Invoice Notes (BT-22) | BT-22 | Notes libres au niveau document. |
| Loop Notes | BT-22 | Groupes de notes répétés au niveau document. |
Chaque champ affiche le libellé du BT, son code BT en badge coloré, la valeur courante (chemin XML ou expression) et un sélecteur ↓ qui ouvre le navigateur XML sur la droite.
La référence de champs liste désormais chaque groupe (BG) et terme (BT) que le Schematron étendu (BR-FR / CTC-FR 1.3.1) contrôle et que l'éditeur sait mapper — BG-3 à BG-32 et les termes qu'ils encadrent (facture précédente BT-25/26, devise de comptabilisation TVA BT-6 / BT-111, date du fait générateur BT-7, identifiant fiscal vendeur BT-32, subdivisions acheteur / livraison BT-54 / BT-79, contact acheteur BT-56, lieu de livraison BT-71, numéro de carte tronqué BT-87, code unité de quantité BT-130, assiette et motif des charges de ligne BT-142/145, ligne 3 d'adresse de livraison BT-165, et d'autres). Ce que vous pouvez mapper ici correspond désormais exactement à ce que le validateur contrôle.
L'éditeur a gagné un mappage Buyer trading name (BT-45 → cac:PartyName/cbc:Name sur la partie client, à l'image du nom commercial vendeur BT-28), et trois mappages de totaux document — Sum of charges (BT-108), Amount already paid (BT-113) et Rounding amount (BT-114). Quand un montant déjà payé ou un arrondi est mappé, le montant dû (BT-115) est calculé comme total avec TVA − déjà payé + arrondi. Un mappage ajouté à un modèle apparaît désormais toujours dans sa section, même quand la liste de champs intégrée ne le prévoyait pas.
Combiner et filtrer les valeurs source
Un select TAG_* ne se limite pas à un seul chemin XML :
- Concaténation (
+). Assemblez plusieurs tags source en une seule valeur UBL avec l'opérateur+—'FirstName + LastName'les joint par une espace,'First + ", " + Last'choisit le séparateur, et les chaînes entre guillemets sont rendues telles quelles. Plus besoin d'une étape de pré-traitement XSL quand un champ UBL agrège plusieurs colonnes source. - Liste de valeurs conditionnelle. Le paramètre
cond_valuedes helpersubl:emit-item-prop/ubl:emit-noteaccepte une valeur unique (comme avant) ou une liste séparée par des virgules —'KWH,M3,LTR'correspond quand la source vaut l'un des trois. Les espaces autour de chaque élément sont supprimés. - Axe parent (
..). Un chemin peut remonter à l'élément parent :../FIELDatteint un voisin de l'élément ligne courant,../../FIELD/Subdeux niveaux plus haut. Cela débloque les XML sources où les lignes sont imbriquées sous un parent qui porte aussi les références de ligne (par exemple la commande client référencée, BT-132) ; les chemins sans..se résolvent exactement comme avant. - Valeurs constantes (accents graves). Une valeur encadrée par des accents graves — par exemple
`EDI`— est écrite telle quelle au lieu d'être lue dans la source. Valable pour les champs d'extension, les notes et les attributs d'article ; utile pour les valeurs fixes propres à une plateforme.
Scoping
TAG_ROOT, TAG_VAT_LINE et TAG_LINE_ITEM sont des contextes de portée : toutes les autres variables s'y rattachent et leurs chemins se résolvent relativement au chemin défini par le contexte.
Une bannière de scope bleue apparaît sous chaque variable de contexte pour rappeler le préfixe actif. Le navigateur XML filtre lui aussi ses entrées sur ce scope — le sélecteur ne propose donc que les chemins effectivement adressables depuis le contexte courant.
Navigateur XML
Une fois Load XML Source activé, cliquer sur le bouton ↓ en regard d'un champ ouvre un navigateur XML sur le bord droit de la page. Il liste tous les chemins d'éléments du scope courant et leur valeur d'échantillon — le bon chemin se choisit par inspection plutôt que par saisie. Sa fermeture laisse l'éditeur dans son état précédent.
Champs d'extension
Pour des données attendues par un partenaire mais sans équivalent standard EN 16931 — un mode d'acheminement, une adresse de copie de livraison, un identifiant partenaire — la section Custom Extension Fields mappe jusqu'à huit valeurs source dans un bloc ext:UBLExtensions en tête de facture. Chaque ligne porte :
| Champ | Effet |
|---|---|
| Nom d'élément | Le nom de balise écrit à l'intérieur de ext:ExtensionContent. Émis sous forme d'élément simple sans préfixe ni xmlns, dans l'espace de noms du document — la forme qu'attendent les plateformes agréées. |
| Valeur | Un chemin source, une expression combinant plusieurs chemins, un appel de {template} ou une constante entre accents graves (voir Combiner et filtrer les valeurs source plus haut). |
| Condition d'émission | Le même prédicat facultatif cond_value que les attributs d'article — la ligne est ignorée si la valeur source ne correspond pas. |
Chaque champ configuré est émis dans son propre bloc ext:UBLExtension / ext:ExtensionContent (UBL n'admet qu'un seul élément enfant par contenu d'extension), et le bloc complet est omis si aucun champ ne se résout. Vide par défaut : les factures existantes restent inchangées.
Les données placées ici sortent du modèle EN 16931 — privilégier le champ standard lorsqu'il existe (référence comptable BT-19, référence acheteur BT-10…) et vérifier que la plateforme destinataire lit bien l'extension.
Factures antérieures — répétées et par ligne
Pour les factures qui référencent un document précédent — typiquement un avoir qui pointe sur la facture qu'il corrige — deux mappages viennent compléter la référence unique BT-25 / BT-26 déjà présente dans la section Billing References :
Au niveau document, répété (BG-3, 0..n). La section Preceding Invoices — répété parcourt un groupe source répétitif et émet un cac:BillingReference par facture antérieure trouvée. Deux champs :
| Champ | Effet |
|---|---|
| TAG itérateur | Chemin du groupe répétitif dans le XML source (par exemple Header/PriorInvoices/Item). Un cac:BillingReference / cac:InvoiceDocumentReference / cbc:ID est émis par nœud que l'itérateur capture. |
| TAG date d'émission (facultatif) | Chemin (relatif à l'itérateur) vers la date d'émission de la facture antérieure. Renseigné, il alimente cbc:IssueDate ; laissé vide, la référence est émise sans date. |
Le bloc répété et la référence unique BT-25 / BT-26 peuvent coexister — retenir celle qui colle à la source, ou les deux quand la source porte une référence de tête plus une liste répétitive.
Au niveau ligne (EXT-FR-FE-136). Utile pour les avoirs en ligne qui pointent sur une ligne de facture précise. Un nouveau mappage sous la section Invoice Lines émet cac:BillingReference / cac:InvoiceDocumentReference / cbc:ID à l'intérieur de la ligne — avec une date d'émission facultative — à la bonne position dans le schéma.
Le XPath de ligne est contrôlé par le schematron Extended-CTC-FR aligné sur la publication FNFE V1.4.0 du 30 juin 2026, donc la structure émise correspond à ce que la PA attend.
Pièces jointes intégrées
La section Embedded Attachments joint à la facture UBL un document déjà encodé en base64 dans le spool source — jusqu'à quatre par facture. Chaque ligne mappe :
| Champ | Effet |
|---|---|
| Chemin source base64 | Le chemin XML qui porte la charge base64 dans le spool. |
| Nom de fichier | Texte fixe ou espace réservé {Champ} / {Groupe/Champ} — par ex. {DocNumber}.pdf. |
| Type MIME | Le type de média déclaré (application/pdf, image/png, …). |
| Code | Un code choisi dans la liste de référence de la plateforme (PJA, RIB, BON_LIVRAISON, …). |
La ligne est émise sous forme de cac:AdditionalDocumentReference avec un EmbeddedDocumentBinaryObject inline (BT-125). Elle se place à la bonne position dans le schéma et coexiste avec les autres sources de pièces jointes déjà gérées (fichiers sur disque, PDF lisible généré) — le tout reste groupé dans la même sortie. Jusqu'à cette section, une pièce jointe ne pouvait venir que d'un fichier sur disque ou du PDF généré, jamais d'un champ base64 déjà présent dans le spool.
XSL Editor
L'onglet de droite ouvre le même fichier dans un éditeur Monaco complet (le moteur utilisé par VS Code) avec coloration syntaxique XML, numéros de ligne et minimap. Cet onglet sert quand le formulaire ne couvre pas un besoin :
- Expressions XPath personnalisées en dehors des variables TAG_.
- Logique conditionnelle via
<xsl:if>/<xsl:choose>. - Appel de templates définis dans
ubl-common.xsl. - Inspection de la sérialisation finale du mapping issu du formulaire.
Le bouton de sauvegarde affiche un point ● quand le tampon diverge du fichier sur disque.
AI Auto-Map
La modale AI Auto-Map est un raccourci pour construire un mapping à partir de zéro.
| Champ | Description |
|---|---|
| Upload XML from computer | Charge l'échantillon XML source. |
| Upload PDF (facultatif) | Charge un PDF rendu de la même facture. L'IA s'en sert comme référence visuelle pour lever les ambiguïtés sur les champs. |
| Invoice root element | Élément XML englobant une facture (par ex. Invoices). Pré-rempli depuis la racine du XML chargé, modifiable. |
| XML content | Corps du spool XML. Renseigné automatiquement par le téléversement, modifiable manuellement. |
Cliquer sur Auto-Map transmet le XML (et le PDF s'il est fourni) à l'IA, avec la liste des variables TAG_* et de leur contexte BT/BG. L'IA renvoie un mapping JSON qui respecte les règles de scoping (chemins relatifs à TAG_ROOT, chemins relatifs à la ligne dans TAG_LINE_ITEM, etc.). Le mapping est fusionné dans le formulaire ; après revue, cliquer sur Save Mappings pour valider.
L'IA reste prudente — elle omet toute variable dont elle n'est pas certaine plutôt que de proposer une supposition. Une revue manuelle reste nécessaire ; l'éditeur accélère le travail, il ne remplace pas l'expertise.
New Transform
La modale New Transform copie ubl-template.xsl sous un nouveau nom dans le même répertoire XSL.
| Champ | Description |
|---|---|
| File name (without .xsl) | Nom de base de la nouvelle transformation. L'extension .xsl est ajoutée automatiquement. |
Après création, le nouveau fichier devient le fichier sélectionné et est chargé dans l'éditeur — prêt pour le mapping.
Conseils & bonnes pratiques
- Démarrer avec AI Auto-Map sur un échantillon représentatif. Couvre généralement 70–90 % du mapping en une passe ; le reste est affaire de revue et de cas particuliers.
- Charger systématiquement un échantillon XML avant de mapper. Avec Load XML Source actif, les sélecteurs déroulants réduisent fortement la saisie manuelle et écartent les coquilles.
- Renseigner TAG_ROOT, TAG_VAT_LINE et TAG_LINE_ITEM en premier. Tous les autres champs se résolvent relativement à ces scopes ; les renseigner d'abord garantit que les sélecteurs suivants ouvrent le bon contexte.
- Une transformation par layout source. Différents systèmes sources — ou différents types de documents pour un même système — méritent généralement leur propre
.xsl. Préférer New Transform à un copier-coller dans le système de fichiers. - Ne pas modifier les fichiers partagés.
ubl-common.xsl,ubl-template.xsletubl-defaults.xslsont filtrés du sélecteur pour une raison : toute modification y touche toutes les transformations et risque de ne pas survivre à une montée de version NomaUBL. - Utiliser l'onglet XSL Editor pour ce que le formulaire ne couvre pas. Logique conditionnelle, XPath personnalisé, templates nommés — Monaco donne toute la puissance de XSLT 1.0 / 2.0 en complément du mapping du formulaire.
- Valider après chaque modification de mapping. UBL Tools → Validate avec
Source = XMLexécute la transformation et les règles Schematron en une passe ; la table de logs signale tout chemin erroné ou variable manquante.