Vorwort

CData-Connectoren sind JDBC-Treiber, die die Anbindung an verschiedenste Anwendungen über deren APIs ermöglichen. Diese Connectoren können Sie zusätzlich zu Ihren bestehenden Modulen gegen eine monatliche Abonnement-Gebühr erwerben.

Der Clou dabei ist, dass die HTTP-Requests nicht umständlich selbst aufgebaut werden müssen, sondern in Form von SQL-Kommandos an den Connector übergeben werden. Der Connector wandelt diese in den benötigten HTTP-Request um, kümmert sich um den API-Aufruf und liefert die Daten tabellarisch aufbereitet zurück. Damit werden komplizierte API-Aufrufe und aufwändige Authentifizierungen deutlich vereinfacht.

Zugang im Update-Center

Den neuen Connector herunterladen

Wenn das Abonnement für Ihren Connector erfolgreich aktiviert wurde, erhalten Sie von unserem Lizenzteam eine E-Mail, in der die Aktivierung der Lizenz bestätigt wird. Danach steht Ihnen der Connector unter Verwaltung → Update-Center zur Verfügung.

Dort finden Sie im Bereich Aktualisierte Connectoren (Kachel links unten) alle Connectoren, die für Ihre Lizenz freigeschaltet wurden. Diese können Sie herunterladen mit einem Klick auf Alle Connectoren herunterladen (gespeichert werden sie im Verzeichnis ./extlib). Hinweis: Danach muss der Integration Server neu gestartet werden, damit die Connectoren aktiv werden.

Presets herunterladen

Um die Konfiguration des Connectors so einfach wie möglich zu gestalten, stellen wir für jeden Connector Presets zur Verfügung. Um sicherzustellen, dass Sie die aktuellsten Presets haben, überprüfen Sie bitte im Update-Center, ob in der rechten oberen Ecke (Vorlagen (Presets)) die Datei preset.xml zum Download bereitsteht. Klicken Sie einfach auf presets.xml und die neuen Presets werden heruntergeladen und eingespielt.

Connector konfigurieren

Nachdem Sie den Connector und die Presets geladen und den Integration Server neu gestartet haben, ist es Zeit, die Verbindung zu konfigurieren. Wechseln Sie dazu zu Verwaltung → Datenbanken/Connectoren.

Legen Sie dort eine neue Verbindung an, indem Sie auf das Symbol in der rechten unteren Ecke klicken oder mit der rechten Maustaste klicken und aus dem Kontextmenü Neue Verbindung auswählen. Die Presets finden Sie dann unter Vorlage wählen → Vorlagen (Presets).

Suchen Sie den Dienst, den Sie anbinden möchten. Nach einem Klick auf einen Eintrag, öffnet sich ein Wizard, der die wichtigsten Parameter für den Connector abfragt. Beispiel:

Jeder Parameter wird durch einen Tooltip beschrieben. Diese Tooltips stammen aus der CData-Dokumentation und sind immer in englischer Sprache.

Wichtiger Hinweis: Der Parameter Logfile in der Zeile Absolute path for the Logfile muss ein absoluter Pfad sein. Das Logfile selbst muss dort als leere Datei angelegt werden. Nur so können die Connectoren ein Log schreiben.

Beispiele:

Windows: C:\Lobster\logs\CData\BigQuery.log → Im Verzeichnis ./logs muss manuell das Verzeichnis CData angelegt werden.

Linux: /opt/Lobster/logs/CData/BigQuery.log → Im Verzeichnis ./logs muss manuell das Verzeichnis CData angelegt werden.

Es gibt auch Parameter, die automatisch im Hintergrund als JDBC Properties angelegt und nicht im Wizard abgefragt werden.

Dies sind die Parameter Verbosity mit dem Wert 1 und Max Log File Size mit dem Wert 10MB. Diese werden im Abschnitt Fehlerbehebung unten konkret erklärt.

Je nach Connector können weitere Parameter voreingestellt sein. Diese finden Sie unter dem Reiter JDBC Properties:

Bei diesem Connector wurden beispielsweise die Parameter AuthScheme, InitiateOAuth und OAuthJWTCertType hinzugefügt. Außerdem wurde der Verbosity Level manuell auf 5 gesetzt.

Wichtiger Hinweis: Unsere Presets verwenden die Parameter gemäß der CData-Dokumentation. Es ist möglich, dass Parameter fehlen und in den JDBC Properties ergänzt werden müssen, oder dass zu viele Parameter vorhanden sind und aus den JDBC Properties entfernt werden müssen. Weiterhin ist immer die Dokumentation der jeweiligen Anwendung zu beachten. Oft ist es notwendig, Berechtigungen zu setzen, Applikationen zu erstellen und verschiedene Access Token zu kopieren.

Unter dem Reiter Einstellungen wird im Feld Database der Connection String erstellt, der in der Regel einen Parameter enthält. Theoretisch können Sie hier auch weitere Parameter angeben, anstatt die JDBC Properties zu verwenden, aber dadurch wird der String unübersichtlich. Wir empfehlen daher, für Parameter immer die JDBC Properties zu verwenden.

Im Feld Driver wird der Pfad zur Treiberklasse eingetragen. Bitte ändern Sie diesen Wert nicht.

Wenn ein Connector einen Benutzer und ein Passwort benötigt, tragen Sie diese bitte immer unter User und Password ein und nicht im Connection String oder in den JDBC Properties.

