Je suis actuellement en mission comme externe dans une équipe qui utilise la Hybris Management Console, ou HMC pour faire court, pour administrer un environnement SAP Commerce. Tous les quelques jours, l'environnement partagé est rafraîchi depuis la production, ce qui est exactement ce qu'on veut pour la plupart des données, et exactement ce qu'on ne veut pas pour les configurations à moitié finies qui n'ont pas encore été poussées en prod. Un type de contenu que vous avez enregistré mardi, un ajustement de workflow fait mercredi, un utilisateur de test dont vous aviez besoin pour une démo; tout cela a disparu vendredi matin. Toute l'équipe est passée par cette boucle assez souvent pour avoir cessé d'être surprise.
Impex est la réponse naturelle. Si vous pouvez décrire un changement de configuration sous forme de fichier Impex, vous pouvez le rejouer après chaque refresh, le versionner, le passer en revue de code et le traiter comme le reste de la plateforme. C'est le playbook officiel et c'est le bon.
Le problème est plus humain que technique. Personne dans l'équipe ne lit Impex couramment. Le format précède la plupart des langages que l'équipe écrit au quotidien, l'outillage autour est rare, et une pull request de soixante lignes de texte séparé par des points-virgules n'invite pas vraiment à une relecture attentive. Alors les gens préfèrent cliquer dans la HMC, accepter que le travail s'évapore dans quelques jours et passer à autre chose. Sachant que cela se règle avec de l'outillage, pas avec une session de formation, j'ai passé une semaine à construire les huit outils navigateur dont parle ce post.
Ce qu'est Impex, en un paragraphe
Impex est un format de script en texte brut que SAP Commerce utilise pour insérer, mettre à jour ou supprimer des lignes dans le système de types de la plateforme. Chaque objet Hybris (Product, Catalog, Category, PriceRow, User, Customer, Order) est un type défini en Java, et Impex est la manière de pousser des données vers ces types sans écrire de Java. Un fichier est une suite de "blocs", chacun avec une ligne d'en-tête déclarant un mode et un type (INSERT_UPDATE Product;code[unique=true];name) suivie de lignes de données séparées par des points-virgules (;P-0001;My Product). Les commentaires commencent par #. Les macros commencent par $. Les chemins de qualification vont entre parenthèses: catalogVersion(catalog(id),version). La référence officielle de l'interpréteur Impex est la spécification qui fait foi.
Voilà tout le langage. Il est véritablement petit. Ce qui rend sa lecture difficile n'est pas la grammaire; c'est un format tabulaire affiché dans un éditeur de texte, sans alignement des colonnes, sans coloration syntaxique, sans aucune des commodités qu'on voudrait pour relire une feuille de calcul.
Pourquoi HMC plus un refresh périodique force cette conversation
Il y a un motif récurrent dans les projets SAP Commerce: vous avez un seul environnement de type prod partagé entre produit, QA et ingénierie. Pour le garder proche de la réalité, quelqu'un lance un refresh depuis la production selon un calendrier, hebdomadaire, bi-hebdomadaire, nocturne. Ce refresh n'est pas négociable; c'est ainsi qu'on reproduit les bugs. Mais cela signifie que chaque changement de configuration qui ne vit que dans la HMC a une demi-vie.
Il y a trois issues et une seule passe à l'échelle.
Option une: arrêter de faire le refresh. Vous dérivez immédiatement de la production, la QA commence à rater de vrais bugs, le refresh finit par revenir et vous avez perdu un mois.
Option deux: demander aux gens de ne pas cliquer dans la HMC. C'est un contrat social qui tient environ un sprint. L'outil est là, il fonctionne, les deadlines existent.
Option trois: tout changement passe dans le contrôle de version comme fichier Impex et est rejoué après chaque refresh. C'est la réponse que la plateforme a toujours voulu que vous choisissiez. C'est aussi celle qui exige que votre équipe soit à l'aise pour lire et écrire du Impex, ce qui me ramène au début de ce post.
Les huit outils
Tout ce qui suit tourne localement dans votre navigateur. Rien n'est téléversé. Le parseur est un module TypeScript d'environ 550 lignes qui gère les champs entre guillemets, les points-virgules échappés, les continuations de ligne, les macros, les blocs de modificateurs et les fichiers multi-blocs. Si vous trouvez du Impex réel que ce parseur n'arrive pas à digérer, je serais preneur.
Éditeur de table Impex
C'est celui qui fait le gros du travail dans mon équipe. Collez un bloc, obtenez une grille de style tableur, éditez les cellules en ligne, ajoutez ou supprimez des lignes, recopiez le Impex régénéré. Quand la personne qui écrit le changement ne lit pas Impex mais lit Excel, c'est le pont. C'est aussi l'outil que je sors en premier quand je dois faire un changement de dix lignes sans défiler à travers des points-virgules.
Si rien d'autre dans ce post ne reste, c'est l'éditeur de table qu'il faut mettre en favori.
Convertisseur Impex vers CSV
Transforme n'importe quel bloc Impex en CSV, un en-tête par colonne. Utile quand quelqu'un du contenu veut voir l'état actuel d'une section de catalogue dans un tableur sans attendre un ingénieur.
Convertisseur CSV vers Impex
L'inverse: un CSV (souvent collé depuis Google Sheets) devient un script Impex, avec le nom du type et la colonne unique sélectionnés explicitement. Les gens du produit peuvent rédiger le changement dans Sheets, l'ingénieur le convertit et le committe. Le diff de relecture reste lisible.
Impex vers JSON et JSON vers Impex
JSON est la lingua franca de tout ce qui n'est pas Impex. Si vous scriptez une migration, générez du Impex depuis une source de vérité, ou comparez deux versions, une représentation structurée est plus simple qu'un traitement à coups de regex sur des points-virgules. Chaque bloc devient {mode, type, headers, rows}, les macros sont des citoyennes de première classe, et les deux outils font l'aller-retour pour que vous puissiez éditer le JSON et reconvertir. Un bouton d'échange en haut de chaque page inverse la direction.
Validateur / Linter Impex
Signale les noms de types manquants, les modificateurs inconnus, les clés uniques dupliquées entre lignes de données, les macros non définies et les incohérences de nombre de colonnes. Aucune de ces erreurs n'est exotique; ce sont toutes des choses que l'interpréteur SAP va accepter avant de produire silencieusement un import défectueux. Ajouter ce validateur comme contrôle CI sur les fichiers .impex est le changement à plus fort levier qu'une équipe utilisant Impex en contrôle de version peut faire.
Expanseur de macros Impex
À partir d'un fichier Impex avec des $macros, il produit le même fichier avec chaque référence remplacée en ligne. Expansion jusqu'à point fixe, pour que les macros qui référencent d'autres macros se résolvent proprement. C'est ce que vous committez en tant qu'artefact d'audit. Les auditeurs ne vont pas poursuivre des $macros à travers votre repo.
Impex vers SQL (approximatif)
Hybris abstrait la base de données. Parfois cette abstraction fuit; un DBA demande ce qui est réellement écrit, ou vous raisonnez sur les performances. Cet outil aplatit le Impex en INSERT / UPDATE / DELETE approximatifs pour PostgreSQL, MySQL ou SQL ANSI standard, avec INSERT_UPDATE rendu en ON CONFLICT / ON DUPLICATE KEY / MERGE selon le dialecte. C'est explicitement approximatif; les chemins de qualification du style catalogVersion(catalog(id),version) ne peuvent pas être rendus fidèlement en joins sans votre items.xml. Mais pour une conversation qui vise à se forger un modèle mental, c'est plus rapide que de monter un Hybris local et de regarder les logs de requêtes.
Le workflow que je pousse dans mon équipe
Version courte, classée par ROI.
Impex fonctionne dans les deux sens: exportez ce que vous avez fait dans la HMC vers un fichier .impex, ou éditez du .impex et importez-le pour éviter la HMC entièrement. La HMC est lente pour la configuration; un formulaire de vingt champs devient pénible dès la troisième fois que vous y touchez. Pour tout ce qui est répétitif ou en volume, écrire le Impex directement et lancer l'import est plusieurs fois plus rapide que de cliquer. Et ce que vous avez quand même dû faire dans la HMC est exporté en .impex pour survivre au prochain refresh.
Les éditions non triviales passent par l'éditeur de table. L'édition à plat d'un Impex convient pour ajouter une colonne ou basculer un drapeau. Pour tout ce qui dépasse une poignée de lignes, l'éditeur de table est la bonne réponse et l'éditeur à plat ne l'est pas.
Lancez le validateur Impex avant chaque import. C'est 90 % de la valeur de l'outillage de ce post. Il attrape les clés uniques dupliquées, les modificateurs inconnus et les macros non définies avant que l'interpréteur SAP ne les accepte silencieusement et ne produise un mauvais import. Pour l'instant, on le passe à la main sur chaque .impex avant de lancer l'import; ce n'est pas automatisé, mais il attrape la plupart des surprises.
Les diffs se font en JSON. Convertissez les deux versions d'un fichier en JSON via Impex vers JSON et comparez le résultat. Les diffs ligne à ligne avec des points-virgules sont illisibles; les diffs structurés, non.
Les macros sont déployées dans les artefacts d'audit. Committez la forme compacte. Quand la conformité demande ce que le déploiement a vraiment fait, remettez-leur la version développée.
Ce qui fait encore mal
Tous les problèmes Impex n'ont pas de réponse en outil navigateur.
L'évolution du système de types est le gros morceau. Quand quelqu'un renomme un champ dans items.xml, chaque fichier Impex qui référence l'ancien nom se met silencieusement à écrire dans la mauvaise colonne ou à échouer de façons troublantes. Aucun linter dans le navigateur ne peut attraper cela sans accès à vos définitions de types spécifiques. Un petit script local au projet qui parcourt vos fichiers .impex et croise les attributs avec le système de types actuel vaut un week-end. Je n'en ai pas livré parce que chaque équipe a un setup différent.
La performance est l'autre. Les gros imports Impex se comportent différemment des chargements SQL en masse; l'interpréteur valide chaque ligne, déclenche des événements plateforme et invalide des caches. Si un import d'un million de lignes prend six heures, la solution n'est presque jamais "tuner la base de données". C'est "découper le fichier et importer en parallèle" ou "désactiver l'éviction de cache pendant le chargement". La documentation performance de SAP Commerce couvre bien le sujet.
Pourquoi j'ai construit ceci et pas autre chose
Réponse honnête: mon équipe (moi compris) n'allait pas apprendre à lire Impex en lisant plus d'Impex. La documentation ne l'a pas réglé. Le pair programming non plus. Le pari était qu'en tendant à quelqu'un une UI tableur par-dessus un bloc Impex et en disant "édite ça comme tu éditerais n'importe quoi d'autre, l'outil écrira le Impex pour toi", on puisse abaisser la barrière assez pour que Impex devienne un format que l'équipe traite comme du CSV; une représentation de transport qui se trouve être la façon dont SAP Commerce veut les données, pas un langage qu'il faudrait maîtriser.
Est-ce que ça va vraiment marcher ? Je ne sais pas encore.
Je veux être franc sur où j'en suis. Ces outils existent parce que mon équipe essaie de répondre à une question plus large: la configuration-as-code via Impex peut-elle remplacer les clics dans la HMC, sur la durée, pour une équipe qui n'est pas à l'aise avec Impex ? Les outils sont un pari sur "oui". Ils ne sont pas une preuve.
Il y a plusieurs façons pour cette expérience de s'effondrer. Peut-être que l'éditeur de table convient pour 80 % des éditions mais que les 20 % restants, ceux impliquant des chemins de qualification imbriqués, des macros qui référencent d'autres catalogues, des subtilités de modificateurs, continuent de renvoyer les gens vers la HMC et la discipline s'érode. Peut-être qu'écrire du Impex est la partie facile et que le vrai travail est le pipeline CI qui rejoue réellement les scripts après un refresh, ce qui n'est pas le sujet de ce post. Peut-être que le système de types évolue plus vite que l'outillage et que le validateur produit un bruit que les gens apprennent à ignorer. Chacune de ces situations signifierait que "infrastructure-as-code dans la HMC via Impex" n'est pas vraiment le bon cadrage et qu'il nous faut une autre abstraction.
J'écrirai une suite dans quelques mois, une fois qu'il y aura de vraies données. Soit ces outils deviennent le chemin par défaut et la configuration-as-code fonctionne comme SAP l'a toujours voulu, soit on apprend quelque chose d'intéressant sur les raisons pour lesquelles cela ne marche pas, et ce sera un post à part entière. Je n'ai pas d'a priori fort dans un sens ou dans l'autre.
Si vous faites tourner SAP Commerce avec le même setup HMC + refresh et que vous voulez tenter quelque chose de similaire, les outils sont gratuits, locaux et continueront à fonctionner quelle que soit ma conclusion. Mettez en favori ceux qui correspondent à votre workflow. Si vous vous retrouvez avec vos propres données, positives ou négatives, j'aimerais les entendre.
Pour le contexte d'écosystème: la documentation ImpEx sur SAP Help est la référence canonique, les forums communautaires SAP Commerce sont meilleurs que Stack Overflow pour les questions spécifiques aux versions, et le Gartner Magic Quadrant for Digital Commerce couvre la place de SAP Commerce dans le paysage plus large de l'e-commerce d'entreprise.
Suite dans quelques mois.