Configurer les contrôles personnalisés dans Dynamics

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

Ajouter un contrôle PCF

Tous les webservices 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 vides. Consultez la section de chaque webservice pour la référence complète des paramètres.
5. Enregistrez et publiez le formulaire. Répétez l'opération pour chaque entité et chaque bloc d'adresse où le webservice doit être actif.

Note : chaque contrôle doit être configuré indépendamment pour chaque formulaire d'entité. Les paramètres au niveau de l'application (DQE DataQ Settings) s'appliquent globalement et ne doivent ê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. Laissez countrycode et countryiso3 vides — aucune présélection de pays, l'utilisateur sélectionne le pays manuellement.
2. Définissez countrycode sur le champ lookup DQE Country — le pays est présélectionné dynamiquement à partir de l'enregistrement.
3. Définissez countrycode sur un lookup vers une table de pays personnalisée + définissez countryfield sur le nom logique du champ ISO3 dans cette table.
4. Définissez countryiso3 sur une valeur ISO3 codée en dur (par ex. FRA) — le pays est fixe pour tous les enregistrements 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 webservice d'adresse fournit 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 Paramètres de l'application

Dans DQE DataQ Settings → General, positionnez les toggles concernés sur Yes :

• Enable Address Autocomplete — active le menu déroulant de suggestion d'adresse sur les champs d'adresse.
• Enable Address Validation — active la boîte de dialogue de validation RNVP à l'enregistrement.

Accédez ensuite à l'onglet Address Setup :

• Autofill Address Complement — activez pour remplir le champ complément (nom du 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 — choice set à sélection multiple par entité. Sélectionnez les blocs d'adresse (Address 1, Address 2…) sur lesquels le webservice doit être actif.

1.2 Validation d'adresse (RNVP)

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

Note : RNVP et Address Autocomplete sont contrôlés par deux toggles distincts et peuvent être activés indépendamment.

1.2.1 AddressFieldControl — Champ rue

AddressFieldControl · Custom API: DQE - Address - Search

1.2.2 CityFieldControl — Champ ville

CityFieldControl · Custom API: DQE - Address - Search

1.2.3 PostalcodeFieldControl — Champ code postal

PostalcodeFieldControl · Custom API: DQE - Address - Search

1.3 Résultats attendus

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 tape dans le champ Street.
• Saisie d'un code postal : les suggestions sont filtrées par villes et rues correspondantes.
• La sélection d'une suggestion remplit automatiquement City, Postal Code et tout autre champ mappé.

2. Emails

Le webservice 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 Paramètres de l'application

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

Accédez ensuite à l'onglet Email Setup :

• Contact / Account / Lead Email List — choice set à sélection multiple par entité. Sélectionnez les champs email sur lesquels le webservice doit être actif.

Note : 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 est également configuré 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 - Validation

2.3 Résultats attendus

• 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 webservice 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 webservice 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 Paramètres de l'application

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

Accédez ensuite à l'onglet Phone Setup :

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

Note : le stockage du code retour est configuré 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 - Validation

3.3 Résultats attendus

• 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. Nom

Le webservice nom suggère des civilités (M./Mme/…) en fonction du prénom et peut valider la cohérence prénom-genre. Disponible sur toute entité disposant d'un champ prénom (généralement Contact, Lead).

4.1 Paramètres de l'application

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

Accédez ensuite à l'onglet Firstname Setup :

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

4.2 Mapping des noms

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

• DQE renvoie 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 pré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 vides, (2) définir gendervalue sur une chaîne codée en dur, ou (3) définir genderchoice sur un champ choice set et configurer le mapping des valeurs dans la WebResource FieldMapping.

5. B2B

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

5.1 Paramètres de l'application

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

Accédez ensuite à l'onglet Company Setup :

• Company Mapping — ouvre la WebResource Field Mapping (voir §5.2).

5.2 Mapping des champs

Cliquez sur le bouton Company Mapping dans l'onglet Company Setup pour ouvrir la WebResource FieldMapping. Cela définit quels champs de données SIRENE sont associés à quels champs Dynamics sur 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. Peut être exécuté plusieurs fois sans risque — ne crée que les enregistrements manquants, n'écrase pas ceux existants.

5.3 Configuration du formulaire

Ajoutez les deux contrôles B2B au formulaire Account : CompanyField sur le champ nom de l'entreprise et CompanyNumberField sur le champ numéro d'entreprise.

CompanyField — Champ nom de l'entreprise

CompanyField · Custom API: DQE - Company - Search

CompanyNumberField — Champ numéro d'entreprise

CompanyNumberField · Custom API: DQE - CompanyNumber - Search

5.4 Colonnes du menu déroulant

Remplacez les colonnes par défaut du menu déroulant CompanyField en définissant le paramètre columns en JSON dans le XML du formulaire.

[
  {"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 CompanyNumber ZIP_Code CompanyAddress1 CompanyAddress2 CompanyAddress3 Locality Phone Email Activity1 Activity2 StaffCount TurnOver LegalStructureCode LegalStructureLabel IncorporationDate DissolutionDate Country CompanyStatus MainCompanyFlag Ref

Astuce : un plugin d'édition XML de formulaire de XrmToolBox peut simplifier l'export et la modification du XML du formulaire.

5.5 Paramètre de filtre

CompanyField et CompanyNumberField acceptent tous deux un paramètre filter optionnel 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 connaître les chaînes de filtre disponibles.

5.6 Résultats attendus

1. L'utilisateur ouvre un enregistrement Account et commence à saisir un nom d'entreprise ou un SIRET.
2. Un menu déroulant apparaît avec les entreprises correspondantes 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 fenêtre native de détection des doublons apparaît.

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