SQL-Resolver

Der SQL-Resolver löst Anruferrufnummern direkt gegen Ihre Datenbank auf. Reverse Lookup PRO baut dazu per JDBC eine Verbindung zu Ihrem Datenbankserver auf, führt ein von Ihnen hinterlegtes SELECT-Statement mit der Anruferrufnummer aus und wertet die erste Ergebniszeile spaltenweise aus. Ihre Aufgabe als Integrator ist es, eine erreichbare Datenbank (oder einen View) mit einem passenden SELECT bereitzustellen.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: ausgehende JDBC-Verbindung; das Modul ist Datenbank-Client
• Richtung: STARFACE (Modul) → Datenbankserver; ausgelöst bei jeder Rufnummernauflösung, beim manuellen Test („Einstellungen testen") sowie bei der Abfrage der UI-Integration
• Konfigurationsort: Moduloberfläche, Tab Einstellungen, Liste Suchanbieter — eigene Suchanbieter legen Sie im Expertenmodus über das Plus-Symbol an (Resolver-Typ SQL)
• Verbindung: wird je Auflösung neu aufgebaut und anschließend geschlossen; es gibt kein Connection-Pooling durch das Modul
• Authentifizierung: Benutzername/Kennwort der Datenbank; richten Sie ein Datenbankkonto mit reinen Leserechten ein
• Zugriff: nur lesend sinnvoll — ausgewertet wird ausschließlich das Resultat eines SELECT-Statements
• Erreichbarkeit: Der Datenbankserver muss von der STARFACE aus erreichbar sein; für Cloud-Anlagen mit lokalen Datenbanken steht ein SSH-Tunnel-Konfigurator bereit (seit Modulversion 23.5.25)

Unterstützte Datenbanken

Auswahl Datenbank-Typ	JDBC-Treiberklasse	Verbindungs-URL
PostgreSQL	org.postgresql.Driver	jdbc:postgresql://<host>/<dbName>
MySQL	com.mysql.cj.jdbc.Driver	jdbc:mysql://<host>/<dbName>
Microsoft SQL Server	com.microsoft.sqlserver.jdbc.SQLServerDriver	jdbc:sqlserver://<host>;databaseName=<dbName>
Derby	org.apache.derby.jdbc.ClientDriver	jdbc:derby://<host>/<dbName>

Die Treiber stellt die STARFACE-Plattform bereit; die Verfügbarkeit der Treiberklassen wird zur Laufzeit geprüft. In die Verbindungs-URL fließen der Wert des Feldes Hostname/IP (<host>) und Datenbank-Name (<dbName>) ein. Das separate Feld Port wird beim Verbindungsaufbau derzeit nicht ausgewertet — tragen Sie einen abweichenden Port als Bestandteil des Hostnamens ein, z. B. db.example.com:5432.

Query-Vorlage und Platzhalter

Das SELECT-Statement hinterlegen Sie im Feld SQL-Select-Statement. Vor der Ausführung ersetzt das Modul darin die folgenden Platzhalter:

Platzhalter	Wird ersetzt durch
{tel}	die aufzulösende Rufnummer im gewählten Rufnummernformat
{<feldId>}	den Wert des gleichnamigen Konfigurationsfelds, z. B. {dbName}, {username} — inklusive definierter Präfixe ({port} ergibt z. B. :5432)

Das Rufnummernformat von {tel} legen Sie je Suchanbieter fest: +xx (z. B. +4972115104230), 00xx (004972115104230) oder 0 (072115104230).

Die Ersetzung ist eine reine Zeichenkettenersetzung — es werden keine Bind-Parameter verwendet und keine Anführungszeichen ergänzt. Setzen Sie {tel} daher selbst in Anführungszeichen ('{tel}') und speichern Sie Rufnummern in der Datenbank möglichst im selben Format, das Sie als Rufnummernformat wählen. Komplexe Abfragen (Joins, Normalisierung von Rufnummernschreibweisen) kapseln Sie am besten in einem datenbankseitigen View. Begrenzen Sie das Ergebnis auf eine Zeile (LIMIT 1 bzw. SELECT TOP 1).

Erwartete Ergebnisspalten und Auswertung

Das Modul wertet die erste Zeile des Abfrageergebnisses aus. Die Spalten werden über ihre Position den konfigurierten Parsern zugeordnet (Parser/Ergebnis-Auswertung):

• Spalte 1 → Parser mit Index {0}, Spalte 2 → Parser {1}, und so weiter. Es gibt keine Zuordnung über Spaltennamen — maßgeblich ist die Reihenfolge im SELECT.
• Jeder Spaltenwert wird in eine Zeichenkette umgewandelt und mit dem Matcher des Parsers (regulärer Ausdruck, Modus DOTALL) verarbeitet; der Formatter setzt die Capture-Groups (\1, \2, …; \0 = Gesamttreffer) zum Ergebnis der Indexvariable {0}, {1}, … zusammen. Soll eine Spalte unverändert übernommen werden, genügt der Matcher (.*) mit dem Formatter \1.
• Für jede auszuwertende Spalte muss ein Parser angelegt sein: Bei mehr Parsern als Spalten protokolliert das Modul einen Fehler, bei mehr Spalten als Parsern eine Warnung; ausgewertet wird jeweils nur die übereinstimmende Anzahl.
• Über die Option UI stellt ein Parser sein Ergebnis zusätzlich der UI-Integration/Kontext-URL zur Verfügung.

Die Felder der STARFACE-ID-Anzeige (STARFACE Feldzuordnungen: Vorname, Nachname, Firma) setzen sich anschließend aus den Indexvariablen zusammen. Die Auflösung gilt als erfolgreich, sobald mindestens ein Parser ein nicht-leeres Ergebnis liefert; erfolgreiche Ergebnisse können je Suchanbieter zwischengespeichert und optional in das STARFACE-Adressbuch übernommen werden.

Vollständiges Beispiel

Kontakttabelle kontakte in einer PostgreSQL-Datenbank crm (Rufnummern kanonisch gespeichert):

Einstellung	Wert
Resolver-Typ	SQL
Datenbank-Typ	PostgreSQL
Hostname/IP	db.example.com:5432
Datenbank-Name	crm
Benutzername / Kennwort	starface_lookup / …
Rufnummernformat	+xx

SQL-Select-Statement:

SELECT vorname, nachname, firma
FROM kontakte
WHERE telefon = '{tel}'
LIMIT 1

Bei einem Anruf von +4972115104230 führt das Modul das Statement mit WHERE telefon = '+4972115104230' aus. Ergebniszeile:

vorname (Spalte 1)	nachname (Spalte 2)	firma (Spalte 3)
Erika	Musterfrau	Muster GmbH

Parser/Ergebnis-Auswertung (je Spalte ein Parser):

Index	Matcher	Formatter	Bezeichnung
{0}	(.*)	\1	Vorname
{1}	(.*)	\1	Nachname
{2}	(.*)	\1	Firma

STARFACE Feldzuordnungen: Vorname = {0}, Nachname = {1}, Firma = {2}.

Resultierende Anzeige: Der Anruf erscheint als „Erika Musterfrau", Firma „Muster GmbH" — auf Telefondisplay, im UCC-Client und in den Ruflisten.

Anwendungsbeispiel

Ein Handwerksbetrieb pflegt Kunden in einer Branchensoftware, die keine API bietet, deren Datenbank aber lesbar ist. Ein View v_telefonbuch (Rufnummer, Name, Firma) genügt: Der SQL-Resolver fragt ihn bei jedem Anruf ab, und die Monteure sehen den Kundennamen bereits auf dem DECT-Telefon.

Fehlerbehandlung

• Verbindungsfehler: Schlägt der Verbindungsaufbau fehl (Server nicht erreichbar, Anmeldung abgelehnt), gilt die Abfrage dieses Suchanbieters als fehlgeschlagen; die Fehlermeldung des Treibers erscheint im Suchprotokoll. Andere Suchanbieter und das STARFACE-Adressbuch (Fallback) bleiben unberührt.
• Timeout: Der im Konfigurationsdialog einstellbare Timeout wirkt auf HTTP-Suchanbieter; im SQL-Pfad begrenzt das Modul Verbindungsaufbau und Ausführung nicht — es gelten die Standard-Timeouts des jeweiligen JDBC-Treibers. Sorgen Sie datenbankseitig für schnelle Antworten (Index auf der Rufnummernspalte).
• SQL-Fehler: Syntax- oder Ausführungsfehler beendet die Abfrage („Unspecified Error occurred"); die Ursache protokolliert das Modul-Log der STARFACE.
• Keine Treffer: Ein leeres Abfrageergebnis wird als „Query returned no result" protokolliert; die Auflösung gilt als trefferlos.
• Mehrere Treffer: Liefert die Abfrage mehrere Zeilen, wertet das Modul nur die erste aus und protokolliert die Warnung, dem SELECT eine LIMIT-Klausel hinzuzufügen. Welche Zeile „die erste" ist, bestimmt Ihre Datenbank — verwenden Sie ORDER BY und LIMIT 1 für deterministische Ergebnisse.
• Spalten-/Parser-Abweichung: Weniger Spalten als Parser → Fehlereintrag („Check your column selection"); mehr Spalten als Parser → Warnung, überzählige Spalten bleiben unausgewertet.
• Diagnose: Der Tab Suchanfragen protokolliert Verbindungsaufbau, ausgeführtes Statement (nach Platzhalterersetzung), Zeilenzahl und Parser-Ergebnisse. Über Einstellungen testen prüfen Sie eine Testrufnummer gezielt.

Versionierung & Kompatibilität

Die Schnittstelle ist nicht explizit versioniert. Den stabilen Vertrag bilden der Platzhalter {tel}, die positionsbasierte Zuordnung Spalte n ↔ Parser n auf der ersten Ergebniszeile sowie die vier Datenbank-Typen mit den oben genannten Treiberklassen. Änderungen und Erweiterungen dokumentieren die Release Notes der jeweiligen Modulversion; der SSH-Tunnel-Konfigurator für Cloud-Anlagen steht seit 23.5.25 bereit.