Convertisseur XML Pivot - Opérations sur les champs

Attribut @id

Identifiant facultatif du champ source dans le XML de données.
Grâce au Wildcard ("*") il est possible de récupérer tous les champs sans devoir les spécifier individuellement : <field id="*"/>

Exemple : XML de données :

<data>
  <field id="site">1234</field>
  <doc type="BL">
    <field id="firstname">Martin</field>
    <field id="lastname">Garrix</field>
  </doc>
</data>

XML de paramétrage :

<param>
  <doc type="BL">
    <field id="*"/>
  </doc>
</param>

Résultat XML "Draw" (Pour le Designer Mapping) :

<doc>
  <page name="BL">
    <field name="GLOBAL_site">1234</field>
    <field name="firstname">Martin</field>
    <field name="lastname">Garrix</field>
  </page>
</doc>

Attribut @name

Facultatif, cet attribut permet la personnalisation du nom du champ cible pour le Designer en surchargeant le nom initial d'origine défini par l'attribut @id.

Attribut @data-type

Facultatif, cet attribut permet de spécifier le type de la donnée provenant du fichier XML de données.

Il permet de forcer le formatage de la donnée, par exemple si la valeur est “000045.65000” et que le type est “number” alors le résultat après transformation sera “45.65” (suppression des zéros non significatifs et application des séparateurs définis par défaut). Le type est utilisé également en cas de tri, afin de déterminé la méthode de tri (alphanumérique ou numérique)

Valeurs possibles :

• text : Valeur par défaut. Ne provoque aucun traitement de formatage
• number : Supprime tous les zéros non significatifs et applique les séparateurs de milliers et de décimal ainsi que le nombre de chiffres après la virgule par défaut.
• date : permet la conversion d’une date en spécifiant le format en entrée (dans le fichier XML de données) et le format attendu en sortie via les attributs @date-in et @date-out, leurs valeurs par défaut étant "ISO".

Exemple : data-type="date"

Si cet attribut n’est pas présent, il sera déterminé automatiquement à partir des attributs de mise en forme.
Ainsi, si un attribut @thousands-separator, @nb-decimal ou @decimal-separator est spécifié, il s’agit forcement d'un numérique (number), de même s’il s’agit d’un champ de type résultat de calcul.
Si @date-in ou @date-out est spécifié, il s’agit forcement d’une date.

Attribut @nb-decimal

Facultatif Nombre fixe de chiffres après la virgule (obtenu par arrondi au plus proche) Ajout de zéros non significatifs si nécessaire (ex : 123,457 => 123,4570 si @nb-decimal=4) Si non spécifié ou “auto”, conserver uniquement les chiffres significatifs après la virgule. Par exemple 12,42370000 → 12,4237 et 57,140000000 → 57,14 Pourquoi “auto” ? Pour surcharger une éventuelle valeur par défaut fixe passée en paramètre du programme ou via les attributs se trouvant au niveau <param> Permettre de spécifier un nombre min et max de chiffres après la virgule Exemple : nb-decimal="2,4" (min=2, max=4) 4.123456 -> 4.1235 4.1 -> 4.10 Remarque : nb-decimal="auto" est équivalent à nb-decimal="9999…" , dans la limite du nombre de chiffres après la virgule techniquement possible et disponibles. Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

Attribut @decimal-separator

Facultatif Chaine de caractères utilisée comme séparateur de décimales Valeur par défaut : "." ou paramètre du programme si spécifié Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

Attribut @thousands-separator

Facultatif Chaine de caractères utilisée comme séparateur de milliers Valeur par défaut : chaine vide ou paramètre du programme si spécifié Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

Attribut @date-in

Factultatif Valeur par défaut (si une conversion de date est requise) : "ISO" Le formatage en entrée peut également être véhiculé par le paramètre de l’attribut @data-type=date(xxxxx) Chaine de caractères permettant de spécifier le format de la date en entrée en vue de sa conversion Valeurs : Concaténation de texte “en dur” et de variables [D] : numéro du jour dans le mois sur 1 chiffre [DD] : numéro du jour dans le mois sur 2 chiffres [M] : numéro du mois sur 1 ou 2 chiffres (1 pour janvier , 10 pour octobre) [MM] : numéro du mois sur 2 chiffres [YY] : année sur 2 chiffres [YYYY] : année sur 4 chiffres Autres chaines de caractères : conservée telle quelle "ISO" : date au format ISO, équivalent à "[YYYY]-[MM]-[DD]" Exemples pour le 23 octobre 2020 : date-in="[YYYY][MM][DD]" signifie que la date est fournie sous la forme "20201023" date-in="[DD]/[MM]/[YYYY]" signifie que la date est fournie sous la forme "23/10/2020" data-type="date([DD]-[MM]-[YY])" signifie que la date est fournie sous la forme "23-10-20" Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "date"

