Version: GSB7.5_7.6Import-Dispatcher
- Anwendungsbeispiel
- Installation
- Aufruf des Import-Dispatchers
- Importerkonfiguration
- Eigene Skripte
- E-Mail-Benachrichtigung
Häufig werden Daten nicht manuell über den Cap-Editor erfasst, sondern aus externen Quellen importiert und publiziert, also ohne Benutzereingriffe auf der Website dargestellt. Eine geläufige Anwendung sind Nachrichtentexte aus einem vertrauenswürdigen Fremdsystem, die in einem speziellen XML-Format geliefert, transformiert, als News-Dokument importiert und über DynDocSearchEnt-Objekte aktuell und zielgruppengerecht präsentiert werden.
Der von CoreMedia mitgelieferte Importer kann - eine entsprechende Konfiguration vorausgesetzt - für dieses Szenario prinzipiell eingesetzt werden. Dazu müssen die Daten in die richtige Inbox geschrieben und ggf. der Importer gestartet werden. Allerdings kann es hier Probleme geben:
- Bei mehreren Importer-Typen muss die richtige Inbox gewählt werden. Eine automatische Verteilung anhand des Dateinamens ist nicht möglich.
- Der Import darf nicht beginnen, bevor die Dateien komplett in der Inbox liegen.
- Mögliche Viren (z. B. Makroviren in Office-Dokumenten) können von außen ins System gelangen.
- Bei Problemen kann keine E-Mail verschickt werden.
- Externe Verarbeitungsschritte (etwa Transformationen in beliebigen Programmiersprachen) sind nur umständlich zu integrieren.
Der Import-Dispatcher setzt genau hier an: Er überwacht Inboxen auf das vollständige Hochladen von Dateien, lässt sie in einem Quarantäne-Verzeichnis von einem Virenscanner überprüfen und übergibt sie dann an einen Importer. Es können je nach Muster des Dateinamens verschiedene Inboxen und Importer eingesetzt werden.
Der Hauptzweck liegt darin, in einer Multi-Mandanten-Installation mit möglicherweise langsamen Verbindungen eine sichere und automatische Möglichkeit für den Import zu bieten. Für gelegentliche Importe auf einer eigenständigen, dezentralen Installation ist ein Import-Dispatcher wahrscheinlich nicht erforderlich, wenn ohnehin keine Viren zu erwarten sind (bei Einspielungen von XML aus einem Intranet heraus) und keine Verteilungsregeln zu beachten sind.
Anwendungsbeispiel
Die folgende Grafik verdeutlicht exemplarisch die Verteilung der Daten in die jeweiligen Ordner. Der eigentliche Import erfolgt anschließend aus den jeweiligen Importer-Inboxen heraus. Im Beispiel sind 3 unterschiedliche Importer-Typen konfiguriert, wobei zwei davon (Importer X und Y) die zugehörigen Dateien anhand des Namens identifizieren. Alle Dateien, die nicht nach diesen Regeln zugeordnet werden können, erhält der Default-Importer (welcher auch ein Dummy-Importer ohne Funktion sein kann).
- Schritt 1: Nach dem letzten Durchlauf des Import-Dispatchers befinden sich 9 Dateien in der zentralen inbox. Alle, die eine entsprechende, mit _finish endende Markierungsdatei besitzen, sind komplett hochgeladen und werden ins quarantine -Verzeichnis verschoben. Hier hat q.txt keinen Marker (vermutlich läuft gerade eine länger andauernde Übertragung) und wird somit ignoriert. Die Markierung "_finish" ist bei Bedarf über die Property finishPattern zu ändern.
- Schritt 2: Nach dem Verschieben in quarantine prüft der Virenscanner jede Datei auf Viren und sonstige Schädlinge. Wurde ein solcher entdeckt, verschiebt der Import-Dispatcher die befallene Datei in infected, die übrigen beläßt er vorerst in quarantine. Im Beispiel ist inf.txt infiziert und wird verschoben.
- Schritt 3: Ab hier werden die Filterregeln auf die Dateinamen angewendet. Der Importer X fordert über den Konfigurationseintrag includePattern=^a.*, dass die zugehörigen Dateien mit dem (kleinen) Buchstaben a beginnen müssen. Die Datei a.txt wird deshalb nach importerXinbox verschoben.
Hinweis: Die Reihenfolge der Importer ( activeImporters=x,y ) wird beachtet.
- Schritt 4: Importer Y fordert, dass die Dateien mit b beginnen müssen, somit erhält die importerYinbox die Datei b.txt.
- Schritt 5: Die Datei c.txt wurde bisher durch keine Regel abgedeckt. Da der Default-Importer als letzter ausgewertet wird, verschiebt der Import-Dispatcher c.txt nach defaultImporterInbox.
Nachdem die hier skizzierte Verteilung abgeschlossen ist, beginnt der eigentliche Importvorgang aus den jeweiligen Importer-Inboxen (sofern mindestens eine Datei dort eingetroffen ist).
Installation
Der Import-Dispatcher wird mit einem ant-Target installiert. Die erforderliche Properties-Datei kann analog zur Datei build_import_dispatcher_ examples.properties vorgenommen werden.
Hier ein Beispiel für build_import_dispatcher_MYCONFIG.properties mit dem Mandanten "customer1":
<syntaxhighlight lang="xml" enclose="div">
- Installationsverzeichnis
import_dispatcher_home=/opt/bk_cms/ImportDispatcher
- Konfiguration der Fehler-E-Mails:
emergency_mail_receivers=import.admin@domain.example
emergency_mail_sender=noreply@domain.example
emergency_mail_subject=Emergency Mail customer1!!
emergency_mail_host=localhost
emergency_mail_login=mailserverLogin
emergency_mail_password=mailserverPassword
emergency_mail_protocol=smtp
emergency_mail_encoding=
- Umgebungsvariablen, die den externen Programmen übergeben werden. Wichtig für den Cap-Importer!
env_PATH=/usr/local/bin:/usr/bin:/bin
env_USER=cmadmin
env_LOGNAME=cmadmin </syntaxhighlight>
Starten der Installation:
<syntaxhighlight lang="xml" enclose="div">> bolant installImportDispatcher -propertyfile buildProperties/build_import_dispatcher_MYCONFIG.properties</syntaxhighlight>
Aufruf des Import-Dispatchers
Der Import-Dispatcher ist dafür gedacht, zyklisch aufgerufen zu werden (etwa in einem cronjob). Als Parameter erhält er eine individuelle Konfigurationsdatei, welche die Verzeichnisse und die auszuführenden Programme angibt. Manche Angaben werden bereits in der Datei conf/importdispatcher/local.properties definiert und können in der Parameterdatei überschrieben werden. Das ist z. B. bei dem Virenscanner sinnvoll, da dieser normalerweise für alle eingehenden Daten verwendet werden kann. In speziellen Fällen könnte aber jederzeit ein anderes Produkt eingesetzt werden.
Die verschiedenen Konfigurationsdateien sind für jeden Mandanten anzupassen. Die eigentliche Installation des Import-Dispatchers braucht auf einer Maschine nur einmal vorgenommen werden, allerdings empfiehlt sich bei einer Multi-Mandanten-Umgebung jeweils eine eigene Installation pro Mandant. Dies hat den Vorteil, dass die Logdateien getrennt sind.
Importerkonfiguration
Dieser Abschnitt erläutert die Konfiguration einer solchen individuellen Steuerdatei. Es handelt sich um eine Properties-Datei (Schlüssel-Wert-Paare), in der grundsätzlich die folgenden Informationen eingetragen werden:
- Pfad zur Inbox des Mandanten (oder eine der Mandanten-Inboxen)
- Quarantäne-Verzeichnis (hier werden die komplett hochgeladenen Dateien von Virenscanner überprüft)
- Verzeichnis für die als infiziert erkannten Dateien
- die verwendeten Importer, falls mehr als der Standard-Importer konfiguriert werden (Unterscheidung nach Dateinamen-Muster)
- Warn-Mail-Informationen (Server, Subject, Empfänger, ...)
- Informationen zum Standard-Importer
- Optional: ein anderer Virenscanner
Für jeden verwendeten Importer - namentlich aufgelistet unter dem Schlüssel activeImporters - muss ein Konfigurationsblock vorhanden sein, in dem die Eigenschaften dieses Importers (etwa das Binary, die Inbox, ein Skript zur Statusermittlung, usw.) genauer beschrieben werden. Prinzipiell gibt es zwei Varianten: Entweder die direkte Verwendung des Importers oder eigene Skripte, die dann nach beliebigen Transformationsschritten selbst den Importer starten sollten.
Wird der CoreMedia-Importer direkt benutzt, erkennt dies der Import-Dispatcher anhand des Programmnamens und kann zwei Überprüfungen automatisch vornehmen, nämlich
- Tests, ob der Importer gerade läuft,
- Tests, ob nach einem Importvorgang die Dateien ordnungsgemäß importiert werden konnten.
Bei eigenen Skripten ist optional, für diese Tests spezielle Programme anzugeben. Es ist allerdings empfehlenswert, den Importstatus mit einem geeigneten Kommandozeilenaufruf nachhalten zu können. Werden die Dateien direkt in eine Cap-Importer-Inbox geschrieben und der zugehörige Importer gestartet, wird automatisch das status -Kommando aufgerufen und werden nach dem Import die Verzeichnisse bak/ und err/ der Inbox kontrolliert.
Im Folgenden nun eine Beispielkonfiguration zu der /some/directory/import_dispatcher_customer1.properties, in der statt dem Virenscanner und den Importern Testskripte eingetragen sind:
<syntaxhighlight lang="xml" enclose="div">
- Mail-Einstellungen (wird nur bei Problemen verschickt)
emergencyMailReceivers=admin@domain.example
emergencyMailSender=noreply@domain.example
emergencyMailHost=mail.domain.example
emergencyMailSubject=Importdispatcher-Meldung
emergencyMailLogin=
emergencyMailPassword=
emergencyMailProtocol=smtp
sourceDirectory=/opt/bk_cms/ImportDispatcher/data/source
quarantineDirectory=/opt/bk_cms/ImportDispatcher/data/quarantine
targetDirectory=/opt/bk_cms/ImportDispatcher/data/defaulttarget
infectedDirectory=/opt/bk_cms/ImportDispatcher/data/infected
virusscanCommand=/opt/bk_cms/ImportDispatcher/jobs/bin/vscan.pl
stopIfVirusDetected=false
- in den globalen oder individuellen Konfigurationen möglich - bei Bedarf:
- finishPattern=_myFinishKeyword
- Die Importerlines
- -----------------------------------------------------------------------
- mögliche Platzhalter in den Args
- FILELIST FILELIST EACHFILE EACHFILE_ABS
- Default-Importer. Immer notwendig
- Inbox des Default-Importers
defaultImportInbox=/opt/CoreMedia/importer/importerInboxes/defaultInbox
- Das aufzurufende Programm, hier der Importer von CoreMedia. Bitte beachten Sie
- die Angabe der Importer-Konfiguration (hier: cm-my-default-importer) an dieser Stelle!
- Beim CoreMedia-Importer gehört dies mit in das Executable / Command!
defaultImportCommand=/opt/CoreMedia/importer/bin/cm cm-my-default-importer
- exit code des Default-Importers im Erfolgsfall (alle anderen: Misserfolg)
defaultImportSuccessCode=0
defaultImportArgs=start
- Die aktivierten Importer:
activeImporters=x,y
- --------------------------- Testimporter x
importer.x.importerInbox=/opt/bk_cms/ImportDispatcher/data/importerXinbox
importer.x.includePattern=^.*[a-g].*$
importer.x.excludePattern=^.*a.*$
importer.x.executable=/opt/bk_cms/ImportDispatcher/jobs/bin/checker1.pl
importer.x.params=-x -y FILELIST
importer.x.successCode=0
importer.x.canReturnStatus=true
importer.x.canReturnSuccess=false
- customImporter: Wenn eigene Scripts verwendet werden, die den Status und
- den Erfolg testen.
- Beim CoreMedia-Importer sind diese Funktionen fest codiert und werden immer aufgerufen.
- Status (ist der Importer bereit?)
importer.x.customImporterStatusCommand=/opt/bk_cms/ImportDispatcher/jobs/bin/checker1.pl 0
importer.x.customImporterStatusReadyCode=0
- Success (wurde erfolgreich konvertiert/importiert?)
- In diesem Beispiel gibt es keine Kommandos, um den Erfolg zu prüfen. Deshalb ist
- canReturnSuccess auch auf false gesetzt. Der Importdispatcher nimmt immer "Erfolg" an.
importer.x.customImporterSuccessCommand=
importer.x.customImporterSuccessArgs=
importer.x.customImporterSuccessCode=
- --------------------------- Testimporter y
importer.y.importerInbox=/opt/bk_cms/ImportDispatcher/data/importerYinbox
importer.y.includePattern=^.*y.*$
importer.y.excludePattern=^.*a.*$
importer.y.executable=/opt/bk_cms/ImportDispatcher/jobs/bin/importer_Y.pl
importer.y.params=--quiet --file EACHFILE_ABS
importer.y.canReturnStatus=true
importer.y.canReturnSuccess=false
importer.y.customImporterStatusCommand=/opt/bk_cms/ImportDispatcher/jobs/bin/importer_Y_status.pl 0
importer.y.customImporterStatusReadyCode=0
importer.y.customImporterSuccessCommand=/opt/bk_cms/ImportDispatcher/jobs/bin/importer_Y_checker.pl
importer.y.customImporterSuccessArgs=--file EACHFILE
importer.y.customImporterSuccessCode=0 </syntaxhighlight>
Hier sind x und y die Namen der Importer, die für reale Anwendungen sicherlich sinnvolle Bezeichnungen bekommen sollten, wie z. B. news. Gestartet wird der Vorgang durch den Aufruf von
<syntaxhighlight lang="xml" enclose="div">> /opt/bk_cms/ImportDispatcher/importdispatcher /some/directory/import_dispatcher_customer1.properties</syntaxhighlight>
Platzhalter
In den Argumenten für die auszuführenden Programme können Platzhalter für die jeweiligen Dateien angegeben werden. Ersetzt werden nur die Dateien, die den Virenscanner passiert haben und in die Inbox des jeweiligen Importers verschoben wurden. Der Suffix _ABS bedeutet, dass der absolute Pfad eingesetzt wird. EACHFILE bedeutet, dass die gesamte Kommandozeile für jede einzelne Datei ausgeführt wird. Ein Platzhalter kann auch völlig fehlen, wenn das Verzeichnis mit den eingehenden Daten bekannt ist (siehe Importer.)
Beispiele für einen Importer /usr/my/importer, wenn die beiden Dateien /my/inbox/file1.txt und /my/inbox/file2.txt gefunden wurden:
| Kommando (Executable mit Argumenten) | Ausgeführt |
| /usr/my/importer FILELIST | /usr/my/importer file1.txt file2.txt |
| /usr/my/importer FILELIST_ABS | /usr/my/importer /my/inbox/file1.txt /my/inbox/file2.txt |
| /usr/my/importer EACHFILE | /usr/my/importer file1.txt
/usr/my/importer file2.txt |
| /usr/my/importer EACHFILE_ABS | /usr/my/importer /my/inbox/file1.txt
/usr/my/importer /my/inbox/file2.txt |
Verwendet man einen Cap-Importer, sind keine Platzhalter notwendig, denn jeder Importer-Typ hat in seiner Konfiguration eine Inbox angegeben, aus der alle passenden Dateien geholt werden.
Der Importer wird nur aufgerufen, wenn mindestens eine neue Datei eingetroffen ist und den Virenscanner passiert hat. Es ist dabei unerheblich, ob Sie einen Datei-Platzhalter angegeben haben oder nicht.
Virenscanner
Grundsätzlich kann in der globalen Konfigurationsdatei der Installation ein Virenscanner konfiguriert und in der individuellen Steuerdatei abweichend angegeben werden, falls ein vom Standardprodukt abweichender Scanner erforderlich ist.
In beiden Fällen handelt es sich um die Properties:
<syntaxhighlight lang="xml" enclose="div"> virusscanCommand=/usr/share/antivirus/vscan
virusscanParameters=--verbose --file EACHFILE
stopIfVirusDetected=false </syntaxhighlight>
Der Platzhalter für die zu prüfenden Dateien kann entweder EACHFILE oder EACHFILE_ABS sein. Dann wird für jede einzelne neue Datei das Kommando aufgerufen (s. Platzhalter). FILELIST oder FILELIST_ABS ist auch möglich, allerdings kann in diesem Fall keine einzelne infizierte Datei unterschieden werden - der gesamte Satz an Dateien wird dann verworfen.
Ist stopIfVirusDetected=true gesetzt, bricht der Import-Dispatcher nach Erkennung eines Virus ab und führt keine Verteilung in die Importer-Inboxen aus. Selbstverständlich werden im anderen Fall keine infizierten Dateien verteilt. Nur Dateien, die ohne Virenbefund waren, werden weiter verteilt.
Eigene Skripte
Wenn die zu importierenden Dateien bereits das CAP-Importer-Format haben oder mittels eigenen Transformationen direkt vom Importer verwendet werden können, ist die Überwachung des Vorgangs bereits in den Import-Dispatcher eingebaut. Mit dem Aufruf
<syntaxhighlight lang="xml" enclose="div">cm my-importer-config status</syntaxhighlight>
stellt der Import-Dispatcher z. B. fest, dass der CAP-Importer gerade läuft und wartet, bis dieser wieder frei ist. Ob die Dateien korrekt importiert wurden, stellt der Import-Dispatcher fest, indem er unterhalb der Importer-Inbox in die Verzeichnisse bak und err hineinsieht.
Verwendet man allerdings Transformations- und Verifikationsstufen, die nicht in den CoreMedia-Mechanismus integriert sind, müssen diese gegebenenfalls mit eigenen Wrapper-Skripten vom Import-Dispatcher aufgerufen werden. Die eigenen Wrapper rufen dann im letzten Schritt normalerweise den CAP-Importer auf und müssen ihrerseits - bei Bedarf - den Importer-Status nachhalten.
Mögliche Varianten
Es gibt drei mögliche Funktionen, die ein solches Skript im Zusammenhang mit dem Import-Dispatcher erfüllen kann:
- Statusermittlung: Läuft der Vorgang momentan oder muss gewartet werden?
- Import: Der eigentliche Importvorgang
- Prüfskript: Wurden die Daten korrekt importiert?
Nur der Importer muss vorhanden sein, die anderen Skripte sind optional. So ist es auch möglich, dass das eigene Importer-Skript so lange blockiert, bis der Import beendet ist und über den Rückgabestatus den Erfolg oder Misserfolg meldet. Es kommt also auf den Importmechanismus an, welche Skripte sinnvoll sind.
Der Statuscode des Importers kann optional überprüft werden (importer.x.successCode), was nicht mit importer.x.customImporterSuccessCode zu verwechseln ist. Ersteres wird direkt vom Importer geliefert und kann dann sinnvoll sein, wenn der Importer so lange blockiert, bis das Ergebnis feststeht und sich ein anschließendes Prüfskript erübrigt. Die zweite Variante wird verwendet, wenn der Importer ein Hintergrundprozess ist (wie z. B. der CAP-Importer) und nach kurzer Zeit lediglich meldet, ob der Prozess erfolgreich gestartet werden konnte.
Ist ein Skript für die Statusermittlung angegeben, wird dies vor dem eigentlichen Importvorgang aufgerufen, um festzustellen, ob der Importer bereit ist. Falls nicht, wird dies jeweils nach einigen Sekunden erneut geprüft. Anschließend startet der Import-Dispatcher den Importer mit den bei Bedarf ersetzten Dateinamen. Wenn mit dem Schlüsselwort EACHFILE oder EACHFILE_ABS eine Schleife über die zu importierenden Dateien ausgeführt wird, ruft der Import-Dispatcher nach jedem Durchlauf das Statuskommando auf.
Nach dem Importvorgang wird nun das optional unter dem Eintrag customImporterSuccessCommand konfigurierte Prüfskript gestartet (für den CoreMedia-Importer ist es, wie bereits erwähnt, nicht nötig). Dieses Skript muss wissen, wie es den Erfolg oder Misserfolg des vorangegangenen Importvorganges feststellen kann. Als Argument können wieder die Platzhalter für die zu importierenden Dateien verwendet werden. Beispielsweise könnte es Archivierungsverzeichnisse oder das Logfile des Importers prüfen.
Return Codes
Alle Properties, die mit SuccessCode enden, enthalten den numerischen Rückgabewert (return code) des zu startenden Prozesses bei Erfolg. Meist ist dies 0 ("Null"). Im Zweifelsfall können Sie unter Unix den Rückgabewert mit dem Kommando
<syntaxhighlight lang="xml" enclose="div">echo $?</syntaxhighlight>
ermitteln, wenn Sie den gewünschten Befehl auf der Kommandozeile unmittelbar vorher ausgeführt haben.
E-Mail-Benachrichtigung
E-Mails werden verschickt, wenn ein Fehler auftrat. Die Meldungen sind in deutscher Sprache gehalten und an technisches Personal gerichtet. Wenn möglich, sind die Pfade betroffener Dateien aufgeführt und der Verarbeitungsschritt, in der eine Störung vorlag.
Zur Konfiguration dienen die Parameter, die mit emergencyMail beginnen. Sie können die Mail-Host-Einstellungen z. B. zentral in der Datei local.properties und die Importer-spezifischen Parameter (Subject, Receivers, Sender) in den individuellen Property-Dateien ablegen. Alle Mail-Parameter können überschrieben werden.