Zum Hauptinhalt springen

Serverprozesse

Wenn diaLIMS auch im Hintergrund arbeiten oder beispielweise für Schnittstellen verfügbar sein muss - ohne dass Benutzer aktiv in diaLIMS angemeldet sind - bietet sich die Einrichtung von Funktionalitäten als Dienst an.

Diensteinrichtung mit Java Service Launcher (JSL) für Windows​

Der Java Service Launcher (JSL) ist nur für Windows geeignet und sehr einfach (im Vergleich zu den anderen Möglichkeiten) zu konfigurieren und zu installieren.

Vorbereitung​

Voraussetzung für die Einrichtung:

  • Es muss der diaLIMS-Dateiordner lokal vorliegen (komplette Installation!). Von einem Aufruf über eine entfernte Freigabe wird dringend abgeraten, da selbst bei temporären Zugriffsschwierigkeiten kaum bis keine Reaktion, zum Beispiel die Protokollierung in weiteren Fehlerfällen oder fehlerfreie Fortsetzung, des Dienstes möglich ist.
  • Eine fertige, dienstfähige Klasse im diaLIMS-Paket muss vorhanden sein.
  • Im Ordner Service\Tools\Java Service Launcher der diaLIMS-Installation befinden sich zwei Dateien (die jsl.exe und die jsl.ini) die benötigt werden. Die Dateinamen können auch angepasst werden, sodass man auch weiß, welchen Dienst es betrifft. Es ist nur wichtig, dass beide den gleichen Namen haben, da die .exe nach der gleichnamigen .ini sucht.

Anpassung der Konfiguration​

In der .ini sind oben (im Abschnitt [defines]) einige Variablen, die gesetzt werden können:

  • SERVICE_NAME = Der Name des Dienstes. Wenn es etwas detaillierter angegeben werden soll, kann weiter unten im Abschnitt [service] folgendes anpassen: appname = %SERVICE_NAME% servicename = %SERVICE_NAME% displayname = %SERVICE_NAME% servicedescription = %SERVICE_NAME%
  • DIALIMS_PROGRAMM_PATH Hier muss ein absoluter Pfad eingetragen werden, da Java anscheinend ein Problem mit dem Auspacken von Klassen aus einer Jar hat. Innerhalb dieses Pfades muss auch der Unterordner Java liegen. Dieser Pfad wird auch als WorkingDirectory gesetzt. Beispiel: DIALIMS_PROGRAMM_PATH = D:\diaLIMS\Programm\
  • DIALIMS_LOG_PATH Gibt den (absoluten oder relativen) Pfad zum Log-Ordner an. Dabei ist es WICHTIG, dass alle angegebenen Unterordner auch existieren. Beispiel: DIALIMS_LOG_PATH = \\SERVERNAME\DIALIMS_FREIGABE\Programm\log\Mein_Dienst\
  • VM_ARGS An dieser Variable muss i.d.R. nichts geändert werden. Default: VM_ARGS = -XX:+HeapDumpOnOutOfMemoryError -Xmx512m
  • CLASSPATH An dieser Variable muss i.d.R. nichts geändert werden. Default: CLASSPATH = .;diaLIMS-kunden.jar;diaLIMS.jar;bsh
  • MAIN_CLASS_AND_PARAMETER Hier wird die Start-Klasse inkl. Übergabeparameter angegeben. Beispiel: MAIN_CLASS_AND_PARAMETER = com.dialog.dialims.kunden.cordenka.CordenkaPVAAuftragsanlageImportProzess .\resource\PVAAuftragsanlage.properties
  • systemout Wenn einkommentiert (Kommentar = vorangestelltes ;), werden sämtliche Sysouts in diese Datei umgeleitet. ACHTUNG: Wenn der Prozess im DEBUG-Modus gestartet wird, erfolgen in der Konsole keine Ausgaben.
  • systemoutappend Gibt an, ob beim Starten des Dienstes die Sysouts an eine vorhandene Datei angehängt werden sollen. yes -> Sysouts werden angehängt no -> Datei wird bei jedem Starten des Dienstes geleert
  • systemerr Siehe "systemout". Hier werden allerdings nur die Errors protokolliert.
  • systemerrappend Gleiches Verhalten wie bei "systemoutappend"

