Le client CLI/42 existe dans l’ERP et dans Dynamics, mais sa mise à jour Dataverse échoue. Le client CLI42, lui, passe. Retirer la barre oblique semble résoudre le problème ; cette correction peut pourtant envoyer les prochaines informations sur une autre société. L’incident commence par une erreur d’URL et se termine par un mauvais rattachement commercial.
Le risque est de croire qu’une référence simplifiée représente encore le même client. La difficulté vient de trois propriétés différentes : reconnaître le client métier, imposer son unicité et construire une adresse utilisable par la Web API REST. Une clé alternative peut servir à l’une sans fonctionner pour toutes. Ce dossier explique comment isoler le blocage, conserver la référence ERP originale et préparer une reprise qui refuse les correspondances ambiguës.
Les exemples portent sur des comptes d’une table Dataverse standard, avec des colonnes personnalisées explicitement créées pour l’intégration. Ils ne décrivent ni toutes les API Dynamics 365, ni les tables élastiques ou virtuelles. Pour qualifier les interfaces réellement présentes, notre accompagnement en intégration API et notre offre Microsoft Dynamics CRM relient le diagnostic Dataverse au modèle client de votre ERP.
Pour qui : des clients ERP présents mais impossibles à retrouver par leur clé
Reconnaître un rejet sélectif plutôt qu’une panne générale
Commencez par comparer une référence acceptée et une référence refusée avec le même compte applicatif, la même table et la même opération. Si seules certaines valeurs cassent, renouveler le jeton OAuth ou augmenter les retries détourne l’enquête. Une erreur de syntaxe, un index indisponible et une permission insuffisante n’appellent pas la même correction ; conservez le statut HTTP et le message retourné pour les distinguer.
Le symptôme métier est souvent plus parlant que la courbe de disponibilité : certaines fiches remontent, leurs contacts restent attachés à un ancien compte, et l’ADV cherche manuellement le client pour terminer un devis. Comptez les identités bloquées et les dossiers commerciaux concernés séparément des tentatives réseau. Cent échecs sur la même référence ne représentent pas cent clients distincts à reprendre. Le délai d’envoi du devis et le temps de recherche de l’ADV permettent de qualifier l’impact commercial du client réellement bloqué.
Délimiter la table et la responsabilité du raccordement
Demandez le nom logique de la table, son type et les colonnes de la clé. Un champ affiché comme « Code ERP » dans un formulaire n’est pas, à lui seul, une clé alternative publiée et utilisable. Vérifiez aussi qui crée les clients : l’ERP, Dynamics ou deux circuits autorisés. Sans cette information, un rattrapage peut fabriquer la seconde fiche que l’équipe cherchait précisément à éviter.
Ce diagnostic concerne notamment les références contenant une ponctuation métier, les reprises après import de solution et les connecteurs ajoutés à un CRM déjà rempli. Si votre connecteur ne connaît que le GUID Dataverse, le problème se situe ailleurs. Si l’objet relève de Business Central ou de Finance and Operations, vérifiez son interface propre avant d’appliquer une procédure Dataverse par analogie de marque.
Plan d’action : réunir les preuves avant de modifier une référence
Constituer une paire de dossiers comparable
Le contrat de reprise reçoit en entrée l’identifiant interne ERP, la société source et la référence affichée. Sa sortie attendue rapproche le GUID cible connu, la définition de clé et l’URL réellement envoyée ; sa journalisation conserve aussi le motif qui bloque cette correspondance. Ajoutez un horodatage et une corrélation de traitement sans exporter le jeton d’accès. La référence peut être sensible selon votre métier : gardez sa valeur complète dans un espace d’analyse autorisé et un identifiant de dossier dans les journaux partagés.
Choisissez des cas qui séparent les causes : une barre oblique, un pourcentage littéral, une référence vide et deux clients de sociétés différentes ayant le même code. Cette comparaison identifie la propriété qui explique le rejet. Un échantillon composé uniquement de références numériques ne prouverait rien sur les codes qui ont déclenché l’incident ; ajoutez ces cas avant de valider le correctif.
Geler le repli qui crée une fiche après chaque échec
Désactivez, pour le flux concerné, la règle applicative « la recherche échoue, donc je crée ». Une recherche qui répond mal ne démontre pas l’absence du client. Placez ces événements dans une file identifiée, avec leur identité source intacte. Les mises à jour des autres clients peuvent continuer si leur chemin ne dépend pas de cette règle et si leur correspondance reste vérifiée.
Fixez une sortie observable : le dossier repart lorsque sa destination est certaine et que le mode d’écriture prévu respecte cette destination. Une clé non active, une recherche ambiguë ou un GUID disparu laisse le dossier bloqué avec un motif différent. Cette séparation rend possible une reprise ciblée ; elle évite qu’une correction de caractères relance en même temps un nettoyage de doublons ou une recréation métier.
| Observation | Décision de reprise | Preuve avant émission |
|---|---|---|
| Index non actif | Bloquer l’upsert | Index natif Active |
| Un candidat exact confirmé | Préparer la mise à jour par GUID | Rattachement et droits vérifiés |
| Zéro ou plusieurs candidats | Différer toute création automatique | Décision du responsable du référentiel |
Séparer référence commerciale, identité source et adresse Dataverse
La ponctuation appartient parfois à la donnée métier
Dans le cas fictif du banc local, CLI/42 et CLI42 désignent deux objets ERP différents. Une fonction supprimant tout caractère non alphanumérique les transforme en une même chaîne. Le transport devient plus simple, mais l’information qui distinguait les clients disparaît. L’exercice reproduit réellement cette collision ; il ne s’agit pas d’une probabilité théorique invoquée pour imposer une nouvelle architecture.
Gardez donc la référence originale comme attribut métier. Un changement d’affichage, une renumérotation ou une correction de libellé doit pouvoir être traité sans changer l’identité du client déjà lié. Demandez à l’éditeur ou à l’installateur ERP s’il existe un identifiant interne stable, distinct du code visible et qualifié par société. Ne présumez pas qu’un numéro de ligne d’export ou une adresse e-mail joue ce rôle.
Une correspondance persistée doit survivre aux redémarrages
Lorsque l’ERP fournit cette identité stable, le middleware peut lui associer une clé technique compatible avec le contrat cible. Le banc utilise un UUID écrit en hexadécimal minuscule et conservé dans SQLite. Il s’agit d’un choix local de conception, pas d’un format exigé par Dataverse. La correspondance est allouée une fois, relue ensuite et séparée pour chaque société source.
Produire un nouvel UUID à chaque tentative annulerait cet intérêt. La correspondance doit être disponible avant l’envoi et restaurable après incident, avec des droits d’écriture limités. Si vous ne pouvez pas reconstruire quelle clé a été attribuée au client, suspendez son émission plutôt que d’allouer une autre identité. Le dossier sur la migration des identifiants API complète ce point pour un changement de système plus large.
Vérifier que la clé alternative existe et que son index est actif
Une définition importée peut encore être inutilisable
Microsoft décrit une création d’index asynchrone, avec les états Pending, In Progress, Active et Failed. La clé devient effective lorsque cet index est créé. Contrôlez cet état après le déploiement de la solution ; la présence des colonnes ou la réussite de l’import ne suffisent pas. En échec, examinez le travail système avant de réactiver sa création.
Placez ce contrôle dans la préparation du connecteur, avec le nom de l’environnement et la définition exacte attendue. Une validation faite dans la sandbox ne confirme pas l’index de production. Le programme téléchargeable reçoit l’état comme entrée et bloque les trois états non actifs. Il vérifie cette décision locale ; il ne lit pas lui-même les métadonnées de votre organisation.
Une valeur absente ne bénéficie pas de l’unicité attendue
La documentation Power Apps précise que les valeurs NULL dans les colonnes de clé ne font pas respecter l’unicité. Refusez donc l’émission d’un client dont l’identité source nécessaire est absente. Remplacer tous les manquants par « inconnu » introduirait une autre collision. Une file de correction doit demander la donnée à la source, puis reprendre l’identité corrigée avec son historique.
Avant un premier remplissage de la nouvelle colonne technique, distinguez les comptes déjà rapprochés, ceux qui nécessitent une recherche et ceux qui sont réellement nouveaux. La création d’une clé ne résout pas les doublons préexistants. Confirmez également que vous travaillez sur une table prise en charge : les clés alternatives ne sont pas disponibles sur les tables virtuelles. Le modèle de ce dossier reste celui des tables standard.
Pourquoi encoder la référence dans l’URL ne corrige pas toutes les clés
Le chemin de clé possède ses propres restrictions
La documentation développeur cite notamment /, % et & parmi les caractères incompatibles avec l’adressage par valeur de clé. Son exemple montre qu’un encodage URL ne suffit pas à rendre cette forme utilisable. D’autres caractères sont listés selon la page ; ne transformez pas une liste partielle recopiée dans un connecteur en certification universelle de vos références.
Un bon diagnostic conserve les deux représentations : valeur métier avant encodage et URL effectivement construite. Vous pourrez ainsi distinguer une valeur déjà encodée puis encodée une seconde fois d’une restriction de Dataverse. Évitez de remplacer les caractères dans l’ERP pour satisfaire l’URL. La référence figure peut-être sur des factures, des contrats et des échanges partenaires ; sa modification aurait des conséquences au-delà du CRM.
Choisir entre une clé technique sûre et un GUID déjà connu
Pour un nouveau raccordement, une colonne technique dédiée peut recevoir la clé persistée du middleware, tandis qu’une autre conserve la référence visible. Dimensionnez la colonne texte pour les 32 caractères du format retenu, puis définissez-la comme clé alternative, contrôlez son index et intégrer les comptes existants avant d’ouvrir l’upsert. L’ajout n’est pas nécessaire si une identité stable et compatible remplit déjà ce rôle ; vérifiez-la plutôt que de créer une troisième convention.
Pour une reprise ponctuelle, vous pouvez déjà disposer d’un GUID Dataverse fiable dans votre table de correspondance. Adressez alors ce compte par GUID, en contrôlant que la relation source-cible est toujours valable. Une clé alternative n’est pas une obligation pour chaque requête. Ce choix réduit les transformations de références, mais il rend la qualité de votre correspondance et le traitement des suppressions particulièrement importants.
Retrouver un compte existant par filtre sans choisir le premier résultat
Une lecture par collection permet de récupérer le GUID
Microsoft propose de rechercher les valeurs concernées avec $filter, puis d’utiliser l’identifiant de la ligne pour l’opération suivante. Construisez une égalité sur la société source et la référence, avec un $select limité aux champs de rapprochement. Les noms new_source et new_raw_ref du banc sont des colonnes personnalisées fictives ; remplacez-les seulement après vérification de votre schéma.
Le programme compose le littéral OData, double une apostrophe dans la valeur, puis encode les paramètres de requête. Le test utilise CLI/O'Neil&50% et relit la chaîne décodée pour vérifier sa conservation. Ce contrôle porte sur la construction locale de la requête, pas sur une réponse Microsoft. Ne concaténez pas une référence brute avec les séparateurs de l’URL et n’utilisez pas une recherche partielle pour décider d’un rattachement.
La casse et les permissions peuvent fausser la conclusion
Les filtres texte Dataverse sont insensibles à la casse. Si votre ERP distingue deux références par les majuscules, une égalité textuelle ne reproduit pas son identité. Dans le banc, un résultat dont la référence diffère par la casse est refusé. Cette comparaison explicite constitue une politique locale prudente ; elle ne modifie pas la comparaison effectuée par Dataverse et ne remplace pas un identifiant source compatible.
Demandez au moins de quoi détecter un second candidat : $top=2 sert ici à bloquer une sélection ambiguë, pas à certifier tout le référentiel. Zéro ligne visible ne prouve pas une absence globale si le compte applicatif n’a pas accès à tous les comptes concernés. En cas de pagination ou de résultat incomplet, n’autorisez pas la création sur cette seule lecture. Faites qualifier le périmètre de recherche et les permissions par l’administrateur CRM.
Préparer l’écriture sans changer implicitement l’identité du compte
Dans un upsert, la clé de l’URL identifie la ligne
Pour une table standard, Microsoft recommande de ne pas répéter dans le corps les données de clé utilisées dans l’URL d’upsert. En création, une valeur contradictoire dans le corps peut définir une identité différente de celle attendue ; en mise à jour, les attributs de clé correspondants sont retirés du traitement. Le banc garde donc new_external_key dans l’adresse et la référence métier dans le corps JSON.
PATCH /api/data/v9.2/accounts(new_external_key='a12b34c56d784901a23b45c67d890123')
Content-Type: application/json
{
"new_raw_ref": "CLI/42",
"name": "Fixture client"
}Cette requête illustre des colonnes personnalisées à créer et une version d’API à valider sur l’organisation cible. Elle n’est pas exécutée par l’exercice. Avant l’envoi réel, examinez les plugins, les règles métier et les champs obligatoires de la table. La présence d’une clé utilisable ne garantit pas que les données commerciales soient acceptées ni que les traitements déclenchés en aval soient rejouables.
Une mise à jour seule doit refuser la recréation
Après rapprochement d’un compte existant, If-Match: * permet de limiter le PATCH à une mise à jour : si la cible manque, Dataverse répond 404. Le connecteur doit alors qualifier la disparition. Retirer l’en-tête pour « faire passer » la requête changerait l’intention métier. Une suppression CRM volontaire ou une fusion exige une nouvelle décision de correspondance.
Cet astérisque ne vérifie pas que la fiche est restée identique depuis votre lecture. Pour protéger une version précise, examinez l’ETag et la prise en charge de la concurrence optimiste sur la table. Une réponse 412 demande une nouvelle lecture et un arbitrage des champs ; elle ne justifie pas un écrasement automatique. Ces conditions doivent être testées sur l’environnement de recette, avec les droits du vrai compte applicatif.
Exercice local : 26 contrôles de correspondance et de préparation des requêtes
Lancer un banc sans jeton ni appel au CRM
Téléchargez le programme Python de vérification des clés puis lancez-le avec Python 3.10 ou supérieur et SQLite 3.24 ou supérieur, accessible via son module standard. Il crée une base temporaire, exécute deux allocations depuis des connexions indépendantes et supprime son répertoire à la sortie. Aucun compte Microsoft, secret, réseau ou accès ERP n’est nécessaire. Les GUID de destination sont des fixtures fournies au programme.
python3 alternate_key_inventory.py
PASS two assignments return one stored key
PASS lossy normalization creates fixture collision
PASS colliding display references yield distinct targets
PASS OData escaping and query encoding preserve raw reference
PASS two candidates block selection
CHECKS 26
Dataverse requests: 0; native writes: 0; no token required.La sortie affichée est un extrait du résultat exécuté ; le fichier complet détaille les 26 contrôles. Deux threads sont synchronisés avant leur tentative d’allocation. La contrainte primaire SQLite sur société et identifiant source conduit les deux connexions à relire la même clé persistée. Ce résultat démontre ce mécanisme local ; il ne mesure ni la concurrence d’une infrastructure distribuée, ni une transaction entre le middleware et Dataverse.
Lire les résultats comme une preuve limitée
Par exemple, le banc conserve trois identités : deux clients distincts dans ERP-A et un identifiant identique appartenant à ERP-B. Il vérifie leur séparation, la stabilité après réouverture et la conservation de la référence lors d’un renommage. Les états d’index non actifs, les identités incomplètes et les candidats ambigus provoquent un arrêt. L’exemple concret montre ainsi ce qui peut être garanti avant même de disposer d’un accès au CRM.
Il reste à vérifier en recette la création de la colonne, l’activation native de l’index, la recherche avec le compte applicatif et les réponses aux écritures conditionnelles. Le programme ne prouve pas l’acceptation d’un payload, l’absence de doublons invisibles ou la qualité du rapprochement historique. Son intérêt est de rendre ces limites séparables des erreurs déjà détectables dans le code du connecteur.
| Contrôle local | Résultat vérifié | Preuve encore nécessaire |
|---|---|---|
| Deux allocations | Une clé persistée | Concurrence de votre stockage |
| Référence avec ponctuation | Valeur conservée | Lecture Dataverse autorisée |
| Index non actif | Requête bloquée | État natif de l’index |
| Candidat unique exact | Adresse par GUID | Correspondance métier confirmée |
| Deux candidats | Aucune sélection | Arbitrage du référentiel |
Passer en recette puis reprendre les dossiers ERP bloqués
Attacher les fiches historiques avant d’ouvrir les créations
Préparez trois cohortes distinctes avant de remplir les correspondances. Pour les comptes historiques confirmés, affectez la clé technique au GUID retenu selon une procédure testée, puis relisez la fiche. Un ancien code commun à deux sociétés ne doit jamais être résolu par le seul nom commercial. Conservez la décision de rattachement et son auteur dans un registre protégé.
- Correspondance confirmée : conserver le GUID retenu et la décision de rattachement avant d’affecter la clé.
- Rapprochement ambigu : différer l’écriture et demander au responsable du référentiel de désigner le compte.
- Client réellement nouveau : vérifier l’autorisation de création émise par la source avant d’ouvrir l’upsert.
Répétez ensuite le parcours après un timeout à résultat inconnu, un redémarrage et une référence renommée. Le connecteur doit retrouver la même clé et la même destination, sans générer une nouvelle identité pour sortir de l’erreur. Ajoutez un test de suppression cible pour vérifier que la mise à jour seule reste bloquée. La stabilité de cette destination ne démontre pas l’idempotence des plugins métier déclenchés par chaque écriture. Coordonnez les changements du modèle ERP avec son installateur ; Dawap intervient sur le contrat de flux, la transformation et l’application de correspondance.
Mesurer des dossiers résolus plutôt que des retries réussis
Dans le runbook Dataverse, la journalisation relie chaque identité source à sa destination, au dernier motif de rejet et à la file autorisée à la reprendre. Son seuil d’arrêt est atteint dès que cette destination ne peut plus être confirmée. Distinguez les états « index à préparer », « référence à retrouver », « ambiguïté métier » et « cible supprimée ». L’équipe saura alors si elle doit mobiliser l’administrateur CRM, le responsable du référentiel ou le mainteneur du middleware, au lieu de réaffecter le même ticket à chaque tentative.
Suivez aussi les clés créées sans correspondance terminée et les dossiers dont la recherche ne voit qu’un périmètre partiel. Une file qui diminue par abandon silencieux n’est pas une reprise réussie. Pour cette cohorte, le critère de sortie est la présence d’une destination confirmée ou d’un refus expliqué pour chaque identité, accompagnée d’une relecture des champs réellement synchronisés. Le quota API reste une contrainte de cadence, pas une preuve de cohérence.
Étendre la correction lorsque l’identité source change aussi
Si l’ERP remplacera prochainement ses identifiants internes, la migration des identifiants avec alias et double lecture traite la coexistence entre anciennes et nouvelles clés. Ce chantier dépasse le caractère refusé dans l’URL : il demande de préserver les correspondances pendant deux générations du référentiel.
Le contrat d’échange ERP et ses reprises complète les critères d’acceptation lorsque le client CRM alimente ensuite devis, commandes ou facturation. Distinguez la correction du rattachement du droit de rejouer ces opérations aval ; retrouver le GUID ne confirme pas leur état.
Erreurs fréquentes : les correctifs qui déplacent le problème
Nettoyer les codes ou utiliser un nom de société comme clé
Supprimer la ponctuation, enlever les zéros initiaux ou passer toutes les références en majuscules nécessite une règle métier, pas une fonction utilitaire ajoutée après un rejet HTTP. Comparez les valeurs originales avant toute normalisation proposée. Une collision avérée bloque cette transformation. Si le métier décide réellement de fusionner deux identités, organisez cette fusion avec ses relations CRM plutôt que de la cacher dans le mapping.
Le jeu de comparaison doit conserver les deux objets avant transformation et leur destination attendue. Dans le cas CLI/42 face à CLI42, l’acceptation consiste à maintenir deux cibles distinctes. Un export normalisé qui ne laisse qu’une ligne échoue à cette vérification même si ses caractères sont tous utilisables dans une URL.
Considérer zéro résultat comme une autorisation de création
Une erreur de filtre, un droit insuffisant ou une recherche sur la mauvaise société peut produire une absence apparente. Conservez la distinction entre « pas de candidat dans cette réponse » et « client autorisé à être créé ». L’ERP doit fournir la décision de création selon le processus convenu ; le middleware ne la déduit pas d’un échec de lecture. Ce point mérite un test dédié dans chaque reprise historique.
Vérifiez notamment le parcours d’un compte présent mais masqué au compte applicatif. La recette doit montrer une remontée vers l’administrateur, sans création de remplacement. Cette situation se distingue d’un client nouvellement ouvert dans l’ERP et explicitement autorisé à entrer dans le CRM.
Remplacer l’erreur conditionnelle par un upsert libre
Une cible supprimée, un ETag différent et une clé non active sont trois situations distinctes. Ne retirez pas leurs contrôles pour obtenir un statut de succès. Le contrat d’échange ERP doit préciser quelle équipe peut autoriser un nouveau rattachement et quels champs restent sous autorité commerciale. La journalisation garde ce motif avec la corrélation, sans recopier les tokens ni les fiches complètes.
Une réponse technique perdue exige elle aussi une lecture de la destination avant toute décision de remplacement. Conservez la clé persistée et les données proposées, puis rapprochez les champs observés. Une opération devenue incertaine ne doit pas entraîner l’allocation d’un autre identifiant externe pour le même client ERP.
Sources Microsoft et vérifications à refaire sur votre organisation
Adresser et rechercher les lignes
Sources consultées le 15 octobre 2026 : référencement par clé alternative pour les restrictions et le recours au filtre ; filtres OData pour la casse, les apostrophes et l’encodage. Les exemples personnalisés de ce dossier restent à aligner sur les noms logiques, les permissions et les données de votre instance.
Relisez l’URL sérialisée produite par votre bibliothèque HTTP sur les références du dossier d’incident. Le programme vérifie son propre encodage ; il ne vérifie pas celui d’un proxy, d’un SDK existant ou d’un composant low-code situé entre l’ERP et Dataverse.
Définir la clé et limiter les écritures
Les pages définition et index de clé, contraintes de création dans Power Apps, fonctionnement de l’upsert et opérations conditionnelles complètent la vérification. Le schéma local, les UUID attribués et le classement des refus relèvent du banc pédagogique, sans promesse de connecteur natif prêt à déployer.
Après un import de solution, relevez l’état de l’index dans l’environnement qui recevra les écritures. Associez cette observation à la version de solution et au profil applicatif testé. Une capture ancienne d’un autre environnement ne clôt pas ce contrôle de préparation.
Conclusion : retrouver le bon client avant de faire accepter son écriture
Un code ERP difficile à placer dans une URL n’est pas nécessairement une mauvaise référence commerciale. Préservez sa valeur, cherchez l’identité interne stable et vérifiez séparément la définition de clé, son index et l’adresse utilisée. Le banc montre pourquoi deux références distinctes ne doivent pas être simplifiées jusqu’à devenir identiques.
Pour les comptes existants, le rapprochement par filtre et l’écriture par GUID constituent une option documentée, à condition d’arrêter les résultats ambigus et de qualifier les permissions. Pour les flux récurrents, une clé technique persistée peut stabiliser les reprises. Dans les deux cas, une disparition de cible ou une identité incomplète appelle une décision explicite avant toute création. Le périmètre peut être qualifié avec notre équipe Dynamics CRM.
Vous pouvez cadrer cette correction avec notre prestation d’intégration API : audit des références, rapprochement des comptes, adaptation du middleware et recette des dossiers qui échouent aujourd’hui. La correction doit remettre à jour le bon client en conservant une correspondance que vos équipes pourront expliquer au prochain incident.
