Benutzerdefinierte Steuerelemente in Dynamics konfigurieren

Diese Anleitung beschreibt die Konfiguration der DQE One Webdienste in einer Microsoft Dynamics 365- oder Power-Apps-Umgebung. Jeder Webdienst erfordert zwei Konfigurationsebenen: Einstellungen auf Anwendungsebene (einmalig) und Einstellungen auf Formularebene (pro Entität — Account, Contact, Lead).

Ein PCF-Steuerelement hinzufügen

Alle DQE-Webdienste werden konfiguriert, indem ein PCF-Steuerelement auf das Zielfeld im Formular-Editor gesetzt wird. Der Vorgang ist für jeden Steuerelementtyp auf jeder 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-Steuerelement aus.
4. Ordnen Sie die erforderlichen Parameter zu. Erforderliche Parameter müssen an ein vorhandenes Feld gebunden werden; optionale Parameter können unverändert bleiben. Die vollständige Parameterreferenz finden Sie im Abschnitt des jeweiligen Webdienstes.
5. Speichern und veröffentlichen Sie das Formular. Wiederholen Sie dies für jede Entität und jeden Adressblock, in dem der Webdienst aktiv sein soll.

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

Ländercode-Optionen

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

1. countrycode und countryiso3 beide unverändert lassen — keine Ländervorwahl, der Benutzer wählt das Land manuell aus.
2. countrycode auf das Nachschlagefeld DQE Country setzen — das Land wird dynamisch aus dem Datensatz vorgewählt.
3. countrycode auf eine benutzerdefinierte Ländertabellen-Suche setzen + countryfield auf den logischen Namen des ISO3-Felds in dieser Tabelle setzen.
4. countryiso3 auf einen fest codierten ISO3-Wert setzen (z. B. FRA) — das Land ist für alle Datensätze dieses Formulars fest vorgegeben.

Achtung: die alten PCFs tragen das Präfix [Legacy], während die neuen PCFs kein []-Präfix haben.

1. Adressen

Der Adress-Webdienst bietet Echtzeit-Adressautovervollständigung und -validierung. Er kann auf den Entitäten Account, Contact und Lead aktiviert werden.

1.1 Anwendungseinstellungen

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

• Enable Address Autocomplete — aktiviert die Adressvorschlagsliste bei Adressfeldern.
• Enable Address Validation — aktiviert den RNVP-Validierungsdialog beim Speichern.

Gehen Sie dann zum Tab Address Setup:

• Autofill Address Complement — aktivieren, um das Ergänzungsfeld (Gebäudename, Stockwerk…) aus der API-Antwort 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 pro Entität. Wählen Sie aus, auf welchen Adressblöcken (Address 1, Address 2…) der Webdienst aktiv sein soll.

1.2 Adressvalidierung (RNVP)

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

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

1.2.1 AddressFieldControl — Feld Straße

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

1.2.2 CityFieldControl — Feld Stadt

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

1.2.3 PostalcodeFieldControl — Feld Postleitzahl

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

1.3 Erwartetes Ergebnis

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

• Eingabe einer Adresse: Vorschläge erscheinen, während der Benutzer in das Feld Straße tippt.
• Eingabe einer Postleitzahl: die Vorschläge werden nach übereinstimmenden Städten und Straßen gefiltert.
• Auswahl eines Vorschlags füllt automatisch Stadt, Postleitzahl und alle weiteren zugeordneten Felder aus.

2. E-Mails

Der E-Mail-Webdienst validiert E-Mail-Adressen in Echtzeit und kann Korrekturen basierend auf dem Namen des Kontakts vorschlagen. Verfügbar für Account, Contact und Lead.

2.1 Anwendungseinstellungen

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

Gehen Sie dann zum Tab Email Setup:

• Contact / Account / Lead Email List — Mehrfachauswahl pro Entität. Wählen Sie aus, auf welchen E-Mail-Feldern der Webdienst aktiv sein soll.

Hinweis: namensbasierte E-Mail-Vorschläge werden auf PCF-Ebene aktiviert, indem die Parameter firstnamevalue und lastnamevalue auf 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 dann.

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

2.3 Erwartetes Ergebnis

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

3. Telefone

Der Telefon-Webdienst validiert Telefonnummern in Echtzeit und formatiert sie nach Land. Verfügbar für Account, Contact und Lead.

3.1 Anwendungseinstellungen

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

