Duplicate Detection Rule feuert nicht: Warum Dubletten trotzdem entstehen

Eine Duplicate Detection Rule in Dynamics 365 feuert nur unter engen Bedingungen. Sie muss veröffentlicht sein, die Duplikaterkennung muss organisationsweit aktiv sein, und der Schreibvorgang muss aus einem Kanal kommen, der die Prüfung überhaupt auslöst. Genau der letzte Punkt überrascht die meisten Teams: Web API, SDK, die meisten Cloud Flows und viele Importwerkzeuge umgehen die Duplikaterkennung standardmäßig. Dieser Beitrag erklärt, wie die Erkennung in Dataverse technisch arbeitet, warum Ihre Regel im Alltag nicht greift und mit welchen Mitteln Sie Dubletten wirklich verhindern.

Er gehört zum Themen-Hub Datenqualität in Dynamics 365 und vertieft eine der häufigsten Fehlerquellen sauberer Stammdaten.

Wie Duplikaterkennung in Dataverse arbeitet

Dataverse erkennt mögliche Dubletten über sogenannte Matchcodes. Ein Matchcode ist ein verdichteter Vergleichswert, der aus den in der Regel definierten Feldern gebildet wird. Beim Veröffentlichen einer Regel erzeugt das System für jeden vorhandenen Datensatz des betroffenen Tabellentyps einen Matchcode. Danach wird auch bei jedem Anlegen oder Ändern eines Datensatzes ein Matchcode gebildet und gegen die bestehenden Matchcodes verglichen.

Eine Regel definiert Basis- und Vergleichstabelle sowie die Kriterien, etwa exakte Übereinstimmung der E-Mail-Adresse oder gleiche Anfangszeichen des Firmennamens. Model-driven Apps und die Customer-Engagement-Apps bringen bereits einfache Standardregeln für Konten, Kontakte und Leads mit. Für alle anderen Tabellen gilt: Es existiert keine Erkennung, bis Sie selbst eine Regel anlegen und veröffentlichen. Wie Sie eine solche Regel anlegen und veröffentlichen, beschreibt Microsoft Learn zum Einrichten von Dublettenerkennungsregeln. Eine nur gespeicherte, aber unveröffentlichte Regel erzeugt keine Matchcodes und wird nie ausgewertet.

Wichtig für das Verständnis: Die Duplikaterkennung ist eine Momentaufnahme beim Schreiben. Sie vergleicht neue Matchcodes mit vorhandenen, während der Datensatz entsteht. Werden zwei identische Datensätze im exakt selben Moment angelegt, können beide durchrutschen, weil zum Vergleichszeitpunkt noch kein Matchcode des jeweils anderen existiert. Aus diesem Grund empfiehlt Microsoft ergänzend geplante Erkennungsjobs, die den Bestand nachträglich auf Dubletten prüfen.

Warum Ihre Regel nicht greift

Wenn Dubletten trotz vorhandener Regel entstehen, liegt es fast immer an einer der folgenden Ursachen. Sie lassen sich der Reihe nach abarbeiten.

Regel nicht veröffentlicht oder Erkennung deaktiviert

Nur Regeln im Status Veröffentlicht feuern. Ebenso lässt sich die Duplikaterkennung organisationsweit ausschalten. Ist dieser Schalter aus, greift keine einzige Regel, egal wie sauber sie konfiguriert ist. Prüfen Sie beides zuerst, bevor Sie an den Kriterien zweifeln.

Feld nach dem Veröffentlichen geändert

Ein tückischer Fall: Wird ein in der Regel verwendetes Textfeld nach dem Veröffentlichen verlängert, bleibt das für die Erkennung unbemerkt. Die kombinierte Feldlänge kann dann die Matchcode-Grenze überschreiten, und Dubletten werden nicht mehr zuverlässig gefunden. Nach jeder Änderung an den beteiligten Feldern sollten Sie die Regel neu veröffentlichen. Zum Bearbeiten einer bereits veröffentlichten Regel müssen Sie sie ohnehin zunächst zurückziehen.

Groß- und Kleinschreibung sowie leere Werte

Ob Meier und MEIER als gleich gelten, hängt am Kontrollkästchen für die Groß-/Kleinschreibung. Passt die Einstellung nicht zur echten Schreibweise Ihrer Daten, findet die Regel zu wenige oder zu viele Treffer. Ebenso relevant ist der Umgang mit leeren Feldern: Enthält eine Regel nur eine einzige Bedingung, werden leere Werte beim Erkennungsjob ignoriert und funktionieren im Offline-Modus nicht.

Nur bestimmte Aktionen lösen die Prüfung aus

Der Dialog zur Duplikaterkennung erscheint nur bei Datensätzen, die über die Oberfläche angelegt oder geändert werden, etwa über Formulare oder editierbare Grids in der Web-App. Für Datensätze aus einem klassischen Workflow wird kein Dialog gezeigt. Zusätzlich gibt es Aktionen, bei denen grundsätzlich keine Erkennung stattfindet: beim Zusammenführen zweier Datensätze, beim Qualifizieren eines Leads, beim Abschließen einer Aktivität und beim reinen Statuswechsel, etwa dem Aktivieren oder Reaktivieren. Wer über diese Wege Datensätze erzeugt, umgeht die Regel.

Warum Web API, SDK und Importe die Prüfung umgehen

