Configurer les contrôles personnalisés dans Dynamics

Ce guide décrit la configuration des services web DQE One dans un environnement Microsoft Dynamics 365 ou Power Apps. Chaque service web nécessite deux niveaux de configuration : les réglages au niveau de l'application (à faire une seule fois) et les réglages au niveau du formulaire (à faire par entité — Account, Contact, Lead).

Ajouter un contrôle PCF

Tous les services web DQE se configurent en plaçant un contrôle PCF sur le champ cible dans l'éditeur de formulaire. Le processus est identique pour chaque type de contrôle, sur chaque entité — standard (Account, Contact, Lead) ou personnalisée.

1. Ouvrez le formulaire de l'entité cible dans l'éditeur de formulaire Power Apps.
2. Sélectionnez le champ à configurer (rue, ville, email, téléphone, etc.).
3. Dans le panneau de droite, cliquez sur + Components, puis sélectionnez le contrôle DQE correspondant.
4. Mappez les paramètres requis. Les paramètres requis doivent être liés à un champ existant ; les paramètres optionnels peuvent rester non définis. Reportez-vous à la section de chaque service web pour la référence complète des paramètres.
5. Enregistrez et publiez le formulaire. Répétez pour chaque entité et chaque bloc d'adresse où le service web doit être actif.

Remarque : chaque contrôle doit être configuré indépendamment sur chaque formulaire d'entité. Les réglages au niveau de l'application (DQE DataQ Settings) s'appliquent globalement et n'ont besoin d'être définis qu'une seule fois.

Options de code pays

Plusieurs contrôles acceptent des paramètres de code pays pour présélectionner le pays des requêtes API. Trois options mutuellement exclusives :

1. Laisser countrycode et countryiso3 tous deux non définis — aucune présélection de pays, l'utilisateur sélectionne le pays manuellement.
2. Définir countrycode sur le champ de recherche DQE Country — le pays est présélectionné dynamiquement à partir de la fiche.
3. Définir countrycode sur une recherche vers une table de pays personnalisée + définir countryfield sur le nom logique du champ ISO3 de cette table.
4. Définir countryiso3 sur une valeur ISO3 fixe (par ex. FRA) — pays fixe pour toutes les fiches de ce formulaire.

Attention : les anciens PCF sont préfixés par [Legacy], tandis que les nouveaux PCF n'ont aucun préfixe [].

1. Adresses

Le service web Adresses propose l'autocomplétion et la validation d'adresse en temps réel. Il peut être activé sur les entités Account, Contact et Lead.

1.1 Réglages d'application

Dans DQE DataQ Settings → General, mettez les bascules concernées sur Yes :

• Enable Address Autocomplete — active la liste de suggestions d'adresse sur les champs d'adresse.
• Enable Address Validation — active la boîte de dialogue de validation RNVP à l'enregistrement.

Puis allez dans l'onglet Address Setup :

• Autofill Address Complement — à activer pour remplir le champ complément (nom de bâtiment, étage…) à partir de la réponse de l'API.
• Address Default Country — présélectionne un pays dans le champ de recherche. Ne restreint pas la validation internationale.
• Contact / Account / Lead Address List — choix multiple par entité. Sélectionnez les blocs d'adresse (Address 1, Address 2…) sur lesquels le service web doit être actif.

1.2 Validation d'adresse (RNVP)

