Custom Controls in Dynamics konfigurieren

Diese Anleitung führt durch die Konfiguration der DQE-One-Webservices in einer Microsoft Dynamics 365- oder Power-Apps-Umgebung. Jeder Webservice erfordert zwei Konfigurationsebenen: Einstellungen auf Anwendungsebene (einmalig durchzuführen) und Einstellungen auf Formularebene (pro Entität durchzuführen — Account, Contact, Lead).

Hinzufügen eines PCF-Controls

Alle DQE-Webservices werden konfiguriert, indem im Formular-Editor ein PCF-Control auf dem Zielfeld platziert wird. Der Vorgang ist für jeden Control-Typ und jede Entität identisch — Standard (Account, Contact, Lead) oder benutzerdefiniert.

1. Öffnen Sie das Formular der Zielentität im Power-Apps-Formular-Editor.
2. Wählen Sie das zu konfigurierende Feld aus (Straße, Stadt, E-Mail, Telefon usw.).
3. Klicken Sie im rechten Bereich auf + Components und wählen Sie dann das entsprechende DQE-Control aus.
4. Ordnen Sie die erforderlichen Parameter zu. Erforderliche Parameter müssen an ein vorhandenes Feld gebunden werden; optionale Parameter können leer bleiben. Die vollständige Parameterreferenz finden Sie im jeweiligen Webservice-Abschnitt.
5. Speichern und veröffentlichen Sie das Formular. Wiederholen Sie dies für jede Entität und jeden Adressblock, in dem der Webservice aktiv sein soll.

Hinweis: Jedes Control muss unabhängig pro Entitätsformular konfiguriert werden. Einstellungen auf Anwendungsebene (DQE DataQ Settings) gelten global und müssen nur einmal festgelegt werden.

Optionen für den Ländercode

Mehrere Controls akzeptieren Ländercode-Parameter, um das Land für API-Abfragen vorauszuwählen. Drei sich gegenseitig ausschließende Optionen:

1. Lassen Sie sowohl countrycode als auch countryiso3 leer — keine Ländervorauswahl, der Benutzer wählt das Land manuell aus.
2. Setzen Sie countrycode auf das DQE-Country-Lookup-Feld — das Land wird dynamisch aus dem Datensatz vorausgewählt.
3. Setzen Sie countrycode auf einen Lookup zu einer benutzerdefinierten Ländertabelle und countryfield auf den logischen Namen des ISO3-Felds in dieser Tabelle.
4. Setzen Sie countryiso3 auf einen fest codierten ISO3-Wert (z. B. FRA) — das Land ist für alle Datensätze dieses Formulars fest vorgegeben.

Achtung: die alten PCFs sind mit dem Präfix [Legacy] gekennzeichnet, während die neuen PCFs kein []-Präfix haben.

1. Adressen

Der Adress-Webservice bietet Echtzeit-Adressautovervollständigung und -validierung. Er kann für die Entitäten Account, Contact und Lead aktiviert werden.

1.1 Anwendungseinstellungen

Setzen Sie unter DQE DataQ Settings → General die entsprechenden Schalter auf Yes:

• Enable Address Autocomplete — aktiviert das Dropdown mit Adressvorschlägen in den Adressfeldern.
• Enable Address Validation — aktiviert den RNVP-Validierungsdialog beim Speichern.

Wechseln Sie dann zum Tab Address Setup:

• Autofill Address Complement — aktivieren, um das Ergänzungsfeld (Gebäudename, Stockwerk usw.) anhand der API-Antwort automatisch zu befüllen.
• Address Default Country — wählt ein Land im Suchfeld vor. Schränkt die internationale Validierung nicht ein.
• Contact / Account / Lead Address List — Mehrfachauswahl-Choice-Set pro Entität. Wählen Sie aus, für welche Adressblöcke (Address 1, Address 2 usw.) der Webservice aktiv sein soll.

1.2 Adressvalidierung (RNVP)

Die Adressvalidierung wird über den Schalter Enable Address Validation in den Anwendungseinstellungen (§1.1) aktiviert. Ist sie aktiviert, löst das Speichern eines Datensatzes, dessen Adressfelder manuell bearbeitet wurden (nicht über die Autovervollständigung ausgewählt), einen RNVP-Dialog aus — der Benutzer kann jede vorgeschlagene Korrektur feldweise annehmen oder ablehnen.

Hinweis: RNVP und die Adressautovervollständigung werden über zwei separate Schalter gesteuert und können unabhängig voneinander aktiviert werden.

1.2.1 AddressFieldControl — Straßenfeld

AddressFieldControl · Custom API: DQE - Address - Search

1.2.2 CityFieldControl — Stadtfeld