Der wichtigste und am häufigsten übersehene Punkt betrifft alle programmatischen Schreibvorgänge. Beim Anlegen oder Ändern von Datensätzen über die Web API oder das SDK ist die Duplikaterkennung standardmäßig unterdrückt. Das Verhalten bei fehlendem Header entspricht dem Wert true, die Operation läuft also durch, auch wenn eine Dublette existiert.

Um die Prüfung zu erzwingen, setzen Sie in der Web API den Anfrage-Header MSCRM.SuppressDuplicateDetection auf false. Bei einem POST zum Anlegen oder einem PATCH zum Aktualisieren bricht Dataverse dann bei einem Treffer mit dem Fehlercode 0x80040333 und der Meldung ab, dass ein Datensatz nicht erstellt oder aktualisiert wurde, weil bereits eine Dublette existiert. Im SDK für .NET erreichen Sie dasselbe über den Parameter SuppressDuplicateDetection = false am jeweiligen Request. Das dokumentierte Verhalten dieses Headers beschreibt Microsoft Learn zur Web API mit dem Header MSCRM.SuppressDuplicateDetection.

POST [Organization URI]/api/data/v9.2/leads HTTP/1.1
Content-Type: application/json
MSCRM.SuppressDuplicateDetection: false

{ "firstname": "Monte", "lastname": "Orton", "emailaddress1": "monteorton@example.com" }

Die Praxis-Falle: Die meisten Integrationen setzen diesen Header nie. Das betrifft Dual-Write, Migrationswerkzeuge und individuelle API-Clients ebenso wie den Dataverse-Connector in Power Automate, je nach Konfiguration der Aktion. Beim Import über den Assistenten müssen Sie die Duplikaterkennung ausdrücklich anhaken, sonst wird sie übersprungen. Wer Bestandsdaten migriert, sollte diese Mechanik von Anfang an einplanen. Der Beitrag zur erfolgreichen Dynamics-365-Datenmigration zeigt, wie Sie Dubletten schon vor dem Ladevorgang aus den Quelldaten entfernen.

Merken Sie sich als Faustregel: Alles, was nicht über ein von Hand bedientes Formular kommt, prüft nicht automatisch auf Dubletten. Die Duplicate Detection Rule ist damit vor allem eine Hilfe für die manuelle Erfassung, nicht für die Integration.

Der Grund für dieses Standardverhalten ist Leistung. Würde jede API-Massenoperation gegen sämtliche Matchcodes prüfen, würden Importe und Synchronisationen spürbar langsamer. Microsoft hat sich deshalb dafür entschieden, die Prüfung im programmatischen Weg nur auf ausdrückliche Anforderung durchzuführen. Für Sie heißt das: Die Verantwortung für saubere Daten wandert bei jeder Integration zurück in den Code, in die Konfiguration des Connectors oder in das Migrationswerkzeug. Wer diese Stelle nicht bewusst absichert, produziert Dubletten, ohne es zu merken.

Alternativen für echte Dublettenvermeidung

Wenn Eindeutigkeit garantiert sein muss, ist die Duplicate Detection Rule das falsche Werkzeug. Sie ist eine weiche Warnung, die sich in vielen Kanälen abschalten lässt. Für harte Eindeutigkeit gibt es zwei belastbare Ansätze.

Alternate Keys auf Datenbankebene

Ein Alternate Key definiert eine oder mehrere Spalten als eindeutigen Schlüssel und legt dafür einen Datenbankindex an. Dieser Index erzwingt die Eindeutigkeit hart und kanalunabhängig: Egal ob Oberfläche, Web API, Dual-Write oder Import, ein zweiter Datensatz mit demselben Schlüsselwert wird von der Datenbank abgelehnt. Ein Alternate Key eignet sich zusätzlich hervorragend, um Datensätze aus einem Fremdsystem über deren fachliche ID per Upsert zu referenzieren. Grenzen: Eine Tabelle darf bis zu zehn Alternate Keys haben, die Schlüsselgröße unterliegt SQL-Grenzen von 900 Byte und 16 Spalten, und nicht alle Feldtypen sind zulässig.

Synchrones Plugin

Reicht ein einfacher Schlüssel nicht, weil die Dublettenlogik unscharf ist, etwa ähnliche statt identischer Werte, ist ein synchrones Plugin die Lösung. Es läuft serverseitig in der Event Pipeline und kann eine Operation vor dem Speichern kontrolliert abbrechen, unabhängig vom Kanal. Ein Plugin kann dabei die vorhandenen Duplicate Detection Rules über die entsprechende Nachricht selbst aufrufen und deren Ergebnis auswerten, sodass Sie Ihre bereits gepflegten Kriterien wiederverwenden, statt die Logik doppelt zu schreiben. Wann ein Plugin gegenüber einer konfigurierbaren Alternative die richtige Wahl ist, ordnet der Beitrag Business Rule, JavaScript, Plugin oder Cloud Flow ein.

In der Praxis kombinieren Sie die Werkzeuge: ein Alternate Key oder Plugin als harte Schranke gegen Duplikate aus jedem Kanal, ergänzt um eine Duplicate Detection Rule für die komfortable Warnung bei der manuellen Erfassung und um geplante Erkennungsjobs für die Bestandsreinigung.

Wenn Dubletten trotz aktiver Regeln in Ihre Daten gelangen oder Sie eine kanalunabhängige Eindeutigkeit sauber aufsetzen möchten, sprechen Sie uns an. Wir analysieren, über welche Wege Datensätze in Ihr System kommen, und bauen die passende Kombination aus Regel, Schlüssel und Plugin.