HCL Domino · SQL-Integration · Domino API-Engine
Inkrementelle Datensynchronisation zwischen HCL Domino und SQL – mehr als INSERT und UPDATE
HCL Domino · SQL-Integration · Änderungserkennung · Sicherer Wiederanlauf
Daten zwischen einer HCL-Domino-NSF und einer SQL-Datenbank zu übertragen, ist vergleichsweise einfach. Zwei unterschiedliche Datenmodelle über Monate oder Jahre hinweg konsistent zu halten, ist eine andere Aufgabe. Änderungen müssen erkannt und in die jeweils vorgesehene Richtung übertragen werden. Gelöschte oder nicht mehr freigegebene Datensätze sind korrekt zu behandeln, und unterbrochene Läufe müssen sich wiederholen lassen, ohne Duplikate oder inkonsistente Daten zu erzeugen.
Mit der Domino API-Engine lassen sich sowohl einseitige als auch bidirektionale Synchronisationsprozesse zwischen Domino und SQL realisieren. Um die grundlegenden Mechanismen nachvollziehbar darzustellen, verwendet dieser Artikel zunächst ein Beispiel von Domino nach SQL und erläutert anschließend die zusätzlichen Anforderungen, wenn Änderungen in beiden Systemen entstehen können. Im Mittelpunkt steht die Architektur einer zuverlässigen Integration – nicht die Behauptung, dass eine einzelne Funktion sämtliche Konsistenzprobleme automatisch löst.
Integrationsarchitektur
1. Ein Export ist noch keine Synchronisation
Bei einem einmaligen Export werden Dokumente gelesen und ihre Feldwerte in ein anderes System geschrieben. Ein regelmäßig ausgeführter Synchronisationsprozess muss deutlich mehr leisten: Er muss Änderungen seit dem letzten erfolgreichen Lauf ermitteln, nicht mehr benötigte Zieldatensätze erkennen, Beziehungen erhalten und nach Fehlern wieder anlaufen können.
Betrachten wir ein bewusst vereinfachtes Beispiel: Eine Domino-Anwendung verwaltet Produktdokumente, während eine Website ausgewählte Katalogdaten aus SQL-Tabellen darstellt. Ein Quelldokument enthält eine Artikelnummer, Beschreibungen, Preise, einen Verfügbarkeitsstatus und gegebenenfalls Bildanhänge. Das relationale Datenmodell könnte dafür eine Haupttabelle catalog_item, eine Tabelle catalog_price und separate Bilddatensätze verwenden.
In diesem ersten Beispiel ist die Domino-Anwendung das führende System; die SQL-Datenbank übernimmt die Änderungen. Das hält die Darstellung übersichtlich und ist keine Einschränkung der API-Engine. Ebenso ist eine Übertragung von SQL nach Domino möglich. Beide Richtungen lassen sich auch zu einem gemeinsamen Integrationsprozess verbinden, sofern Datenhoheit und Konfliktregeln festgelegt sind.
Dargestellte Richtung: Domino → SQL. Die API-Engine kann ebenso Änderungen von SQL → Domino verarbeiten. Für eine bidirektionale Synchronisation kommen ein entsprechender Rückweg und ausdrücklich definierte Konfliktregeln hinzu.
Inkrementelle Änderungserkennung
2. Neue und geänderte Dokumente erkennen
Im ersten Schritt wird ermittelt, welche Dokumente überhaupt verarbeitet werden müssen. Anstatt bei jedem Lauf sämtliche Dokumente zu lesen und abzubilden, kann ein inkrementeller Scan einen gespeicherten Synchronisationszeitpunkt mit einer Notes-kompatiblen Auswahlformel kombinieren.
Die API-Engine stellt dafür @ScanDB bereit. Der folgende Ausschnitt ist schematisch und orientiert sich an der Aufrufstruktur vorhandener Implementierungen. Für sich allein ist er kein ausführbares Skript:
ChangedIDs := @ScanDB(SourceDB; SelectionFormula; LastSyncTime; 1);
Die Auswahlformel legt fest, welche Dokumente für die Integration relevant sind. Der Zeitstempel begrenzt die Suche auf das vorgesehene Änderungsfenster. Zusammen können beide Kriterien den Verarbeitungsaufwand erheblich reduzieren, wenn sich zwischen zwei Läufen nur ein kleiner Teil des Datenbestands ändert.
Der Synchronisationszeitpunkt ist allerdings nicht einfach „die Uhrzeit, zu der das Skript beendet wurde“. Ein belastbares Verfahren legt für jeden Lauf eine definierte obere Zeitgrenze fest, verarbeitet das entsprechende Änderungsfenster und schreibt den Checkpoint erst nach erfolgreichem Abschluss der erforderlichen Operationen fort. Andernfalls können Änderungen, die während des Laufs stattfinden, zwischen zwei Synchronisationsfenstern verloren gehen. Auch Zeitstempelauflösung, inklusive oder exklusive Vergleiche sowie gleichzeitige Änderungen müssen berücksichtigt werden. Ein überlappendes Zeitfenster in Verbindung mit wiederholbaren Aktualisierungen ist eine mögliche Absicherung.
Löschungen und Sichtbarkeit
3. Löschen, Ausblenden und geänderte Auswahlbedingungen
Eine häufige Fehlerquelle bei Synchronisationsprozessen besteht darin, jedes Verschwinden eines Datensatzes als physische Löschung zu behandeln. Tatsächlich müssen mehrere Fälle unterschieden werden:
| Zustand in der Quelle | Bedeutung für das Zielsystem |
|---|---|
| Ein Dokument wurde physisch gelöscht | Den zugehörigen Zieldatensatz entfernen oder auf andere Weise außer Betrieb nehmen. |
| Ein Dokument existiert noch, erfüllt aber die Auswahlbedingungen nicht mehr | Aus der veröffentlichten Auswahl entfernen oder als inaktiv kennzeichnen. |
| Ein Dokument bleibt relevant und wurde geändert | Zugeordnete Feldwerte und abhängige Datensätze aktualisieren. |
Für physische Löschungen kann die API-Engine mit @ScanDBDeleted die seit dem letzten Checkpoint angefallenen Löschinformationen ermitteln:
DeletedUIDs := @ScanDBDeleted(SourceDB; 1; 2; LastSyncTime);
Über die stabile Domino-Dokumentkennung lassen sich die zugehörigen SQL-Daten auch dann identifizieren, wenn das ursprüngliche Dokument nicht mehr geöffnet werden kann.
Ein logisches Entfernen ist etwas anderes. Ein Produkt kann in Domino weiterhin existieren, aber seinen Status von „veröffentlicht“ auf „intern“ ändern oder aus einer Auswahlformel herausfallen. Liefert der Änderungsscan nur Dokumente zurück, welche die Formel aktuell erfüllen, kann genau der soeben ausgeschlossene Datensatz übersehen werden. Je nach Anwendung ist deshalb ein umfassenderer Statusänderungs-Scan, eine ausdrückliche Prüfung des Veröffentlichungsstatus oder ein regelmäßiger Abgleich mit dem gesamten aktuell zulässigen Datenbestand erforderlich.
Hinzu kommt eine betriebliche Grenze: Domino bewahrt Löschinformationen nicht unbegrenzt auf. Deletion Stubs unterliegen den Bereinigungseinstellungen der Datenbank. War ein Synchronisationsdienst länger außer Betrieb, als die relevanten Löschinformationen aufbewahrt werden, lassen sich möglicherweise nicht mehr alle historischen Löschungen inkrementell feststellen. Dann ist ein vollständiger Bestandsabgleich die sicherere Wiederherstellungsstrategie. Siehe hierzu die HCL-Domino-Dokumentation zu Deletion Stubs und Purge-Intervallen.
Relationale Datenabbildung
4. NSF-Dokumente auf relationale Strukturen abbilden
Domino-Dokumente und relationale Tabellen organisieren Informationen unterschiedlich. Ein einzelnes Dokument kann Mehrfachwerte, sprachabhängige Beschreibungen, logisch verschachtelte Strukturen oder Attachments enthalten. Im SQL-Zielsystem werden diese Informationen möglicherweise auf einen Hauptdatensatz und mehrere abhängige Tabellen verteilt.
Ein Domino-Produktdokument könnte beispielsweise auf folgende Tabellen abgebildet werden:
| SQL-Tabelle | Aufgabe |
|---|---|
catalog_item | Identität, Artikelnummer, Bezeichnung und Verfügbarkeit |
catalog_price | Ein oder mehrere Preisdatensätze, gegebenenfalls nach Region |
catalog_text | Sprachabhängige Beschreibungen |
catalog_image | Referenzen auf Bilder und gespeicherte Größenvarianten |
Die Integration benötigt daher eine dauerhafte Zuordnung zwischen der UNID des Quelldokuments und den Datensätzen im Ziel. Eine von der SQL-Datenbank erzeugte ID kann intern sinnvoll sein. Die Quell-UNID oder ein anderer stabiler fachlicher Schlüssel muss aber dafür sorgen, dass wiederholte Läufe denselben logischen Datensatz erkennen, statt ein Duplikat einzufügen.
Für wiederkehrende INSERT- und UPDATE-Operationen eignen sich Prepared Statements besonders gut. Die API-Engine stellt hierfür unter anderem @MySQLCreatePreparedStatement und @MySQLExecutePreparedStatement bereit. Parameter – soweit unterstützt auch Binärpuffer – werden dabei getrennt vom SQL-Befehlstext übergeben. Das ermöglicht typisierte Werte und vermeidet es, für jeden Datensatz die komplette SQL-Anweisung neu zusammenzusetzen.
Bei abhängigen Tabellen ist auch die Reihenfolge der Schreiboperationen entscheidend. Das Ersetzen von Kinddatensätzen, das Aktualisieren des Hauptdatensatzes und das Entfernen veralteter Beziehungen sollten möglichst als konsistente Einheit behandelt werden, sofern die Zieldatenbank Transaktionen unterstützt. Die API-Engine stellt die benötigten Bausteine bereit; die erforderlichen Konsistenzregeln muss das Skript jedoch selbst umsetzen.
Attachments und Binärdaten
5. Attachments und Binärdaten gehören zum Datenmodell
In vielen Anwendungen umfasst eine Synchronisation mehr als Text- und Zahlenfelder. Ein Domino-Dokument kann Produktbilder oder andere Binärdaten als Anhänge enthalten, während das Zielsystem mehrere Bildauflösungen und zugehörige Metadaten erwartet.
Ein bereits eingesetztes Verarbeitungsmuster der API-Engine liest einen Anhang in einen Speicherpuffer, erzeugt mit den Bildverarbeitungsfunktionen die benötigten Varianten und überträgt die resultierenden Binärdaten über Prepared Statements nach SQL. Metadaten wie Dateiname, ursprüngliche Dateigröße und Änderungszeitpunkt helfen bei der Entscheidung, ob ein Bild erneut verarbeitet werden muss. Ändert sich lediglich die Reihenfolge von Bildern, kann es genügen, einen SQL-Metadatenwert zu aktualisieren, ohne das Bild neu zu konvertieren.
Das verdeutlicht eine allgemeine Regel: Synchronisiert werden muss das relevante Geschäftsobjekt, nicht nur die sichtbaren Felder eines Dokuments. Dieses Objekt kann sich über mehrere Tabellen, Anhänge und daraus abgeleitete Daten erstrecken. Die Verarbeitung von Binärdaten ist für die grundlegende SQL-Synchronisation nicht zwingend nötig, zeigt aber, warum reale Integrationen häufig deutlich anspruchsvoller sind als ein zeilenweiser Export.
Checkpoint-Verwaltung
6. Fehlerbehandlung, Checkpoints und sicherer Wiederanlauf
Angenommen, ein Job hat bereits 500 Dokumente übertragen, als die SQL-Verbindung abbricht. Einige Änderungen im Zielsystem sind möglicherweise bereits bestätigt, andere noch nicht. Wird der gesamte Lauf ohne weitere Vorkehrungen wiederholt, können Duplikate oder inkonsistente Beziehungen entstehen.
Ein praxistauglicher Synchronisationsprozess benötigt deshalb mehrere Schutzmechanismen:
- Wiederholbare Operationen: Wird ein Dokument erneut verarbeitet, muss der bestehende Zieldatensatz aktualisiert werden, statt eine weitere Kopie anzulegen. Stabile Schlüssel und geeignete SQL-Constraints unterstützen dies.
- Ausdrückliche Fehlererfassung: Verbindungsabbrüche, fehlgeschlagene SQL-Anweisungen und unvollständige Schreibvorgänge in abhängigen Tabellen müssen für den Job erkennbar sein und dürfen nicht nur als Text im Log erscheinen.
- Kontrollierte Checkpoints: Der gespeicherte Wert
LastSyncTimewird erst fortgeschrieben, wenn das gewählte Verarbeitungsfenster gemäß der festgelegten Fehlerbehandlungsstrategie erfolgreich abgeschlossen wurde. - Transaktionsgrenzen: Zusammengehörige SQL-Änderungen sollten möglichst gemeinsam bestätigt werden. Eine SQL-Transaktion bezieht die Domino-Seite jedoch nicht automatisch in dieselbe verteilte Transaktion ein.
- Bestandsabgleich nach außergewöhnlichen Unterbrechungen: Ein regelmäßiger Vollabgleich oder Reparaturmodus ist hilfreich, wenn die Änderungshistorie unvollständig ist oder die Synchronisation längere Zeit ausgefallen war.
Wird ein Fehler registriert und der vorherige Checkpoint beibehalten, kann ein späterer Lauf dasselbe Änderungsfenster erneut bearbeiten. Bereits ausgeführte SQL-Schreibvorgänge werden dadurch allein allerdings nicht rückgängig gemacht. Deshalb gehören idempotente Aktualisierungen, Eindeutigkeitsbedingungen und passend gewählte Transaktionsgrenzen zur Checkpoint-Verwaltung dazu.
Bei länger laufenden Jobs lohnt es sich außerdem, die Anzahl ausgewählter, eingefügter, aktualisierter, entfernter, übersprungener und fehlgeschlagener Datensätze zu protokollieren. Damit lassen sich ungewöhnliche Abläufe besser erkennen und beispielsweise „Es gab keine Änderungen“ von „Der Job hat nichts verarbeitet“ unterscheiden.
Betrieb und Administration
7. Vom Skript zum betreibbaren Integrationsprozess
Ein Synchronisationsskript ist nur ein Bestandteil einer produktiven Lösung. Im Umfeld der Domino API-Engine übernehmen mehrere getrennte Domino-Datenbanken Aufgaben bei Steuerung, Konfiguration und Protokollierung:
| Komponente | Aufgabe |
|---|---|
| APICTRL | Enthält Skripte, Batches und Ereignisdefinitionen einschließlich zeitgesteuerter und anderer auslöserbasierter Jobs. |
| TOOLBOX | Verwaltet Skriptparameter. Für dasselbe Skript können unterschiedliche Parametersätze für verschiedene Server, Kunden oder Einsatzszenarien existieren. |
| APILOG | Speichert die Engine-Protokollausgaben in einem eigenen Logdokument pro Taskausführung. |
| APIJOB | Stellt bei Bedarf die Standard-Mail-In-Datenbank zur Auslösung von Jobs durch eingehende E-Mails bereit. |
Diese Trennung ist im Betrieb hilfreich. Die Verarbeitungslogik eines Synchronisationsskripts kann unverändert bleiben, während ein anderer Parametersatz beispielsweise einen anderen NSF-Pfad, ein anderes Zielsystem oder geänderte Auswahlformeln festlegt. Ausführungsintervalle und Fehlerverhalten lassen sich unabhängig vom eigentlichen Mapping-Code verwalten. Jeder Lauf hinterlässt zugleich eine nachvollziehbare Protokollierung.
Damit entfallen weder Tests noch Zugriffskontrollen, Backups, Monitoring oder eine sorgfältige Fehlerbehandlung. Die Architektur ermöglicht es aber, eine Integration als wiederholbar ausgeführten, konfigurierbaren serverseitigen Job statt als isoliertes Einmalskript zu betreiben.
Bidirektionale Integration
8. Erweiterung auf bidirektionale Synchronisation
Die API-Engine beschränkt eine Integration keineswegs auf die Übertragung von Domino nach SQL. Da sich mit ihr beide Systeme lesen und aktualisieren lassen, können Änderungen ebenso von SQL zurück nach Domino übertragen werden. Eine bidirektionale Lösung kann gemeinsame fachliche Schlüssel oder eine eigene Zuordnung von Domino-UNIDs zu SQL-IDs verwenden.
Die zusätzliche Komplexität entsteht vor allem durch die Synchronisationsregeln und weniger durch die grundsätzliche Fähigkeit, Daten auf beiden Seiten zu lesen und zu schreiben. Für eine Zweiwegesynchronisation werden typischerweise folgende Mechanismen benötigt:
- Änderungserkennung auf beiden Seiten: Domino-Änderungen lassen sich beispielsweise mit
@ScanDBermitteln. Auf SQL-Seite werden geeignete Zeitstempel, Änderungstabellen oder andere datenbankspezifische Change-Tracking-Verfahren benötigt. - Geklärte Datenhoheit: Es muss feststehen, ob Domino oder SQL für bestimmte Datensätze, Felder oder Geschäftsprozesse führend ist. Nicht jedes Feld muss in beiden Richtungen beschreibbar sein.
- Konfliktbehandlung: Was geschieht, wenn dieselben Geschäftsdaten in beiden Systemen geändert wurden, bevor der Abgleich erfolgt? Regeln können auf Feldzuständigkeiten, Versionsinformationen oder einer ausdrücklichen Prüfung beruhen. Zeitstempel allein reichen nicht immer aus.
- Vermeidung von Rückkopplungen: Eine von der Integration geschriebene Änderung darf nicht unbegrenzt als neue Änderung zwischen den Systemen hin- und herwandern. Dafür können Herkunftskennzeichen, Wertvergleiche oder ähnliche Verfahren notwendig sein.
- Wiederanlauf in beiden Richtungen: Fortschritt und Fehler müssen je Richtung nachvollziehbar sein. Wiederholungsversuche dürfen weder Duplikate erzeugen noch unbeabsichtigt neuere Daten überschreiben.
Bidirektional bedeutet nicht zwangsläufig, dass jedes Feld überall frei bearbeitet werden darf. Eine kontrollierte Verteilung der Zuständigkeiten zwischen Domino und SQL ist häufig leichter zu betreiben und nachzuvollziehen als uneingeschränkte parallele Änderungen.
Diese Anforderungen führen zu einem umfangreicheren Skript und erfordern anwendungsspezifische Entscheidungen. Sie sind jedoch eine konsequente Erweiterung derselben Engine-basierten Integrationsarchitektur, die das vorangegangene Beispiel verwendet.
Einsatzbereiche und Grenzen
9. Wo dieser Ansatz sinnvoll ist – und wo seine Grenzen liegen
Die inkrementelle Synchronisation zwischen Domino und SQL ist überall dort interessant, wo Anwendungen trotz unterschiedlicher Datenmodelle Informationen austauschen müssen. Einseitige Datenflüsse eignen sich etwa für Websites, Berichtssysteme und andere nachgelagerte Anwendungen. Bidirektionale Prozesse werden relevant, wenn sowohl Domino als auch eine externe Anwendung Änderungen zu einem gemeinsamen Geschäftsprozess beitragen. Beide Varianten können eine schrittweise Modernisierung unterstützen, ohne eine funktionierende Domino-Anwendung unmittelbar ersetzen zu müssen.
Eine systemübergreifende Synchronisation ist nicht mit der nativen Domino-Replikation gleichzusetzen. Die reguläre Replikation gleicht Domino-Repliken ab; eine Domino-SQL-Integration verbindet unterschiedliche Datenmodelle und erfordert in der Regel anwendungsspezifische Transformationen und Konsistenzregeln. Die API-Engine stellt die entsprechenden Zugriffs- und Verarbeitungsfunktionen bereit. Welche Synchronisationsrichtungen, Konfliktstrategien und betrieblichen Absicherungen verwendet werden, wird für jede Integration festgelegt.
Auch mit LotusScript, Java oder Integrationsplattformen wie HCL Enterprise Integrator lassen sich Teile oder sämtliche dieser Aufgaben umsetzen. Der Ansatz der API-Engine besteht darin, Domino-spezifische Scan- und Verarbeitungsfunktionen mit SQL-Operationen, Transformation, Zeitplanung, Parametrisierung und Protokollierung in einer gemeinsamen Engine-Umgebung zu verbinden. Welche Lösung geeignet ist, hängt von der vorhandenen Infrastruktur und den Anforderungen des jeweiligen Projekts ab.
Fazit
Fazit: Synchronisation bedeutet kontrollierte Zustandsänderungen
Zuverlässige Synchronisation besteht nicht in erster Linie darin, INSERT-, UPDATE– und DELETE-Anweisungen auszuführen. Entscheidend ist, die richtigen Änderungen zu erkennen, zu verstehen, warum ein Dokument nicht mehr zur Zielauswahl gehört, Beziehungen zwischen unterschiedlichen Datenmodellen zu erhalten und unterbrochene Läufe sicher wiederaufnehmen zu können.
Die Domino API-Engine bietet dafür praktische Funktionen und eine betriebliche Grundlage – sowohl für einseitige als auch für bidirektionale Integrationsprozesse. Das Beispiel in diesem Artikel betrachtet bewusst zunächst nur eine Richtung, um Änderungserkennung, Löschungen und Wiederanlauf nachvollziehbar zu halten. Datenhoheit, Konfliktregeln, Fehlerbehandlung, SQL-Datenmodell und Wiederanlaufstrategie bleiben konkrete Entwurfsentscheidungen der jeweiligen Anwendung.
Die API-Engine näher kennenlernen
Die hier zugrunde liegenden produktiven Implementierungen veröffentlichen wir bewusst nicht, da sie projektspezifische Datenstrukturen und Geschäftslogik enthalten.