La validation d'adresse est activée par la bascule Enable Address Validation dans les réglages d'application (§1.1). Lorsqu'elle est activée, l'enregistrement d'une fiche dont les champs d'adresse ont été modifiés manuellement (non sélectionnés via l'autocomplétion) déclenche une boîte de dialogue RNVP — l'utilisateur peut accepter ou refuser chaque correction suggérée, champ par champ.

Remarque : le RNVP et l'autocomplétion d'adresse sont contrôlés par deux bascules distinctes et peuvent être activés indépendamment.

1.2.1 AddressFieldControl — Champ Rue

AddressFieldControl · Custom API : DQE - Addresses - Search by address

1.2.2 CityFieldControl — Champ Ville

CityFieldControl · Custom API : DQE - Addresses - Search by address

1.2.3 PostalcodeFieldControl — Champ Code postal

PostalcodeFieldControl · Custom API : DQE - Addresses - Search by address

1.3 Résultat attendu

Lorsque Enable Address Autocomplete est actif et que les contrôles PCF sont configurés :

• Saisie d'une adresse : des suggestions apparaissent au fur et à mesure que l'utilisateur saisit dans le champ Rue.
• Saisie d'un code postal : les suggestions sont filtrées par villes et rues correspondantes.
• Sélectionner une suggestion remplit automatiquement Ville, Code postal et les autres champs mappés.

2. Emails

Le service web Email valide les adresses email en temps réel et peut suggérer des corrections basées sur le nom du contact. Disponible sur Account, Contact et Lead.

2.1 Réglages d'application

Dans DQE DataQ Settings → General, mettez Enable Email Validation sur Yes.

Puis allez dans l'onglet Email Setup :

• Contact / Account / Lead Email List — choix multiple par entité. Sélectionnez les champs email sur lesquels le service web doit être actif.

Remarque : les suggestions d'email basées sur le nom sont activées au niveau du PCF en mappant les paramètres firstnamevalue et lastnamevalue sur EmailFieldTextControl. Le stockage du code retour se configure également au niveau du PCF via le paramètre returncode.

2.2 Configuration du formulaire

Dans l'éditeur de formulaire, sélectionnez le champ Email, cliquez sur + Components, sélectionnez EmailFieldTextControl, mappez les paramètres, puis enregistrez et publiez.

EmailFieldTextControl · Custom API : DQE - Email - Search by email

2.3 Résultat attendu

• Après la saisie d'un email par l'utilisateur, un indicateur de validation apparaît à côté du champ.
• Si les champs prénom/nom sont mappés, le service web suggère des adresses email et noms de domaine probables.
• Si returncode est mappé, il est mis à jour après chaque validation et peut déclencher une logique Power Automate en aval.

3. Téléphones

Le service web Téléphone valide les numéros de téléphone en temps réel et les formate selon le pays. Disponible sur Account, Contact et Lead.

3.1 Réglages d'application

Dans DQE DataQ Settings → General, mettez Enable Phone Validation sur Yes.

Puis allez dans l'onglet Phone Setup :

• Address Default Country — présélectionne un indicatif pays. Ne restreint pas la validation internationale.
• Contact / Account / Lead Phone List — choix multiple par entité. Sélectionnez les champs téléphone sur lesquels le service web doit être actif.

Remarque : le stockage du code retour se configure au niveau du PCF via le paramètre returncode sur PhonefieldControl.

3.2 Configuration du formulaire

Dans l'éditeur de formulaire, sélectionnez le champ Main Phone, cliquez sur + Components, sélectionnez PhonefieldControl, mappez les paramètres, puis enregistrez et publiez.

PhonefieldControl · Custom API : DQE - Phone - Search by phone number

3.3 Résultat attendu

• Après la saisie d'un numéro de téléphone par l'utilisateur, un indicateur de validation apparaît et le numéro est reformaté selon le standard du pays.
• Si returncode est mappé, il est mis à jour après chaque validation et peut déclencher une logique Power Automate en aval.

4. Prénom

Le service web Prénom suggère les civilités (M./Mme/…) à partir du prénom et peut valider la cohérence prénom/genre. Disponible sur toute entité disposant d'un champ prénom (typiquement Contact, Lead).

4.1 Réglages d'application

Dans DQE DataQ Settings → General, mettez Enable Firstname Validation sur Yes.

Puis allez dans l'onglet Firstname Setup :

• Address Default Country — présélectionne un pays par défaut pour le service web.
• Firstname Configuration — ouvre le WebResource Name Mapping (voir §4.2).

4.2 Mapping des noms

Cliquez sur le bouton Firstname Configuration dans l'onglet Firstname Setup pour ouvrir le WebResource FieldMapping. C'est ici que vous mappez les codes de genre DQE sur les valeurs d'option de votre choice set Dynamics.

• DQE retourne trois valeurs de genre : H (masculin), F (féminin), I (inconnu/indéterminé).
• Pour chaque valeur, définissez la valeur d'option entière correspondante de votre champ choice set Dynamics.
• Les mappings sont stockés dans la table dqe_field_mapping dans Dataverse.

Requis en cas d'utilisation de genderchoice : si le paramètre genderchoice est mappé sur FirstNameFieldControl mais qu'aucun mapping n'est configuré ici, le champ genre ne sera pas mis à jour après la sélection du nom.

4.3 Configuration du formulaire

Dans l'éditeur de formulaire, sélectionnez le champ First Name, cliquez sur + Components, sélectionnez FirstNameFieldControl, mappez les paramètres, puis enregistrez et publiez. Configurez d'abord le mapping de genre au §4.2 si vous utilisez le paramètre genderchoice.

FirstNameFieldControl · Custom API : DQE - Name - Search by firstname

Configuration du genre : choisissez l'une des trois options — (1) laisser gendervalue et genderchoice tous deux non définis, (2) définir gendervalue sur une chaîne fixe, ou (3) définir genderchoice sur un champ choice set et configurer le mapping des valeurs dans le WebResource FieldMapping.

4.4 Résultat attendu

• Saisie d'un prénom : le service web recherche le prénom et détermine le genre/civilité probable.
• Si genderchoice est mappé et que le mapping des valeurs est configuré dans le WebResource FieldMapping (§4.2), le champ choice set genre/civilité est automatiquement mis à jour avec l'option correspondante.
• Si gendervalue est mappé à la place, il est directement défini sur la chaîne de genre fixe (H/F/I) retournée par le service web, sans passer par le mapping du choice set.
• Si genderchoice est mappé mais qu'aucun mapping n'est configuré au §4.2, le champ genre n'est pas mis à jour après la sélection du nom.

5. B2B

Le service web B2B propose l'autocomplétion d'entreprise à partir de la base SIRENE française (INSEE). Disponible uniquement sur l'entité Account.

5.1 Réglages d'application

Dans DQE DataQ Settings → General, mettez Enable Company Verification sur Yes.

Puis allez dans l'onglet Company Setup :

• Bouton Configure company mapping (cette ligne n'a pas de libellé de champ visible) — ouvre le WebResource Field Mapping, dont la popup est intitulée Company Mapping (voir §5.2).

5.2 Mapping des champs

Cliquez sur le bouton Configure company mapping dans l'onglet Company Setup pour ouvrir le WebResource FieldMapping (sa popup est intitulée Company Mapping). Cela définit quels champs de données SIRENE sont mappés vers quels champs Dynamics de l'entité Account.

• Les mappings sont stockés dans la table dqe_field_mapping dans Dataverse.
• Cliquez sur Initialize Default Records pour pré-remplir un mapping standard. Sans risque à exécuter plusieurs fois — ne crée que les enregistrements manquants, n'écrase pas les existants.

5.3 Configuration du formulaire

Ajoutez les deux contrôles B2B au formulaire Account : CompanyField sur le champ raison sociale et CompanyNumberField sur le champ numéro d'entreprise. Les deux contrôles appellent la même Custom API, DQE - Siretisation - Search.

CompanyField — Champ raison sociale

CompanyField · Custom API : DQE - Siretisation - Search

CompanyNumberField — Champ numéro d'entreprise

CompanyNumberField · Custom API : DQE - Siretisation - Search

5.4 Colonnes de la liste déroulante

Remplacez les colonnes par défaut de la liste CompanyField en définissant le paramètre columns en JSON dans le form XML.

[
  {"label": "Company",  "propertyName": "CompanyName",   "minWidth": 150, "maxWidth": 250},
  {"label": "Zip Code", "propertyName": "ZIP_Code",      "minWidth": 150, "maxWidth": 250},
  {"label": "SIRET",    "propertyName": "CompanyNumber", "minWidth": 150, "maxWidth": 250},
  {"label": "Ref",      "propertyName": "Ref",           "minWidth": 150, "maxWidth": 250}
]

Noms de propriétés disponibles :

CompanyName CompanyName2 CompanyCName CompanyNumber ZIP_Code CompanyAddress1 CompanyAddress2 CompanyAddress3 Locality Phone Fax Email Activity1 Activity2 StaffCount TurnOver LegalStructureCode LegalStructureLabel IncorporationDate DissolutionDate Country CompanyStatus CompanySIC IntraNumber MainCompanyFlag Ref

Astuce : un plugin d'édition de form XML depuis XrmToolBox peut simplifier l'export et l'édition du form XML.

5.5 Paramètre de filtre

CompanyField et CompanyNumberField acceptent tous les deux un paramètre optionnel filter, transmis directement à l'API RECSIRET. Il peut être défini statiquement dans Component Properties ou dynamiquement à partir d'une valeur de champ. Contactez votre chef de projet DQE pour les chaînes de filtre disponibles.

5.6 Résultat attendu

1. L'utilisateur ouvre une fiche Account et commence à saisir une raison sociale ou un SIRET.
2. Une liste déroulante apparaît avec les entreprises correspondantes issues de la base SIRENE.
3. L'utilisateur sélectionne une entreprise — les champs mappés (adresse, SIRET, forme juridique…) sont remplis automatiquement.
4. À l'enregistrement, si Dynamics détecte un doublon, la popup native de détection de doublons apparaît.

Important : la sélection d'un pays avant la recherche est obligatoire.