Weitere Einstellungen sind aus der .ini zu entnehmen.

Installation​

Der Dienst wird über die CMD installiert. Es ist zwingend erforderlich, dass die CMD als Administrator bzw. mit den entsprechenden Rechten gestartet wird, damit der Dienst auch installiert werden kann. Über die CMD muss nun in das Verzeichnis navigiert werden, wo die .exe und die .ini liegen.

Über die .exe stehen folgende Parameter zur Verfügung:

  • MeinDienst.exe -debug Zum Testen, ob die Konfiguration der .ini korrekt ist. Hierbei wird noch kein Dienst installiert. Hinweis: systemout und systemerr sollten auskommentiert sein, damit auch sämtliche Ausgaben in der Konsole landen.
  • MeinDienst.exe -install Installiert den Dienst anhand der vorhandenen Konfiguration (*.ini). Von nun an wird der Dienst unter Dienste angezeigt und kann ggf. von hier aus weiter konfiguriert werden.
  • MeinDienst.exe -configure Konfiguriert den Dienst neu, falls Änderungen an der .ini vorgenommen wurden. Funktioniert nur, wenn der Dienst bereits installiert ist.
  • MeinDienst.exe -remove Entfernt den Dienst wieder.

Diensteinrichtung mit YAJSW​

Für die Einbindung von Java als Dienst wird hier YAJSW - Yet Another Java Service Wrapper verwendet.

Vorbereitung​

Voraussetzung für die Einrichtung:

  • Es muss der diaLIMS-Dateiordner lokal vorliegen (komplette Installation!). Von einem Aufruf über eine entfernte Freigabe wird dringend abgeraten, da selbst bei temporären Zugriffsschwierigkeiten kaum bis keine Reaktion, zum Beispiel die Protokollierung in weiteren Fehlerfällen oder fehlerfreie Fortsetzung, des Dienstes möglich ist.
  • Eine fertige, dienstfähige Klasse im diaLIMS-Paket muss vorhanden sein. (In der Regel kommt hier com.dialog.dialims.limsworker.Daemon zum Einsatz.)
  • Es muss die Laufzeitumgebung für Java lokal abgelegt sein (diaLIMS-Installation/Programm/java). Dies ist für den Betrieb des diaLIMS auf den Servern sonst nicht zwingend vorausgesetzt. Auch hier wird, aus den oben genannten Gründen, von einem Aufruf über eine entfernte Freigabe dringend abgeraten.
  • Es muss die Java-Version passend oder höher zur diaLIMS-Installation sein.
  • Launch4j muss verfügbar sein um eine ummantelnde diaLIMS-Daemon.exe erzeugen zu können.
  • Es dürfen keine Laufwerkbuchstaben verwendet werden, da diese beim Start als Dienst nicht zur Verfügung stehen. Anstatt L:\diaLIMS\SchnittstelleEins\Eingang muss die UNC-Pfadangabe //Servername/Freigabename/diaLIMS/SchnittstelleEins/Eingang verwendet werden.
  • Es muss die aktuelle YAJSW-Version als Archiv vorliegen, diese kann über http://sourceforge.net/projects/yajsw/files/ bezogen werden.

Einrichtung​

lokaler diaLIMS-Ordner​

Alle für den Aufruf von diaLIMS nötigen Dateien müssen lokal vorliegen, analog einer ggf. vorhandenen Laufwerksfreigabe, beispielsweise:

Windows

C:\Program Files\diaLIMS

Linux

/opt/diaLIMS

#### Dienstordner erstellen

Entpacken Sie das yajsw-Archiv in einen sprechenden Unterordner passend zum Betriebssystem, beispielsweise:

Windows

C:\Program Files\diaLIMS-DaemonWrapper

Linux

/opt/diaLIMS-DaemonWrapper

Je gewünschtem Dienst muss ein eigener Ordner angelegt werden, damit die Dienste unabhängig voneinander gehandhabt werden können. Der Prefix diaLIMS im Ordner erleichtert hier die Wiedererkennung.

Wichtig ist die Unterscheidung von Wrapper (Das Programm, was den diaLIMS-Daemon mit dem Betriebssystem verbindet), hierzu separate Logs **TODO**...)