Gehen 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 pro Entität. Wählen Sie aus, auf welchen Telefonfeldern der Webdienst aktiv sein soll.

Hinweis: die Speicherung des Rückgabecodes wird auf PCF-Ebene über den Parameter returncode auf 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 dann.

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

3.3 Erwartetes Ergebnis

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

4. Name

Der Name-Webdienst schlägt anhand des Vornamens Anreden (Herr/Frau/…) vor und kann die Konsistenz von Name und Geschlecht validieren. Verfügbar für jede Entität mit einem Vornamenfeld (typischerweise Contact, Lead).

4.1 Anwendungseinstellungen

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

Gehen Sie dann zum Tab Firstname Setup:

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

4.2 Namenszuordnung

Klicken Sie auf die Schaltfläche Firstname Configuration im Tab Firstname Setup, um die WebResource FieldMapping 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 Ihres Dynamics-Choice-Set-Felds fest.
• Die Zuordnungen werden in der Tabelle dqe_field_mapping in Dataverse gespeichert.

Erforderlich bei Verwendung von genderchoice: Wenn der Parameter genderchoice auf FirstNameFieldControl zugeordnet ist, hier aber keine Zuordnung konfiguriert ist, 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 dann. Konfigurieren Sie zuerst die Geschlechtszuordnung in §4.2, falls Sie den Parameter genderchoice verwenden.

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

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

4.4 Erwartetes Ergebnis

• Eingabe eines Vornamens: der Webdienst sucht nach dem Namen und ermittelt das wahrscheinliche Geschlecht/die wahrscheinliche Anrede.
• Wenn genderchoice zugeordnet ist und die Wertzuordnung in der WebResource FieldMapping (§4.2) konfiguriert ist, wird das Geschlechts-/Anrede-Choice-Set-Feld automatisch auf die passende Option aktualisiert.
• Wenn stattdessen gendervalue zugeordnet ist, wird es direkt auf die vom Webdienst zurückgegebene fest codierte Geschlechts-Zeichenfolge (H/F/I) gesetzt, ohne über die Choice-Set-Zuordnung zu gehen.
• Wenn genderchoice zugeordnet ist, aber keine Zuordnung konfiguriert ist, in §4.2, wird das Geschlechtsfeld nach der Namensauswahl nicht aktualisiert.

5. B2B

Der B2B-Webdienst bietet Unternehmensautovervollstä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.

Gehen Sie dann zum Tab Company Setup:

• Schaltfläche Configure company mapping (diese Zeile hat keine sichtbare Feldbeschriftung) — öffnet die WebResource Field Mapping, deren Popup mit Company Mapping betitelt ist (siehe §5.2).

5.2 Feldzuordnung

Klicken Sie auf die Schaltfläche Configure company mapping im Tab Company Setup, um die WebResource FieldMapping zu öffnen (ihr Popup ist mit Company Mapping betitelt). Hier wird festgelegt, welche SIRENE-Datenfelder welchen Dynamics-Feldern der Entität Account zugeordnet werden.

• Die Zuordnungen werden in der Tabelle dqe_field_mapping in Dataverse gespeichert.
• Klicken Sie auf Initialize Default Records, um eine Standardzuordnung vorzubefüllen. 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-Steuerelemente hinzu: CompanyField auf dem Firmennamenfeld und CompanyNumberField auf dem Firmennummernfeld. Beide Steuerelemente rufen dieselbe Custom API auf: DQE - Siretisation - Search.

CompanyField — Feld Firmenname

CompanyField · Custom API: DQE - Siretisation - Search

CompanyNumberField — Feld Firmennummer

CompanyNumberField · Custom API: DQE - Siretisation - Search

5.4 Dropdown-Spalten

Überschreiben Sie die Standardspalten der CompanyField- Dropdown-Liste, indem Sie den Parameter columns als JSON im Form-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 Eigenschaftsnamen:

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

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

5.5 Filterparameter

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

5.6 Erwartetes Ergebnis

1. Der Benutzer öffnet einen Account-Datensatz und beginnt, einen Firmennamen oder eine SIRET-Nummer einzugeben.
2. Es erscheint eine Dropdown-Liste mit passenden Unternehmen aus der SIRENE-Datenbank.
3. Der Benutzer wählt ein Unternehmen aus — zugeordnete Felder (Adresse, SIRET, Rechtsform…) 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 zwingend erforderlich.