Importer des commandes clients dans Business Central à partir de six formats, et gérer les échecs

Un distributeur québécois reçoit les commandes de six gros clients, chacun dans son format : fichiers CSV et Excel venant de portails de détaillants, de distributeurs et de places de marché, jusqu'à environ 300 commandes dans un seul fichier. Elles étaient saisies à la main. Elles entrent maintenant seules dans Business Central comme commandes de vente.

La preuve de concept a répondu à « est-ce que ça peut marcher? » en quelques jours. Le reste du travail a répondu à la question plus difficile : qu'est-ce qui arrive quand quelque chose tourne mal, et qui le sait?

Le parcours

1. Un surveillant de dossier (un petit service Windows) prend les nouveaux fichiers dans le dossier où ils arrivent déjà, et les envoie dans Azure Blob Storage. Rien ne change pour les clients.
2. Une Azure Function (C#) lit chaque fichier avec un traducteur (normalizer) par source et le transforme en un schéma de commande commun. Ajouter une source, c'est ajouter un traducteur ; rien ne change plus loin.
3. Une extension AL expose une API sur mesure. La Function envoie les commandes normalisées dans des tables d'attente (staging), et un codeunit de traitement crée le Sales Header et les Sales Line.

Garder la lecture des fichiers hors de Business Central garde le côté AL sur les règles d'affaires seulement, et le fouillis propre à chaque format (bizarreries d'Excel, noms de colonnes, formats de date) dans du code facile à tester unitairement.

Les règles d'affaires en AL

• Le client, trouvé dans une table de configuration par source et par pays.
• La zone de taxe, selon la province de livraison, tirée de l'adresse du fichier ou du magasin.
• Le transport, selon une grille gardée dans Business Central.
• Le prix, celui du fichier ou celui de Business Central selon la source, avec un avertissement sur la commande quand il vient de la fiche article.

Les cas d'échec

C'est là que le temps est passé.

• Les doublons. Chaque source a sa propre clé de doublon, gardée dans External Document No.. Une commande dont la clé a déjà été créée est rejetée : un fichier déposé deux fois, ou repris, ne crée jamais les commandes en double.
• Les commandes à moitié créées. Créer une commande prend plusieurs étapes (en-tête, lignes, traitement). Si une commande est rejetée après que son en-tête existe, la commande à moitié créée est supprimée. Rien d'incomplet ne reste derrière.
• Les mauvaises lignes. Pour un article manquant ou inconnu, chaque source a sa règle : rejeter toute la commande, ou écarter la ligne avec un avertissement. Une commande sans ligne restante est rejetée. Rien n'est jamais créé avec un article vide.
• Les reprises. Si un appel à Business Central échoue au milieu d'un fichier (réseau, délai dépassé), la boîte de réception reprend le fichier à son prochain passage, jusqu'à trois fois, puis le déplace dans un conteneur failed. Les commandes déjà créées à l'essai précédent sont rejetées comme doublons, et c'est exactement pour ça que la clé de doublon compte.
• Un fichier qui fait planter la Function va aussi dans failed, et le message d'erreur va au journal plutôt que dans une console que personne ne lit.

Une page pour le service à la clientèle

Une page Business Central liste chaque commande importée avec son état : créée, rejetée (et pourquoi), archivée. Elle s'ouvre sur les sept derniers jours, avec des vues par période et par état. Après avoir corrigé la cause (ajouter un article manquant, corriger un prix), le service à la clientèle fait Réessayer sur la commande rejetée. Archiver et Désarchiver gardent la liste courte, et « Afficher les archivées » fonctionne dans les vues enregistrées.

C'est cette page qui rend l'intégration utilisable : ce sont les gens responsables des commandes qui voient les problèmes, pas le développeur.

Les tests

• 33 tests AL dans une application de test à part couvrent les règles d'import : client, taxes, prix, doublons, rejet et nettoyage. Ils roulent dans un sandbox, jamais en production.
• Les traducteurs ont leurs propres tests, sur de petits fichiers fabriqués dans les tests (aucune donnée de client), et ils roulent en intégration continue.

Quand une règle change, les tests disent tout de suite si autre chose a brisé. Sur une intégration à six sources, c'est la différence entre changer une règle en un après-midi et avoir peur d'y toucher.

À savoir si vous construisez ça

• Décidez la clé de doublon de chaque source en premier. Les reprises, les fichiers redéposés et la récupération en dépendent.
• Faites atterrir chaque échec à un endroit où quelqu'un regarde, dans Business Central si possible.
• Gardez les données des clients hors des fichiers de test. Fabriquez de petits fichiers qui touchent chaque règle.

J'ai déjà raconté une autre synchronisation avec Azure Functions, pour un planificateur qui échange dans les deux sens.

Des imports de commandes à bâtir dans Business Central? Parlons-en.