dbconnection.properties vorbereiten​

Damit die Worker-Informationen aus der Datenbank ausgelesen werden können, ist die Datei Einstellungen/dbconnection.properties aus dem lokalen diaLIMS-Pfad anzupassen bzw. vorzubereiten.

Schnittstellenmodul vorbereiten​

Im diaLIMS-Schnittstellenmodul muss ein Eintrag erzeugt werden, dessen Kurzbezeichnung ("Schnittstelle") sich mit derjenigen aus dem Parameter der Kommandozeile des Workers deckt (siehe nächster Punkt).

Die weiteren Informationen (wie Hostname, IP, Port) werden später durch den Daemon automatisch ergänzt, sobald der Daemon das erste Mal startet.

hinweis

Beachten Sie bei mehreren Daemons, dass sich die Ports unterscheiden müssen. Ggf. ist der automatisch ermittelte Port ab dem zweiten Daemon manuell nach unten zu korrigieren, bspw. von 1099 auf 1098.

diaLIMS-Daemon.exe mit Launch4j erzeugen​

Für den Start der Klasse sind viele nötige Parameter bereits in einer Vorlage für Launch4j vorbereitet.

  • In Launch4j muss aus dem diaLIMS-HEAD die Datei LimsWorkerDaemon.cfg.xml geladen werden

  • Der 1. Komanndozeilenparameter im XPath /launch4jConfig/cmdLine muss dem Workernamen aus dem Schnittstellenmodul entsprechen.

  • Nach dieser Anpassung kann die diaLIMS-Daemon.exe mit Launch4j erzeugt werden

  • Die mit Launch4j generierte diaLIMS-Daemon.exe muss in den lokalen diaLIMS-Programmpfad gelegt werden, etwa

Windows

C:\Program Files\diaLIMS\Programm

Linux

/opt/diaLIMS/Programm

Hier liegt für gewöhnlich bspw. auch die diaLIMS.jar und die diaLIMS-kunden.jar. Dieser Ausführungsort ist wichtig, da JPA zur Laufzeit diesen Pfad als Ausgangspunkt für das Laden der `customMapping.xml` verwendet.

Klasse manuell starten​

Starten Sie mit lokalen Administratorrechten über eine Kommandozeile den diaLIMS-Daemon.

Beispiel:C:\Program Files\diaLIMS\Programm\diaLIMS-Daemon.exe

Vergewissern Sie sich, dass der Prozess fehlerfrei arbeitet und lassen Sie ihn jetzt für die Folgeschritte laufen.

Prozess-ID ermitteln​

Öffnen Sie eine 2. Kommandozeile mit lokalen Administatorrechten, um die Prozess-ID (PID) des oben gestarteten Aufrufs zu ermitteln, beispielsweise:

Windows

tasklist | findstr java

Linux

ps aux | grep java

**Note:**

Bei mehrdeutigen Ergebnissen, beispielsweise wenn schon andere Java-Dienste laufen, sollten Sie vorher die Liste generieren, den Dienst starten und vergleichen welche PID hinzugekommen ist.

Pfad wechseln​

Wechseln Sie in der 2. Kommandozeile in den erstellten YAJSW-Odner für den Dienst, beispielsweise:

Windows

cd "C:\Program Files\diaLIMS-DaemonWrapper\bat".

Linux

cd /opt/diaLIMS-DaemonWrapper/bin.

#### Konfiguration generieren

YAJSW liefert ein Skript, getConfig, aus, welches anhand der ermittelten Prozess-ID automatisch alles (Pfade, Parameter, Rechte), was für Diensteinrichtung und -ausführung nötig ist, erkennt und aufbereitet.

Führen Sie genConfig mit der ermittelten Prozess-ID als Parameter in der 2. Kommandozeile aus, beispielsweise:

Windows

genConfig.bat 1519

Linux

genConfig.sh 1519

Es wird eine Dienstkonfiguration \(wrapper.conf\) generiert und im Unterordner `conf` des YAJSW-Ordners abgelegt, welche im Folgeschritt anzupassen ist.

Windows

C:\Program Files\dialims-DaemonWrapper\conf\wrapper.conf

Linux

/opt/dialims-DaemonWrapper/conf/wrapper.conf

