Fehler und Fehlermeldungen

Auf der Admin-Seite (http://<host>:<port>/handlungshilfe/config) werden die Reiter „Datenbank“ und „LDAP“ nicht angezeigt.

Bitte stellen Sie sicher, dass die Property „-Dapp.config.advanced.enabled=true“ ist, und starten Sie ggf. den Applikationsserver neu.

Nähere Informationen finden Sie in der „Installationsanleitung Server Handlungshilfe 4.0.2976“ in Kapitel 1.8 Systemvariablen der Handlungshilfe bzw. im jeweiligen Konfigurationskapitel zu den unterstützten Applikationsservern.

Ausgangssituation: Eine MSSQL-Datenbank der Handlungshilfe 4.0.2575 soll auf die Handlungshilfe 4.0 in der Version 2944 oder 2976 aktualisiert werden. Für die Installation der Handlungshilfe in der Version 2944 oder 2976 wurde der mssql-jdbc-Datenbanktreiber konfiguriert, z. B. weil zusätzlich die MS SQLServer-Version angehoben wurde und somit der veraltete jtds-Treiber für den Betrieb nicht mehr ausreicht. 

Beim Update der Datenbank im Rahmen des Starts der neuen Handlungshilfeversion treten in diesem Fall folgende Fehlermeldungen in der Logdatei auf:

Auszug aus der Logdatei

Nach dem Start der Handlungshilfe ist z. B. kein Anmelden mehr möglich oder alle Daten in den Strukturbereichen fehlen.

Ursache:

Während des Starts der Handlungshilfe finden Integritätstests und ggf. Updates des Datenbankschemas mittels der Bibliothek Liquibase (https://www.liquibase.org/) statt. Die in der Handlungshilfe 4.0 eingesetzte Version von Liquibase setzt im Datenbanktreiber eine JDBC3-Funktion voraus, die im mssql-jdbc-Treiber nicht implementiert/unterstützt ist. Dies führt dazu, dass eine Datenbankschemaaktualisierung beim Start der Handlungshilfe im Rahmen des Updateprozesses nicht durchgeführt werden kann. 

Mit einem Update des mssql-jdbc-Datenbanktreibers kann das Problem nicht behoben werden.

Workaround:

Ausgangssituation: Die Handlungshilfe 4.0 ist in Version 2944 oder 2976 installiert. Das Datenbankschema der zugehörigen MS SQL-Datenbank befindet sich noch in der Version 2575.

Hinweis: Nutzen Sie bitte für die Aktualisierung der Datenbank die gleiche SQLServer-Version wie für die Handlungshilfe-Installation in der Version 2575. Falls Sie zusätzlich den SQLServer aktualisieren möchten, führen Sie diese bitte erst nach der Migration der Daten auf Handlungshilfe 2944 oder 2976 durch.

1. Verwenden Sie bitte einmalig zum Start der Handlungshilfe unabhängig von der unterstützten MS SQL-Serverversion den jtds-Treiber. Stellen Sie hierzu bitte sicher, dass die Datenbankeinstellungen unter „http://<host>:port/handlungshilfe/config“ wie folgt gesetzt sind:

2. Starten Sie bitte anschließend die Handlungshilfe neu und öffnen Sie die Startseite der Handlungshilfe: „http://<host>:port/handlungshilfe“. Im Hintergrund wird das Datenbankschema aktualisiert. Hierdurch wird der Aufruf der Startseite verzögert. Sobald die Startseite geladen ist, sich auch im Log keine neuen Einträge zeigen und auch keine Fehler protokolliert wurden, ändern Sie bitte die Datenbankeinstellungen unter „http://<host>:port/handlungshilfe/config“:

3.Anschließend starten Sie bitte die Handlungshilfe erneut. Mit diesen Einstellungen ist nun ein Regelbetrieb möglich.

Hinweis: Die virtuelle Maschine der Handlungshilfe 4.0.2976 beinhaltet eine vorkonfigurierte PostgreSQL 12-Datenbank. Zur Übernahme der Daten aus einer Handlungshilfe 4.0.2575 muss das Datenbankschema aktualisiert werden und ggf. die Datenbank auf PostgreSQL 12 migriert werden. Es wird empfohlen, die Migration auf PostgreSQL außerhalb der virtuellen Maschine durchzuführen, da die PostgreSQL-Instanz der virtuellen Maschine aus Sicherheitsgründen nicht extern erreichbar ist und zudem die Konfiguration der Handlungshilfe in der virtuellen Maschine angepasst werden müsste.

Variante 1: Migration der Datenbank in Handlungshilfe 4.0.2575

Bitte öffnen Sie die Administrationsoberfläche der Handlungshilfe (http://<host>:<port>/handlungshilfe/config) und prüfen im Reiter Datenbank die Datenbankkonfiguration:

Fall 1: Der konfigurierte Datenbanktreiber lautet: „org.postgresql.Driver“

1. Bitte stoppen Sie den Applikationsserver der Handlungshilfe 4.0.2575.
2. Folgen Sie bitte den Schritten in der Installationsanleitung virtuelle Maschine Handlungshilfe 4.0.2976 ab Kapitel 2.2.1 Übernahme aus einer bestehenden PostgreSQL-Datenbank.
3. Nach dem Neustart des Applikationsservers der virtuellen Maschine rufen Sie bitte die Startseite der Handlungshilfe auf. Der Seitenaufbau wird verzögert erfolgen, da im Hintergrund das Datenbankschema von 2575 auf 2976 aktualisiert wird.
4. Sobald die Startseite der HH vollständig geladen ist, prüfen Sie bitte die Logdatei (/usr/share/tomcat/logs/catalina.out) auf eventuelle Fehler.

Fall 2: Ein anderer Datenbanktreiber wird verwendet:

Für den Fall, dass für die Handlungshilfe 4.0.2575 keine PostgreSQL-Datenbank genutzt wurde, führen Sie bitte die folgenden Schritte durch:

1. Vorbereitung der Handlungshilfe 4.0.2575

• Bitte erhöhen Sie den Heap-Speicher für die Handlungshilfe. Für die Migration der Datenbank sollte der Handlungshilfe mindestens 8 GB zur Verfügung stehen. Erhöhen Sie bitte ggf. den Heapspeicher mit dem Java VM Parameter „Xmx“ (z. B. „java –Xmx8192m“ = 8 GB Heap Space).
• Für eine Migration der Datenbank auf PostgreSQL innerhalb der Version 2575 wird eine PostgreSQL-Installation in der Version 9.6 benötigt. Bitte installieren Sie PostgreSQL 9.6. Erstellen Sie eine Datenbank „handlungshilfe“ mit UTF-8-Zeichenkodierung. Legen Sie darunter einen Benutzer „hh“ an. Ein Default-Schema „hh“ wird automatisch erzeugt.

2. Umstellung der Handlungshilfe 2575 auf PostgreSQL

• Führen Sie bitte in der Administrationsoberfläche der Handlungshilfe eine Datenbanksicherung durch und laden die Backupdatei herunter.
• Legen Sie bitte die zuvor heruntergeladene Backupdatei unter <HH-DIR>/webapps/handlungshilfe/data/importdb/handlungshilfe.db.zip ab.
• Tragen Sie bitte in der Administrationsoberfläche der Handlungshilfe (Reiter Datenbank) die Verbindungsparameter der im Schritt 1 b) installierten PostgreSQL-Datenbank ein und speichern diese.
• Beispielzugangsdaten für Postgres-Datenbank:

• Testen Sie bitte die Datenbankverbindung (Schaltfläche „Verbindung testen“)
• Sofern der Verbindungstest erfolgreich war, führen Sie bitte einen Import durch (Schaltfäche „Import“). Hierdurch wird Ihr zuvor unter <HH-DIR>/webapps/handlungshilfe/data/importdb/handlungshilfe.db.zip abgelegtes Backup in die PostgreSQL 9.6 Datenbank importiert.
• Prüfen Sie bitte die Logdatei des eingesetzten Applikationsservers auf eventuelle Fehler.
• War der Import der Daten in die PostgreSQL-Datei erfolgreich, fahren Sie bitte oben mit den Schritten des Fall 1 der Variante 1 fort.

Variante 2: Nutzung der portablen Version als Migrationstool

Diese Variante setzt voraus, dass die Handlungshilfe 4.0.2575 auf einem Windows-Server installiert ist. Für eine Datenbankmigration mit der portablen Version führen Sie bitte die folgenden Schritte durch:

1. Stoppen Sie bitte die Handlungshilfe 4.0.2575.
2. Führen Sie bitte eine Datenbanksicherung der Handlungshilfedatenbank mithilfe der Werkzeuge Ihres eingesetzten Datendankservers durch.
3. Entpacken Sie bitte die portable Version der Handlungshilfe 4.0.2976 auf dem Server der Handlungshilfe 4.0.2575.
4. Editieren Sie bitte nach dem Entpacken die Datei „Handlungshilfe.bat“. Ersetzen Sie bitte „-Xmx2048m“ durch „-Xmx8192m“.
5. Kopieren Sie bitte die Datei <HH-Serverinstallation>/webapps/handlungshilfe/data/etc/db-config.properties“ in das Verzeichnis <HH-Portable-Version>\work\data\etc.
6. Starten Sie die portable Version. Im Hintergrund wird das Datenbankschema von 2575 auf 2976 aktualisiert.
7. Sobald die portable Version vollständig geladen ist, prüfen Sie bitte die Logdatei (<HH-Portable-Version>\logs\hh.log) auf eventuelle Fehler.
8. Führen Sie bitte in der Administrationsoberfläche der portablen Version Handlungshilfe 4.0.2076 (http://localhost:8987/handlungshilfe/config) eine Datenbanksicherung durch und laden die Backupdatei herunter.
9. Importieren Sie bitte den Backup in die virtuelle Maschine gemäß der Installationsanleitung virtuelle Maschine Handlungshilfe 4.0.2976 Kapitel 2.2.2 Übernahme aus anderen Datenbanksystemen.

Falls ab Schritt 6 ein Fehler auftreten sollte, ist die Handlungshilfe 4.0.2575 nicht mehr startfähig. Zur Wiederherstellung der Startfähigkeit der Handlungshilfe 4.0.2575 spielen Sie bitte wieder das in Schritt 2 erstellte Backup in den Datenbankserver der Handlungshilfe 4.0.2575 ein und starten die Handlungshilfe 4.0.2575 erneut.

Nach dem Update auf eine neue Applikationsserverversion (Tomcat 10, Wildfly 23) oder einer Neuinstallation startet die Handlungshilfe nicht. In der Logdatei gibt es eine Fehlermeldung, die den Text „java.lang.NoClassDefFoundError: javax/servlet“ enthält.

Neuere Versionen von Tomcat (>10) und Wildfly (>23  EE9) sind nicht kompatibel und werden von der Handlungshilfe aus technischen Gründen nicht mehr unterstützt. Bitte beachten Sie die Hinweise in der Installationsanleitung Server Handlungshilfe 4.0.2976 (Kapitel 1.4 Unterstützte Web/Application Server) und verwenden Sie ältere Versionen, z. B. Tomcat 9.x

Beispielhafter Auszug aus der Logdatei bei Wildfly

Beispielhafter Auszug aus der Logdatei bei Tomcat

Die Fehlermeldung „Unsupported major.minor version 52.0" tritt bei dem Versuch auf, die Handlungshilfe mit Java 7 zu starten. Die Systemanforderungen der Handlungshilfe 4.0.2976 haben sich erhöht. Mindestvoraussetzung ist jetzt Java 8.

Um den Fehler zu beheben, muss die Java-Version aktualisiert werden. Empfohlen wird ein OpenJDK 8 (JDK-Variante statt JRE), das über https://adoptopenjdk.net/?variant=openjdk8&jvmVariant=hotspot bezogen werden kann.

Beim Einsatz von MS SQLServer mit dem mssql-jdbc-Datenbanktreiber erscheinen beim Start der Handlungshilfe 4.0.2976 folgende Fehlermeldungen in der Logdatei:

Auszug aus der Logdatei

Während des Starts der Handlungshilfe 4.0.2976 finden Integritätstests und ggf. Updates des Datenbankschemas mittels der Bibliothek Liquibase (https://www.liquibase.org/) statt. Die in der Handlungshilfe 4.0.2976 eingesetzte Version von Liquibase setzt im Datenbanktreiber eine JDBC3-Funktion voraus, die im mssql-jdbc-Treiber nicht implementiert/unterstützt ist. Dies führt dazu, dass eine Datenbankbereinigung beim Start der Handlungshilfe 4.0.2976 nicht durchgeführt werden kann. Konkret kann es ein, dass Sperren auf Strukturelemente (implizite Sperren) nicht bereinigt werden und Steuerelemente fälschlicherweise gesperrt bleiben.

Mit einem Update des mssql-jdbc-Datenbanktreibers kann das Problem nicht behoben werden. Ein möglicher Workaround wäre, vor dem Start der Handlungshilfe mittels eines Skriptes das folgende SQL-Statement auszuführen:

UPDATE hh.hh_sperre SET implizit_kz = 0, bearbeitung_sperre = null, benutzer_sperre = null WHERE implizit_kz = 1;

Im Ausdruck fehlen am Ende eine Zeile oder eines Feldes einzelne Buchstaben oder Worte. Der Fehler trat bisher nur auf Linux-Systemen auf. Für den PDF-Druck werden von der Handlungshilfe Microsoft-Schriftarten referenziert, die bei den meisten Linuxdistributionen nicht standardmäßig installiert sind. Für die PDF-Erstellung werden von der Handlungshilfe Ersatzschriftarten gewählt, die eine andere Zeichenbreite haben, was zu abgeschnittenen Texten führt.

Bitte prüfen Sie, ob auf den betroffenen Systemen die folgenden Microsoft-Schriftarten vorhanden sind:

andale_mono=Andale Mono
arial=Arial
arial_black=Arial Black
book_antiqua=Book Antiqua
comic_sans_ms=Comic Sans MS
courier_new=Courier New
georgia=Georgia
helvetica=Helvetica
impact=Impact
tahoma=Tahoma
terminal=Terminal
times_new_roman=Times New Roman
trebuchet_ms=Trebuchet MS
verdana=Verdana
webdings=Webdings
 

Falls nicht, empfehlen wir, unter Linux die sogenannten Ms-Core-Fonts zu installieren:

• Befehl für Ubuntu/Debian: sudo apt install ttf-mscorefonts-installer
• Für RedHat siehe http://mscorefonts2.sourceforge.net/

Nähere Informationen sowie ein Installationsbeispiel für CentOS finden Sie in der „Installationsanleitung Server Handlungshilfe 4.0.2976“ in Kapitel 5.3 Schriftarten unter Linux.

Die zugrundeliegenden Dateien (siehe in der Installationsanleitung im Kapitel „Corporate Identity anpassen“) sind im falschen Format gespeichert. Bei Textänderungen müssen die Dateien mit der Codierung „ANSI“ gespeichert werden.

Speichen Sie die Dateien „LoginForm.properties“ bzw. „WillkommenForm.properties“ über den Weg „Datei speichern unter“ und wählen Sie bei Codierung „ANSI“ aus.

Während des Imports des Inhaltsupdates ist ein Fehler beim Zugriff auf die Datenbank aufgetreten. Möglicherweise ist das Programm, die Datenbank bzw. ein Teil der Datensätze beschädigt. Führen Sie folgende Schritte durch:

1. Installieren Sie die portable Version neu.
2. Kopieren Sie das letzte oder ggf. vorletzte funktionierende Backup der Datenbank (siehe Kapitel 5.2 der Installationsanleitung portable Version 4.0.2976) in die neu installierte Version.
3. Führen Sie erneut das Inhaltsupdate durch.

Sollte der Fehler weiterhin auftreten:

1. Wiederholen Sie die Schritte 1 und 2.
2. Sichern Sie Ihre Daten über die programminterne Export-Funktion.
3. Installieren Sie die portable Version neu und behalten Sie die leere Datenbank.
4. Richten Sie den Zugang gemäß Kapitel 2.1 der Installationsanleitung portable Version 4.0.2976 neu ein
5. Führen Sie erneut das Inhaltsupdate durch.
6. Importieren Sie die exportierten Daten.

Möglicherweise wurde die Datenbank oder das Programm durch einen Import beschädigt. Das Programm konnte nach dem Import normal beendet werden. Der Fehler wird erst beim Neustart ersichtlich. Führen Sie folgende Schritte durch:

1. Installieren Sie die portable Version neu.
2. Kopieren Sie das letzte oder ggf. vorletzte funktionierende Backup der Datenbank (siehe Kapitel 5.2 der Installationsanleitung portable Version 4.02976) in die neu installierte Version.
3. Führen Sie den Import erneut durch.