CityFieldControl · Custom API: DQE - Address - Search

1.2.3 PostalcodeFieldControl — Postleitzahlfeld

PostalcodeFieldControl · Custom API: DQE - Address - Search

1.3 Erwartete Ergebnisse

Wenn Enable Address Autocomplete aktiv und die PCF-Controls konfiguriert sind:

• Eingabe einer Adresse: Vorschläge erscheinen, während der Benutzer im Straßenfeld tippt.
• Eingabe einer Postleitzahl: Vorschläge werden nach passenden Städten und Straßen gefiltert.
• Die Auswahl eines Vorschlags füllt automatisch Stadt, Postleitzahl und alle anderen zugeordneten Felder aus.

2. E-Mails

Der E-Mail-Webservice validiert E-Mail-Adressen in Echtzeit und kann anhand des Kontaktnamens Korrekturvorschläge machen. Verfügbar für Account, Contact und Lead.

2.1 Anwendungseinstellungen

Setzen Sie unter DQE DataQ Settings → General Enable Email Validation auf Yes.

Wechseln Sie dann zum Tab Email Setup:

• Contact / Account / Lead Email List — Mehrfachauswahl-Choice-Set pro Entität. Wählen Sie aus, für welche E-Mail-Felder der Webservice aktiv sein soll.

Hinweis: Namensbasierte E-Mail-Vorschläge werden auf PCF-Ebene aktiviert, indem die Parameter firstnamevalue und lastnamevalue am EmailFieldTextControl zugeordnet werden. Die Speicherung des Rückgabecodes wird ebenfalls auf PCF-Ebene über den Parameter returncode konfiguriert.

2.2 Formularkonfiguration

Wählen Sie im Formular-Editor das Feld Email aus, klicken Sie auf + Components, wählen Sie EmailFieldTextControl aus, ordnen Sie die Parameter zu und speichern und veröffentlichen Sie anschließend.

EmailFieldTextControl · Custom API: DQE - Email - Validation

2.3 Erwartete Ergebnisse

• Nachdem der Benutzer eine E-Mail-Adresse eingegeben hat, erscheint neben dem Feld eine Validierungsanzeige.
• Sind Vor-/Nachnamefelder zugeordnet, schlägt der Webservice wahrscheinliche E-Mail-Adressen und Domainnamen vor.
• Ist returncode zugeordnet, wird es nach jeder Validierung aktualisiert und kann nachgelagerte Power-Automate-Logik auslösen.

3. Telefonnummern

Der Telefon-Webservice validiert Telefonnummern in Echtzeit und formatiert sie länderspezifisch. Verfügbar für Account, Contact und Lead.

3.1 Anwendungseinstellungen

Setzen Sie unter DQE DataQ Settings → General Enable Phone Validation auf Yes.

Wechseln Sie dann zum Tab Phone Setup:

• Address Default Country — wählt eine Landesvorwahl vor. Schränkt die internationale Validierung nicht ein.
• Contact / Account / Lead Phone List — Mehrfachauswahl-Choice-Set pro Entität. Wählen Sie aus, für welche Telefonfelder der Webservice aktiv sein soll.

Hinweis: Die Speicherung des Rückgabecodes wird auf PCF-Ebene über den Parameter returncode am PhonefieldControl konfiguriert.

3.2 Formularkonfiguration

Wählen Sie im Formular-Editor das Feld Main Phone aus, klicken Sie auf + Components, wählen Sie PhonefieldControl aus, ordnen Sie die Parameter zu und speichern und veröffentlichen Sie anschließend.

PhonefieldControl · Custom API: DQE - Phone - Validation

3.3 Erwartete Ergebnisse

• Nachdem der Benutzer eine Telefonnummer eingegeben hat, erscheint eine Validierungsanzeige und die Nummer wird gemäß dem Landesstandard neu formatiert.
• Ist returncode zugeordnet, wird es nach jeder Validierung aktualisiert und kann nachgelagerte Power-Automate-Logik auslösen.

4. Name

Der Name-Webservice schlägt anhand des Vornamens Anreden (Mr./Ms./…) vor und kann die Konsistenz zwischen Name und Geschlecht validieren. Verfügbar für jede Entität mit einem Vornamefeld (typischerweise Contact, Lead).

4.1 Anwendungseinstellungen

Setzen Sie unter DQE DataQ Settings → General Enable Firstname Validation auf Yes.

Wechseln Sie dann zum Tab Firstname Setup:

• Address Default Country — wählt ein Standardland für den Webservice vor.
• Firstname Configuration — öffnet die Name-Mapping-WebResource (siehe §4.2).

4.2 Namenszuordnung