Der Catalog Name hat keinen Einfluss und wird automatisch gefüllt.

Beispiel:

Wenn alle Parameter eingestellt sind, klicken Sie auf Anwenden. Es wird nun automatisch ein Eintrag in der Datei ./etc/database.xml erstellt und sofort eine Verbindung über den Connector hergestellt. Ein Neustart des Integration Servers ist daher nicht erforderlich.

CData-Dokumentation

Wenn Sie nicht genau wissen, welche Informationen Sie benötigen, finden Sie weitere Informationen in der CData-Dokumentation des jeweiligen Connectors. Sie erreichen diese, indem Sie unter Verwaltung → Datenbank/Connectoren auf den Button Business Connector klicken, den gewünschten Eintrag aus der Liste auswählen (unten links gibt es auch eine Suchfunktion) und dann auf den ersten Link in der Beschreibung klicken.

Sie finden die Dokumentation auch auf der CData-Webseite. Klicken Sie dort auf den gewünschten Connector, wählen Sie dann auf der neuen Seite in der Leiste oben rechts Docs und auf der wiederum folgenden Seite die Online-Dokumentation für die JDBC-Version des Connectors.

Testen der Verbindung

Ein Verbindungstest kann über das Plugin SQL-Konsole erfolgen.

Wählen Sie dort den erstellten Alias aus und klicken Sie auf Tables/Procedures. Dadurch wird im Hintergrund eine Abfrage an den Connector gestellt und dieser prüft, ob im angebundenen System Tabellen vorhanden sind.

Direkt nach dem Anlegen kann es vorkommen, dass noch keine Tabellen, sondern nur Prozeduren angezeigt werden. Ein erneuter Klick auf den Button sollte dann zum Erfolg führen. Der Grund dafür ist, dass der Connector die Daten zunächst cachen muss. Manchmal ist auch ein Neustart des Integration Servers notwendig, um den Cache des Connectors zu erneuern.

Wird nach dem Klick auf die Schaltfläche kein Fenster mit den Tabellen und Prozeduren angezeigt, ist ein Fehler beim Abruf aufgetreten. In diesem Fall müssen die Einstellungen des Connectors noch einmal überprüft werden. Beachten Sie hier den Abschnitt Fehlerbehebung unten.

Versuchen Sie nun einen Select auf die gefundenen Tabellen abzusetzen, und prüfen Sie, ob Daten zurückkommen. Beachten Sie dabei die nötige Syntax gemäß der CData-Dokumentation für den jeweiligen Connector.

Für den Fall mit bigquery liefert folgender Select Daten zurück. Wenn Sie Daten erhalten, ist die Installation abgeschlossen!

Fehlerbehebung

Sollten beim Testen der Verbindung Fehler auftreten, erhöhen Sie in den Connector-Einstellungen (Verwaltung → Datenbanken/Connectoren) den Verbosity Level des entsprechenden Connectors auf 5. Wichtiger Hinweis: Nach der Fehlerbehebung unbedingt wieder auf 1 zurücksetzen!

Nach einem Klick auf Anwenden wird die Verbindung zum Connector getrennt und neu aufgebaut. Führen Sie anschließend den Test erneut durch. Nun finden Sie im Log alles, was der Connector macht, also auch Fehler, die von der API gemeldet werden. Das Log kann Rückschlüsse auf vergessene oder falsche Parameter geben.

Wenn Sie Hilfe benötigen, senden Sie uns bitte das Log (in diesem Fall das aktuelle Log leeren, die Verbindung zum Connector erneut herstellen, indem Sie unter Datenbanken/Connectoren den Eintrag öffnen und mit Anwenden wieder schließen und den Test wiederholen) und eine kurze, aber aussagekräftige Beschreibung des Problems an support@lobster.de. Wir werden versuchen zu helfen und bei Bedarf auch den CData-Support einschalten. Wenn der CData-Support involviert ist, müssen Sie jedoch mit einer Bearbeitungszeit von bis zu mehreren Tagen rechnen. Es kann auch vorkommen, dass CData einen Fehler beheben muss, was ebenfalls zu einer längeren Laufzeit der Anfrage bei CData führen kann.

Features

CData hat nicht immer alle Funktionen einer API in seinen Connectoren implementiert. Wenn Sie auf eine Funktion zugreifen möchten, die noch nicht implementiert ist, leiten wir Ihre Anfrage gerne an CData weiter und bitten darum, die Funktion zu implementieren. Wir können jedoch nicht versprechen, dass CData dem nachkommt und können auch keine Aussage darüber treffen, wie lange CData für die Implementierung benötigt. Aus Erfahrung können wir aber sagen, dass CData immer versucht, Feature-Wünsche umzusetzen und mit einer Wartezeit von ca. 3 Wochen zu rechnen ist. Deutlich längere Wartezeiten sind jedoch möglich.

Updates

Wenn CData einen Bugfix oder ein neues Feature liefert, stellen wir Ihnen den Connector über das Update-Center zur Verfügung. Nach dem Download und einem Neustart des Integration Servers ist die neue Version des Connectors aktiv.

Es empfiehlt sich, den alten Connector vor dem Update zu sichern, da dieser überschrieben wird. Im Falle eines Fehlers im neuen Connector, können Sie dann die alte, funktionierende Version schnell wiederherstellen.

Wir liefern von Zeit zu Zeit neue Versionen der Connectoren aus, wenn ein Update erforderlich ist.