Au sein d’un système d’intégration, les applications échangent rarement des données avec exactement la même structure. Une API peut produire une commande au format JSON, tandis qu’un ERP attend un document avec d’autres noms de propriétés, une organisation différente ou des valeurs calculées.
Azure propose plusieurs mécanismes de manipulation et de transformation des messages. Le choix de l’outil dépend avant tout de la nature du traitement à réaliser.
Le Data Mapper est un outil de conception disponible dans Visual Studio Code avec l’extension Azure Logic Apps (Standard) : https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurelogicapps.
Il permet de modéliser une transformation entre les propriétés d’un schéma source et celles d’un schéma cible. Pour cela, on lie visuellement les éléments entre eux dans une interface graphique de mapping. Il est également possible d’insérer des fonctions entre ces éléments afin d’effectuer des opérations telles que :
Lors de l’enregistrement du mapping, l’outil produit un fichier de transformation XSLT qui sera exécuté par le runtime de Logic Apps. Cet outil fournit donc une interface graphique permettant de construire des transformations XSLT sans avoir à écrire manuellement l’intégralité du code.
Plusieurs fonctionnalités de Logic Apps peuvent sembler similaires, mais elles répondent à des besoins différents.
Les actions Data Operations, comme Select, Compose, Filter array ou Parse JSON, sont adaptées aux manipulations relativement simples réalisées directement dans un workflow.
Le Data Mapper devient plus intéressant lorsque :
Dans cet article, nous allons découvrir l’action Transform using Data Mapper XSLT, destinée aux mappings créés avec le Data Mapper. Elle ne doit pas être confondue avec l’action Transform XML, destinée aux transformations XSLT créées avec d’autres outils.
Cette distinction est importante : un mapping généré par le Data Mapper doit être appelé avec l’action dédiée aux opérations du Data Mapper.
Pour créer un mapping, il faut disposer :
Les schémas peuvent être fournis sous la forme :
Dans la suite de l’article, nous utiliserons deux fichiers XSD afin d’illustrer une transformation XML plus avancée.
Officiellement, Microsoft indique que le Data Mapper est pris charge dans Visual Studio Code sous Windows uniquement. Toutefois, sur MacOS, il est possible d’utiliser l’éditeur graphique pour créer et modifier des mappings grâce à des solutions de contournement.
En revanche, la fonctionnalité native Test Map, disponible sous Windows, ne fonctionne pas nativement sous MacOS car elle dépend d’un composant .NET Framework propre à Windows. Il est tout de même possible de tester les transformations localement au moyen du SDK de test Logic Apps et de tests .NET.
Pour plus de détails, voir : Workaround: Testing Logic Apps Data Mapper Maps on macOS – DEV Community
Pour illustrer le Data Mapper avec un cas plus réaliste, prenons l’exemple de l’entreprise MyCompany. Cette entreprise reçoit des commandes e-commerce au format XML et doit les transformer vers un format attendu par son ERP.
Le flux source contient les données suivantes :
L’ERP de MyCompany attend cependant un format différent, structuré de la manière suivante :
Dans notre cas, la solution consiste donc à utiliser une Logic App Standard avec le Data Mapper afin de transformer le format source vers le format cible.
Pourquoi utiliser le Data Mapper ici ? Parce qu’il ne sert pas uniquement à relier des champs simples. Il peut également gérer des structures imbriquées, des collections, des conversions de valeurs, des calculs et des règles conditionnelles.
La transformation doit donc effectuer plusieurs opérations de mapping. Dans l’outil Data Mapper, ces règles de transformation sont représentées graphiquement par des connexions entre les nœuds source et cible, avec l’utilisation, si nécessaire, de fonctions intermédiaires.
How to : Create Standard Workflows with Visual Studio Code – Azure Logic Apps | Microsoft Learn
La première étape consiste à ajouter, , les schémas de données au format XSD que nous allons utiliser.
Ces schémas seront ensuite utilisés par le Data Mapper pour afficher la structure du message source et celle du message cible. Ils permettront de créer les correspondances entre les différents éléments XML.
Dans Visual Studio Code, il faut ouvrir le projet Logic Apps Standard, puis accéder à la section Data Mapper de l’extension Azure.
Il est également possible de créer une map depuis la vue « Explorer » du workspace. Pour cela, on peut faire un clic droit sur le dossier « Maps », puis sélectionner « Create Data Map ».
Après avoir renseigné le nom de notre nouvelle map, une interface de création de Data Map va s’ouvrir. Cette interface est composée principalement de trois zones :
Avant de pouvoir appliquer nos règles de transformations, il faut renseigner les schémas source et cible. Une fois cela fait, vous devriez retrouver toutes les propriétés dans « Source » et « Destination » :
Sur la partie gauche de l’interface, on retrouve la liste des fonctions proposées par le Data Mapper. Ces fonctions peuvent être utilisées pour construire des transformations plus complexes, par exemple des concaténations, des calculs, des conditions ou des conversions de valeurs.
Une fois les schémas chargés, nous pouvons commencer à créer les premières correspondances entre les champs source et cible.
Lorsqu’aucune transformation n’est nécessaire, un élément source peut être directement relié à un élément cible. Ce type de mapping est adapté lorsque les deux éléments utilisent des types compatibles.
Pour cela, il faut sélectionner la propriété source, puis tracer un lien vers la propriété cible en effectuant un glisser-déposer.
Voilà le résultat avec d’autres mapping direct :
Le Data Mapper propose plusieurs types de fonctions. On retrouve notamment des fonctions permettant d’effectuer des conversions, de manipuler des tableaux, d’appliquer des conditions ou encore de traiter des strings.
Par exemple, imaginons que nous ayons les règles de mapping suivantes :
| Source | Cible | Mapping |
| Order.Customer.Type | Partner.PartnerCategory | Conversion B2C → CONSUMER, B2B → BUSINESS |
| Order.Customer.FirstName + Order.Customer.LastName | Partner.DisplayName | Concaténation pour un client particulier |
| Order.Customer.CompanyName | Partner.DisplayName | Utilisé si le client est de type B2B |
Le résultat pourrait ressembler à cela :
Avec :
L’utilisation de fonctions permet de maintenir la logique de transformation dans le mapping plutôt que de multiplier les actions intermédiaires dans le workflow.
Pour transformer lines en items, les éléments parents des deux tableaux doivent être reliés.
Le Data Mapper ajoute alors la logique d’itération nécessaire. Les propriétés internes doivent néanmoins être mappées explicitement.
Par exemple, nous voulons créer un mapping vers OrderLInes.OrderLine.LineAmount :
| Source | Cible | Mapping |
| Lines.Line.Quantity Lines.Line.UnitPrice Lines.Line.DiscountAmount |
OrderLines.OrderLine.LineNetAmount | Lines.Line.Quantity x Lines.Line.UnitPrice – Lines.Line.DiscountAmount |
Un lien se crée automatiquement entre les éléments parents de la collection.
Lors de l’enregistrement, le Data Mapper crée deux artefacts principaux :
Le fichier .lml contient la définition utilisée par l’éditeur visuel.
Le fichier .xslt contient la transformation exécutable par Logic Apps.
Ces deux fichiers doivent être conservés dans le dépôt Git. Le fichier .lml permet de continuer à modifier visuellement le mapping, tandis que le fichier .xslt constitue l’artefact utilisé à l’exécution.
Les schémas peuvent également être stockés dans le dossier suivant : Artifacts/Schemas
Cette organisation facilite la gestion des contrats et des mappings dans le même projet que les workflows.
Grâce à l’extension Azure Logic Apps (Standard), il est possible de tester une map directement depuis Visual Studio Code. Le Data Mapper contient en effet un panneau de test dans lequel on peut fournir un exemple de message source.
Attention : avant d’exécuter le test, il faut enregistrer le mapping afin de régénérer le fichier XSLT avec les dernières modifications.
Le résultat de la transformation est alors affiché directement dans Visual Studio Code. Cette fonctionnalité permet de tester rapidement :
En cas d’erreur lors du test, il faut vérifier à la fois le message XML d’entrée, la validité des schémas XSD et la configuration locale du runtime Logic Apps Standard.
Une fois le mapping enregistré, il peut être appelé depuis le designer du workflow.
Il faut ajouter l’action intégrée Transform using Data Mapper XSLT.
L’action demande principalement :
Dans un projet local, il suffit ensuite de sélectionner le fichier présent dans le dossier Artifacts/Maps.
Le résultat de cette action peut ensuite être transmis aux étapes suivantes du workflow, par exemple vers un topic Service Bus.
Dans une Logic App Standard, les artefacts locaux peuvent être déployés avec l’application et ses workflows.
Dans le cas d’un déploiement via pipeline YAML, le projet Logic App Standard est d’abord packagé sous forme d’archive ZIP, puis publié comme artefact de pipeline. Cette archive contient les éléments nécessaires à la map, notamment les fichiers .lml, .xslt et les schémas.
Voici un exemple de code :
- task: AzureLogicAppsStandardBuild@1 displayName: 'Azure Logic Apps Standard Build' inputs: sourceFolder: '$(Build.SourcesDirectory)/MyLAppStd.ProjectName/MyLAppStdName' deploymentFolder: '$(System.DefaultWorkingDirectory)/deployment/MyLAppStd.ProjectName/' archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip' deploymentWorkflowParametersFile: '$(Build.SourcesDirectory)/MyLAppStd.ProjectName/MyLAppStd.ProjectName/parameters.json' - task: PublishPipelineArtifact@1 displayName: 'Publish logic app zip artifact' inputs: targetPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip' artifact: 'MyArtifactName' publishLocation: 'pipeline'
Le déploiement d’une Logic App Standard se fait en deux étapes :
Le déploiement du code peut être réalisé une fois le projet build et l’artefact publié. L’archive ZIP peut ensuite être déployée sur la ressource cible.
Voici un exemple de code permettant de le faire :
- job: Deployment_LogicApp displayName: "Deploy Logic App" steps: - task: DownloadPipelineArtifact@2 displayName: "Download LogicApp Artifact" inputs: artifact: 'MyArtifactName' path: $(Pipeline.Workspace) - task: AzureFunctionApp@1 displayName: "Deploy logic app workflows" inputs: azureSubscription: "MyAZureSubscription" appType: "functionAppLinux" appName: "my-lapp-std-dev" package: "$(Pipeline.Workspace)/MyArtifactName" deploymentMethod: "zipDeploy"
Finalement, l’utilisation du Data Mapper n’ajoute pas d’étape de déploiement spécifique. En revanche, elle ajoute des artefacts qui doivent être présents dans le package de la Logic App Standard.
Les fichiers de schéma, les fichiers .lml et les fichiers .xslt doivent être placés sous contrôle de source.
Une modification de schéma peut avoir un impact direct sur plusieurs mappings. Ces changements doivent donc être traités comme des évolutions de contrats d’interface.
Lorsque la transformation est gérée avec le Data Mapper, il est préférable de modifier le fichier .lml depuis l’éditeur visuel, puis de régénérer le XSLT.
Une modification manuelle du fichier généré risque d’être perdue lors du prochain enregistrement du mapping.
Pour les besoins plus spécifiques, le Data Mapper permet d’intégrer des fragments XSLT ou d’utiliser des fonctions personnalisées.
À la date de rédaction de cet article, plusieurs limites doivent être prises en compte :
Ces limites ne remettent pas en cause l’intérêt de l’outil, mais elles doivent être analysées avant de choisir le Data Mapper pour une transformation complexe.
Le Data Mapper apporte à Azure Logic Apps Standard une expérience de transformation visuelle particulièrement utile pour les scénarios d’intégration structurés.
Il permet de séparer les règles de conversion de l’orchestration, de travailler à partir de schémas, de tester localement les transformations et de versionner les artefacts avec le reste du projet et également un avantage.
Il est particulièrement adapté aux équipes qui manipulent des contrats XML ou JSON complexes, mais peut aussi être utilisé dans le cadre d’une modernisation d’une plateforme d’intégration basée sur BizTalk Server, par exemple.
Pour les transformations simples, les actions Data Operations restent souvent suffisantes. En revanche, lorsque la structure des messages devient complexe ou que le mapping représente un véritable contrat d’intégration, le Data Mapper constitue une solution plus lisible, testable et maintenable.