Klicken Sie auf die Schaltfläche Firstname Configuration im Tab Firstname Setup, um die FieldMapping-WebResource zu öffnen. Hier ordnen Sie die DQE-Geschlechtscodes den Optionswerten Ihres Dynamics-Choice-Sets zu.

• DQE gibt drei Geschlechtswerte zurück: H (männlich), F (weiblich), I (unbekannt/unbestimmt).
• Legen Sie für jeden Wert den entsprechenden ganzzahligen Optionswert aus Ihrem Dynamics-Choice-Set-Feld fest.
• Zuordnungen werden in der Tabelle dqe_field_mapping in Dataverse gespeichert.

Erforderlich bei Verwendung von genderchoice: Wenn der Parameter genderchoice am FirstNameFieldControl zugeordnet ist, hier aber keine Zuordnung konfiguriert wurde, wird das Geschlechtsfeld nach der Namensauswahl nicht aktualisiert.

4.3 Formularkonfiguration

Wählen Sie im Formular-Editor das Feld First Name aus, klicken Sie auf + Components, wählen Sie FirstNameFieldControl aus, ordnen Sie die Parameter zu und speichern und veröffentlichen Sie anschließend. Konfigurieren Sie bei Verwendung des Parameters genderchoice zuerst die Geschlechtszuordnung in §4.2.

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

Geschlechtskonfiguration: Wählen Sie eine von drei Optionen — (1) sowohl gendervalue als auch genderchoice leer lassen, (2) gendervalue auf eine fest codierte Zeichenfolge setzen, oder (3) genderchoice auf ein Choice-Set-Feld setzen und die Wertzuordnung in der FieldMapping-WebResource konfigurieren.

5. B2B

Der B2B-Webservice bietet eine Firmenautovervollständigung aus der französischen SIRENE-Datenbank (INSEE). Nur für die Entität Account verfügbar.

5.1 Anwendungseinstellungen

Setzen Sie unter DQE DataQ Settings → General Enable Company Verification auf Yes.

Wechseln Sie dann zum Tab Company Setup:

• Company Mapping — öffnet die Field-Mapping-WebResource (siehe §5.2).

5.2 Feldzuordnung

Klicken Sie auf die Schaltfläche Company Mapping im Tab Company Setup, um die FieldMapping-WebResource zu öffnen. Hier wird festgelegt, welche SIRENE-Datenfelder welchen Dynamics-Feldern der Account-Entität zugeordnet werden.

• Zuordnungen werden in der Tabelle dqe_field_mapping in Dataverse gespeichert.
• Klicken Sie auf Initialize Default Records, um eine Standardzuordnung vorzubelegen. Kann gefahrlos mehrfach ausgeführt werden — es werden nur fehlende Datensätze erstellt, vorhandene werden nicht überschrieben.

5.3 Formularkonfiguration

Fügen Sie dem Account-Formular die beiden B2B-Controls hinzu: CompanyField auf dem Firmennamefeld und CompanyNumberField auf dem Firmennummernfeld.

CompanyField — Firmennamefeld

CompanyField · Custom API: DQE - Company - Search

CompanyNumberField — Firmennummernfeld

CompanyNumberField · Custom API: DQE - CompanyNumber - Search

5.4 Dropdown-Spalten

Überschreiben Sie die Standardspalten im Dropdown von CompanyField, indem Sie den Parameter columns als JSON im Formular-XML festlegen.

[
  {"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}
]

Verfügbare Property-Namen:

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

Tipp: Ein Formular-XML-Editor-Plugin von XrmToolBox kann den Export und die Bearbeitung des Formular-XML vereinfachen.

5.5 Filter-Parameter

Sowohl CompanyField als auch CompanyNumberField akzeptieren einen optionalen Parameter filter, der direkt an die RECSIRET-API übergeben wird. Er kann statisch in den Component Properties oder dynamisch über einen Feldwert festgelegt werden. Wenden Sie sich an Ihren DQE-Projektmanager für verfügbare Filterzeichenfolgen.

5.6 Erwartete Ergebnisse

1. Der Benutzer öffnet einen Account-Datensatz und beginnt, einen Firmennamen oder eine SIRET-Nummer einzugeben.
2. Ein Dropdown mit passenden Firmen aus der SIRENE-Datenbank erscheint.
3. Der Benutzer wählt eine Firma aus — zugeordnete Felder (Adresse, SIRET, Rechtsform usw.) werden automatisch ausgefüllt.
4. Erkennt Dynamics beim Speichern ein Duplikat, erscheint das native Duplikaterkennungs-Popup.

Wichtig: Die Auswahl eines Landes vor der Suche ist obligatorisch.