#### Dienstkonfiguration \(wrapper.conf\) anpassen

Passen Sie nun mit einem Texteditor und den nötigen Rechten die Konfiguration des Dienstes an.

  • wrapper.working.dir

    = E:\\Pfad\\zu\\diaLIMS\\Programm Dies ist wichtig, damit die relativen Angaben etwa für classpath und dbconnection.properties gefunden werden.

  • wrapper.tray

    = false, deaktiviert das (je YAJSW-Dienst) einblendbare Icon im Systray. Belegt aktiviert einen separaten Port, der bei mehreren Wrappern auf dem gleichen System manuell angepasst werden müsste.

  • wrapper.ntservice.name

    = diaLIMS-DaemonWrapper-$name, keine Leer- oder Sonderzeichen verwenden.

  • wrapper.ntservice.displayname

    = diaLIMS-DaemonWrapper-$name, keine Leer- oder Sonderzeichen verwenden.

  • wrapper.jmx

    = true, Aktiviert die Folgeeinträge, damit der Dienst aus dem Schnittstellenmodul von diaLIMS erreichbar ist.

  • wrapper.jmx.rmi.port

    = 51099 (default: 1099 wird von diaLIMS-Daemon selbst (nicht vom Wrapper) verwendet

    Wenn mehrere Dienste (bspw. Produktiv- und Testdienst) auf dem gleichen System eingerichtet werden benötigt jeder Dienst einen eigenen Port. Es wird abwärts gezählt, der zweite Dienst erhält also 51098.

  • wrapper.java.classpath.1

    = .

  • wrapper.java.classpath.2

    = diaLIMS-kunden.jar

  • wrapper.java.classpath.3

    = diaLIMS.jar

  • wrapper.java.classpath.4

    = bsh

Optional können Timeouts gesetzt werden, die YAJSW veranlassen die zu ummantelnde Klasse erst verzögert aufzurufen. Das kann sinnvoll sein, wenn nötige Ressourcen direkt nach einem Neustart noch nicht verfügbar sind. Details hierzu sind sehr individuell und sollten in den Kommentaren der wrapper.conf direkt gelesen werden.

Klasse manuell stoppen​

Stoppen Sie nun den am Anfang manuell gestarteten Prozess, um ihn wie weiter unten beschrieben über YAJSW aufzurufen.

Testaufruf mit YAJSW-runConsole​

Die erzeugte Konfiguration beziehungsweise der Prozess sollte nun - vorerst ohne Dienstinstallation - über YAJSW startbar sein. runConsole ist ein Hilfeprogramm und vermittelt auch später zwischen der Dienstverwaltung des Betriebssystems und der aufzurufenden Klasse. Hier sollte bei einem manuellen Start von runConsole kein Fehler mehr auftreten und an dieser Stelle ist die letzte Möglichkeit noch Parameterkorrekturen vorzunehmen.

Windows

runConsole.bat

Linux

runConsole.sh

**Note:**

Überprüfen Sie die Protokolle (log-Unterordner im dialims-DaemonWrapper-Ordner, Ereignisprotokoll, ...) und passen Sie ggf. die Log-Level in der wrapper.conf an

Sobald runConsole fehlerfrei läuft beziehungsweise die darin aufgerufene Klasse wie im manuellen Aufruf aus der 1. Kommandozeile arbeitet, kann runConsole hier abgebrochen und mit dem nächsten Schritt fortgesetzt werden.

Installation des Dienstes​

CAUTION:

Die folgenden Schritte, insbesondere der Installationsaufruf dürfen erst ausgeführt werden, wenn sich die Konfiguration (wrapper.conf) nicht mehr ändert. Nachträgliches Anpassen der wrapper.conf führt zu nur schwer handhabbaren Folgefehlern.

CAUTION:

Beachten Sie hier insbesondere, dass lokale Administratorrechte nötig sind. Die Kommandozeile von Windows muss hier explizit über "mit Administratorrechten ausführen" aufgerufen worden sein. Ein DB2Admin als lokaler Admin allein reicht nicht immer aus.

Hiermit installieren Sie die YAJSW für die entsprechende Klasse als Dienst.

Equivalent zum hier gezeigten Beispiel mit Windows-Batchdateien enden unter Linux die Aufrufe auf .sh

  • 1. installService.bat

    Installiert den Dienst ohne ihn zu aktivieren. Vergewissern Sie sich durch Überprüfung der Konsolenausgabe, dass beim Installieren keine Fehler aufgetreten sind.

  • 2. startService.bat

    Startet den Dienst. Vergewissern Sie sich durch Überprüfung der Konsolenausgabe, dass beim Starten keine Fehler aufgetreten sind.

  • 3. stopService.bat

    Stoppt den Dienst. Vergewissern Sie sich durch Überprüfung der Konsolenausgabe, dass beim Stoppen keine Fehler aufgetreten sind.

  • 4. startService.bat

    Der Dienst kann nun gestartet bleiben.

Test über Betriebssystem​

  • Testen Sie über die betriebssystem-eigenen Mittel die Steuerung des Dienstes (Start, Stop, Neustart)
  • Wenn möglich prüfen Sie auch ob bei Neustart des Betriebssystems der Dienst korrekt gestartet wird. Erst hier können sich noch Fehler zeigen, die beispielsweise mit früh nach dem Neustart noch nicht verfügbaren Ressourcen zu tun haben (beispielsweise eine andere noch nicht gestartete Schnittstelle/(Datenbank-)Dienst)
hinweis

Die Einrichtung der Klasse als Dienst ist hiermit abgeschlossen. Es folgt der Test und die Anbindung der Dienststeuerung an diaLIMS.

Worker einrichten​

Nachdem nun der diaLIMS-Daemon über den YAJSW-Wrapper als Dienst auf dem Server eingerichtet ist, kann mit der Einrichtung der einzelnen Worker fortgesetzt werden.

Gehen Sie hierzu ins Schnittstellenmodul, wählen den betreffenden Daemon aus und fügen die gewünschten Worker hinzu und passen diese an.

Regelmäßige Abläufe | Korrekturprozess für Statusübergänge​

Für wiederkehrende, automatisierbare Aufgaben ist es möglich einen Prozess regelmäßig aufzurufen. Bekannte Beispiele für so einen Aufruf sind unter Windows die Aufgabenplanung, früher "geplante Tasks" genannt und unter Linux cronjobs.

Als Beispiel wird hier der Prozess für den FreigabeProzess verwendet.

Dieser Prozess geht alle Ergebnisse im Status R,A durch und prüft, ob hier die Anzahl an Mindestwiederholungen erfüllt ist. Wenn dies der Fall ist, wird das Ergebnis in den Status W überführt.

Weiterhin geht der Prozess alle Proben im Status R, A durch und prüft, ob alle zugeordneten Ergebnisse entweder im Status W, F oder S sind. Ist das der Fall, wir der Status der Probe auf W korrigiert.

.\java\bin\java.exe -cp .;diaLIMS-kunden.jar;diaLIMS.jar;bsh
com.dialog.dialims.anbindung.FreigabeProzess //localhost:50000/aqslab67:retrieveMessagesFromServerOnGetMessage=true;
db2admin 4E63363875327A30416E673D Administrator DB2NET
>> Statuskorrigieren.log

Einrichtung​

Der Serverprozess wird als Batchdatei im Ordner \dialims\Programm abgelegt.

Als Benutzer für diesen Prozess sollte der ZBA-Benutzer verwendet werden. Als Datenbank muss die jeweilige diaLIMS-Datenbank des Kunden angegeben werden.

Das Kennwort für den Benutzer sollte verschlüsselt werden, bevor es in die Batch-Datei eingetragen wird. Hierzu kann die Funktion Passwort verschlüsseln im Modul Optionen verwendet werden.

Auf dem Server kann die Aufgabenplanung verwendet werden, um diesen Prozess regelmäßig auszuführen.

notwendige Klassen​

Für die Einrichtung des Prozesses muss die Klasse com.dialog.dialims.anbindung.FreigabeProzess in der diaLIMS-Installation vorhanden sein.

Protokollierung​

Die Protokollierung für geänderte Ergebnisse und Proben sollte in einer eigenen LOG-Datei erfolgen. Diese muss in der Batch-Datei angegeben werden.

In obigem Beispiel wird das Protokoll fortlaufen in die eigens dafür erzeugte Statuskorrigieren.log geschrieben.