Referenz auflösen

Der Service Task „Referenz auflösen“ sucht zu einem Freitext, etwa dem Lieferantennamen aus einer gelesenen Rechnung, den passenden Datensatz eines Datenschemas und liefert dessen Id. Damit wird aus Text, der aus Dokumenten oder E-Mails kommt, eine Verknüpfung auf einen vorhandenen Datensatz. Verglichen wird eine Spalte des Schemas in sechs Stufen, von der exakten Übereinstimmung bis zur Ähnlichkeitssuche.

Technischer Name prio_resolveReference · Kategorie im Dialog „Service-Task auswählen“: Daten & Verknüpfungen

Wann wird dieser Service verwendet?

Eingangsrechnungen zuordnen: Der Lieferantenname aus der PDF-Analyse wird dem Lieferantendatensatz der Musterfirma GmbH zugeordnet, bevor die Rechnung gespeichert wird.
Lieferscheine zum Kunden: Der Absender eines Lieferscheins wird im Schema „Kunden“ gesucht.
Anfragen aus Formularen: Eine Firma, die in einem öffentlichen Formular als Text eingegeben wurde, wird mit dem Kundenstamm abgeglichen.

Voraussetzungen

Das Datenschema muss für SQL-Abfragen bereitstehen, wie sie auch das SQL-gefilterte Referenzfeld nutzt. Jede Suche ist eine Abfrage auf diese Datenbank; sie dauert einige Sekunden und verursacht Kosten je Abfrage.

Eingabe

Feld	Typ	Pflicht	Bedeutung
`dataSchemaId`	String	ja	Id des Datenschemas, z. B. `kunden` oder `contacts/organisation`. Gesucht wird im letzten Pfadteil, einschließlich der von ihm abgeleiteten Schemata
`searchValue`	String	ja	Der Suchtext; leer oder nur Leerzeichen bricht ab
`attributeName`	String	nein	Spalte, die verglichen wird. Standard `document_name` (der Dokumentname des Datensatzes). Erlaubt sind Buchstaben, Ziffern und Unterstrich, beginnend mit Buchstabe oder Unterstrich

{
  "dataSchemaId": "lieferanten",
  "searchValue": rechnung.lieferantName,
  "attributeName": "document_name"
}

Die Suche läuft in zwei Schritten. Zuerst werden Kandidaten vorgefiltert: Jedes Wort des Suchtexts mit mindestens drei Zeichen muss in der Spalte vorkommen (Groß-/Kleinschreibung egal). Dann werden die Kandidaten in dieser Reihenfolge verglichen, die erste Stufe mit Treffer gewinnt:

Stufe	`matchType`	Bedeutung	`score`
1	`exact`	Spalte ist gleich dem Suchtext	1
2	`contains`	Spalte enthält den Suchtext	1
3	`reverseContains`	Suchtext enthält die Spalte	1
4	`tokenMatch`	alle Wörter des Suchtexts kommen vor; Satzzeichen werden ignoriert	1
5	`startsWith`	Spalte beginnt mit dem Suchtext	0.9
6	`fuzzy`	Ähnlichkeit (Jaro-Winkler) mindestens 0,80	Ähnlichkeit, gerundet

Passen mehrere Datensätze in derselben Stufe, gewinnt der kürzeste Wert; bei reverseContains der längste.

Ausgabe

{
  "found": true,
  "dataObjectId": "01JCX4R9M2T7V8W3Y5Z6A7B8C9",
  "documentName": "Huber Elektrotechnik GmbH & Co. KG",
  "dataSchemaId": "lieferanten",
  "matchType": "tokenMatch",
  "score": 1
}

found: true, wenn ein Datensatz gefunden wurde. Ohne Treffer kommt { "found": false, "dataObjectId": null, "documentName": null, "matchType": null, "score": 0 } zurück, und der Prozess läuft weiter.
dataObjectId: Id des gefundenen Datensatzes, einsetzbar als Wert eines Referenzfelds.
dataSchemaId: Schema des Treffers. Bei abgeleiteten Schemata kann es vom Eingabewert abweichen.

Das Ergebnis landet unter dem Ergebnispfad, z. B. lieferant.

Fehler und Verhalten

Eingabefehler werfen: prio_resolveReference: dataSchemaId is required, prio_resolveReference: searchValue is required, prio_resolveReference: invalid attributeName "…".
Datenbankfehler (Tabelle fehlt, Spalte unbekannt, Abfrage scheitert) werfen ebenfalls. Mit Fehler-Randereignis läuft der Prozess dort weiter, ohne Randereignis endet der Vorgang im Fehler mit Wiederaufsetzpunkt und Fehler-Mail an den Prozessverantwortlichen.
Kein Treffer ist kein Fehler: found ist false, der Prozess läuft weiter.
Wiederholungen: Bis zu drei Versuche nur bei vorübergehenden Fehlern (Zeitüberschreitung, Dienst kurz nicht erreichbar). Zeitgrenze 900 Sekunden. Der Service liest nur und ändert keine Daten.
Im Dry Run wird keine Abfrage ausgeführt; der Schritt liefert eine Beispielausgabe aus dem Katalog.

Beispiel

Die Musterfirma GmbH liest Eingangsrechnungen mit KI: Daten extrahieren aus. In der Nachricht steht rechnung.lieferantName = Huber Elektrotechnik GmbH & Co KG; im Schema „Lieferanten“ heißt der Datensatz „Huber Elektrotechnik GmbH & Co. KG“.

Input-Ausdruck wie oben, Ergebnispfad lieferant.
Ausgabe: found: true, matchType: "tokenMatch", score: 1. Der fehlende Punkt in „Co KG“ spielt keine Rolle, weil Satzzeichen beim Vergleich der Wörter entfernt werden.
Gateway: lieferant.found and lieferant.score >= 0.9 → Datenbank-Schritt speichert die Rechnung mit lieferant.dataObjectId im Referenzfeld; sonst Benutzeraufgabe „Lieferant zuordnen“.

Häufige Fragen

Kann in mehreren Spalten gleichzeitig gesucht werden?

Nein, verglichen wird genau eine Spalte (attributeName). Für eine zweite Spalte wird der Service ein zweites Mal aufgerufen.

„Müller GmbH“ findet „Mueller GmbH“ nicht.

Umlaute bleiben erhalten und werden nicht in ae, oe, ue übersetzt. Ob die Ähnlichkeitssuche noch greift, hängt vom Rest des Namens ab; matchType zeigt es.

Soll dataObjectId ungeprüft gespeichert werden?

Besser nicht. Ab Stufe 5 (startsWith, fuzzy) sind Fehlzuordnungen möglich. found, matchType und score in einem Gateway prüfen und unsichere Treffer einer Benutzeraufgabe vorlegen.

Die Suche ist langsam, obwohl das Schema klein ist.

Jede Suche ist eine Datenbankabfrage mit einigen Sekunden Laufzeit. Besteht der Suchtext nur aus kurzen Wörtern (unter drei Zeichen, z. B. „AG“), wird die ganze Tabelle gelesen, was zusätzlich dauert.

Nächster Schritt

Datenbank: wie Verknüpfungen zwischen Datensätzen aufgebaut sind und wo die Id eines Datensatzes steht.