Attribut @date-out

Factultatif Valeur par défaut (si une conversion de date est requise) : [DD]/[MM]/[YYYY] ou utiliser @culture si spécifié Syntaxe inspirée de la norme ISO 8601 Chaine de caractères permettant de spécifier le format de la date attendu après conversion Valeurs : Concaténation de texte “en dur” et de variables [D] : numéro du jour dans la semaine (1 pour lundi et 7 pour dimanche) [DD] : numéro du jour dans le mois sur 2 chiffres (01, 02, 03, …, 30, 31) [DD-short] : numéro du jour dans le mois sur 1 ou 2 chiffres (1, 2, 3, …, 30, 31) [DDD] : numéro du jour dans l’année [weekday-name-short] : nom du jour abrégé de la semaine (“Sun” pour Sunday, “Mon” pour Monday …). “dotw”=day(s) of the week, qui est différent de weekdays qui ne comprend ni le samedi ni le dimanche. [weekday-name] : nom du jour de la semaine (“Monday”, “Thuesday”, “Wednesday” …) [MM] : numéro du mois dans l’année sur 2 chiffres (01, 02, …, 12) [MM-short] : numéro du mois dans l’année sur 1 ou 2 chiffres (1, 2, …, 12) [month-name-short] : diminutif du nom du mois (Jan, Feb, Mar, Apr etc…) [month-name]: nom du mois (January, February, March etc…) [YY] : année sur 2 chiffres [YYYY] : année sur 4 chiffres [WW] : numéro de la semaine dans l’année sur 2 chiffres (01, 02, … , 52) [WW-short] : numéro de la semaine dans l’année sur un ou 2 chiffres (1, 2, …, 52) Autres chaines de caractères : conservée telle quelle "ISO" : [YYYY]-[MM]-[DD] Exemples pour le 23 octobre 2020 : date-out="[weekday-name], [month-name] [DD] [YYYY]" → "Thursday, October 23 2020" date-out="[DD]-[month-name]-[YY]" → "23-Oct-20" Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "date"

Attribut @culture

Facultatif Valeur par défaut : "en-UK" Chaine de caractère permettant de spécifier les types de conversion numériques ou de date Exemples : "fr-FR" , "en-US" , "en-UK" etc… Impact sur le séparateur de décimales (virgule ou point) , séparateur de milliers (virgule ou point), langue pour les noms de jours et de mois, formatage des dates

Attribut @case

Facultatif Permet de spécifier la casse Valeur par défaut : vide (pas de modification de la casse) Valeurs : "upper" : conversion en majuscule "lower" : conversion en minuscule "first-upper" : forcer la première lettre en majuscule, ne pas modifier le reste "first-upper-then-lower" : "forcer la première lettre en majuscule puis le reste en minuscules Exemples si le champ d’origine contient "hello World!" case="upper" → "HELLO WORLD!" case="lower" → "hello world!" case="first-upper" → "Hello World!" case="first-upper-then-lower" → "Hello world!"

Attribut @math

Facultatif Application d’une opération arithmétique sur un champ Syntaxe : math="<opération>" avec utilisation du caractère “.” pour représenter la valeur du champ avant calcul. Exemple : <field id="volume" math="./1000"/> Permet de diviser le volume par 1000 afin de convertir des millilitres en litres. Dans un premier temps seul ./xxxx .*xxxxx .-xxxxx .+xxxxx et .%xxxxxx doivent être mis en oeuvre Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

Attribut @prefix

Facultatif Chaine de caractère ajoutée en préfixe devant le champ Syntaxe : prefix="abcdefg" Exemple : <field id="volume" prefix="Volume : "/> avec volume=1000 Permet d’obtenir <field name="volume">Volume : 1000</field> Le prefix doit être appliqué uniquement si le contenu du champ n’est pas vide afin de ne jamais obtenir un champ ne contenant que le préfixe et/ou le suffixe. Exemple : si prefix="Montant : " et suffix="€", en cas d’absence de valeur (null ou chaine vide), le résultat ne doit surtout pas être "Montant : €"

Attribut @suffix

Facultatif Chaine de caractère ajoutée en suffixe après le champ Syntaxe : suffix="abcdefg" Exemple : <field id="volume" suffixe=" L"/> avec volume=1000 Permet d’obtenir <field name="volume">1000 L</field> Même principe et contraintes que l’attribut @prefix

Attribut @from

Facultatif Alias : @xfrom - les 2 syntaxes étant équivalentes Permet de récupérer la valeur d'un champ situé dans une autre branche du XML Cet attribut doit contenir le chemin, absolu ou relatif, de la branche contenant l'élément <field> à récupérer Si une collection est récupérée : si l’attribut @function est spécifié, cette fonction est appliquée sur la collection dans le cas contraire, c’est la valeur du 1er élément trouvé qui doit être récupéré 3 fonctions permettent de faciliter les requêtes relatives : global-data() : permet de pointer vers la racine du XML de données (/data ou plus généralement /* ) Exemple : from="global-data()" Il s’agit d’un chemin absolu current-doc() : permet de pointer à la racine de l'élément <doc> courant Exemple : from="current-doc()/list[@id='products']/item" pour récupérer la valeur d’un champ se trouvant dans la liste “product” du document courant. Il s’agit d’un chemin absolu parent-list() : Permet de remonter à la liste parent lorsque l’on se trouve dans une sous-liste Exemple : from="parent-list()/item" , ce qui revient en fait à from="../../item" mais plus intuitif Il s’agit d’un chemin relatif En cas d’absence de l’attribut @id sur le champ, on s’attend à ce que la requête XPATH spécifiée par le @from retourne une valeur, ou une collection de valeurs. Cela peut-être opportun en cas de requête XPATH complexe comprenant l’utilisation de fonctions XPATH appliquées sur les valeurs retournées. En cas de chemin absolu commençant par “/param” , la requête XPATH doit être appliquée non pas au XML de données mais au XML de paramétrage lui même. Cela permet de renseigner des données directement dans le fichier de param. Dans ce cas, la structure des données présente dans le XML de param est libre, mais en cas d’utilisation de l’attribut @id, il faut considérer que la valeur à récupérer provient d’un élément <field> possédant un attribut @id.

Exemple :

<field name="COMPTE" id="IBAN" from="/param/mydata/banque[id='CIC']" /> ou <field name="COMPTE" from="/param/mydata/banque[id='CIC']/field[id='IBAN']" />

1<param ……> 2 <doc … > 3 … 4 </doc> 5 6 <mydata> 7 <banque id="CIC"> 8 <field id="IBAN">FR76 4377 2347 7653 1235 8754 23</field> 9 </banque> 10 <banque id="CIC"> 11 <field id="IBAN">FR76 4377 2347 7653 1235 8754 23</field> 12 </banque> 13 </mydata> 14</param>

Attribut @keep-empty-if-void

Facultatif Booleen Si sa valeur est à "true", ce flag permet de créer un élément <field> vierge en sortie si l'origine de la donnée n'existe pas. somme de champs d'une "collection vide" (aucun élément retournée) champ <field> d'origine absent ou vide Le champ <field> créé doit alors est complètement vierge En effet, par défaut, la somme de rien retourne 0 Exemple : <field id="montant_ht" from="list[@id='frais']/item" function="sum()" nb-decimal="2">Montant : </field> --> <field name="montant_ht">Montant : 0,00</field>

<field id="montant_ht" from="list[@id='frais']/item" function="sum()" nb-decimal="2" keep-empty-if-void="true">Montant : </field> --> <field name="montant_ht"></field>

Illustration sur un cas concret : Les échéances 2, 3 et 4 sont vides (pas de montant à 0,00) malgré un formatage numérique avec 2 chiffres après la virgule.

Attribut @where

Facultatif, en complément de l’usage de l’attribut @from ou @xfrom L'attribut where permet d'appliquer un filtre sur la requête passée via l’attribut @from, par comparaison de valeurs avec le symbole "=" comme en SQL. Plusieurs comparaisons peuvent être effectuées, séparées par le mot clé “or” ou “and”. Exemple : where="((total < 1000) and (nom = 'foo') and (Condition 3)) or (Condition 4)" Dans cet exemple, les champs total et nom correspondent respectivement aux éléments <field id="total"> et <field id="nom"> frères de l'élément <field> à récupérer. La valeur 1000 implique une comparaison numérique, alors que la valeur 'foo' une comparaison alphanumérique grâce à la présence des quotes (simples ou doubles). Si la valeur du champ recherché contient une quote, il suffit de la doubler dans la recherche (comme en syntaxe SQL). Exemple : where="(nom='abcdefg')" si la valeur recherchée est abc'defg

Attribut @function

Facultatif Il s’agit d’une fonction d’agrégation permettant de réduire une collection de champs à une seule valeur. Applicable sur une collection de champs <field> enfants (champ composé) ou sur une collection de champs issus d’une requête via l’usage de l’attribut @from ou @xfrom. Attention : il y a des petites différences de comportement selon le cas d’usage (champ composé ou requête xpath) Valeurs possibles : sum() : somme → tout élément non numérique doit être considéré comme étant égal à 0 mul('default') : multiplication → en cas de présence d’un champ non numérique, le résultat doit être une chaine vide, ou la chaine “default” si cette dernière est spécifiée div('default') : division → en cas de présence d’un champ non numérique, ou de tentative de division par 0, le résultat doit être une chaine vide, ou la chaine “default” si cette dernière est spécifiée Cette fonction n’est pas applicable dans le cas de l’utilisation de l’attribut @function pour une collection de valeurs récupérées via l’usage de @from ou @xfrom A la place d’une valeur, spécifiée entre simples quotes, prévoir un mot clé permettant de retourner le calcul. Exemple : "5/0" Ce mot clé pourrait être : operation

Exemples :

1<field name="nb-colis-par-palette" function="div(operation)"> 2 <field id="nb-palettes"/> 3 <field id="nb-colis"/> 4</field> Ainsi, si nb-palettes=10 et nb-colis=0 alors le résultat nb-colis-par-palette sera "10/0"

1<field name="nb-colis-par-palette" function="div('N/A')"> 2 <field id="nb-palettes"/> 3 <field id="nb-colis"/> 4</field> Ainsi, si nb-palettes=10 et nb-colis=0 alors le résultat nb-colis-par-palette sera "N/A"

avg() : moyenne (somme des valeurs des champs divisée par la quantité de valeurs trouvées) → tout élément non numérique doit être considéré comme étant égal à 0 min(field id ou xpath , data-type) : valeur du champ ayant la plus petite valeur. ATTENTION Fonctionnement à débattre…. Les paramètres de la fonction “min” sont facultatifs. Il s’agit soit l'identifiant d'un élément frère, soit une requête xpath relative au chemin spécifiée dans la requête XPATH. S’il n’y a pas de paramètres, c'est le champ spécifié par l'attribut @id qui sera utilisé (c’est à dire le champ lui même). Un second paramètre facultatif permet de spécifier explicitement le type de comparaison à effectuer : 'number' , 'text' , 'date' Par défaut, la comparaison doit être numérique, mais peut être alphanumérique si le champ possède un attribut @data-type="text" ou si le contenu n’est pas numérique, ou alors une comparaison de date si @data-type="date". Le paramètre field id ou xpath est utilisable uniquement en cas d’usage de l’attribut @from ou @xfrom, permet de spécifier un élément frère ou relatif de l'élément recherché. La requête xpath est obligatoirement relative au chemin définit par l’attribut @from. Exemples : Recherche du numéro de colis ayant la plus petite date de livraison <field id="NUM_COLIS" from="list[@id='COLIS']/item" function="min(DAT_LIV,date([DD]/[MM]/[YYYY]))"/>

Recherche de la date de livraison la plus ancienne (plus petite) <field id="DATE_LIV" from="list[@id='COLIS']/item" function="min()" data-type="date([DD]/[MM]/[YYYY])"/>

Rercherche la palette dans laquelle se trouve le colis contenant le plus d’articles <field id="NUM_PALETTE" from="list[@id='PALETTES']/item" function="max(list[@id='COLIS']/item/field[@id='QTE_ARTICLES'])"/>

max(field id ou xpath , data-type) : valeur du champ ayant la plus grande valeur. Mêmes contraintes que pour min() concat('séparateur') : concaténation des champs en utilisant le séparateur spécifié. Ce dernier peut être aussi bien une chaine vide qu'une chaine d’un ou plusieurs caractères. Ce séparateur est appliqué uniquement entre 2 chaines non vides afin de ne pas obtenir une chaine de caractère comportant plusieurs séparateurs à la suite. first() last() count() Valeur par défaut : Dans le cadre d’un champ composé : concat(' ') Dans le cadre d’un résultat de requête via usage de l’attribut @from : first() Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number" (@data-type="number") dans le cas où la fonction utilisée retourne un numérique (sum, mul, count, avg etc…)

Noeud text()

Facultatif On ne les retrouve avec du contenu qu’en tant qu’enfant des éléments <field> S'il n'y a pas d'attribut @id, cela permet de créer un champ texte avec un contenu fixe (en dur). Cet usage implique obligatoirement l’utilisation de l’attribut @name S'il y a un attribut @id, la valeur renvoyée par ce dernier est préfixée par le contenu "text()" de l'élément <field> Exemple 1 : <field id="num_colis">Numéro de colis : </field> devient <field name="num_colis">Numéro de colis : 123456789</field> Exemple 2 : <field name="titre">Facture</field> devient <field name="titre">Facture</field>