Umstellung von PPP 3.27.9 / 2025.1.3 auf PPP 2025.2.2
Auf dieser Seite erfahren Sie Schritt für Schritt, wie Sie eine Installation der PICTURE-Prozessplattform in Version 3.27.9 bzw. 2025.1.3 auf die aktuelle Version 2025.2.2 aktualisieren können.
Diese Anleitung bezieht sich auf die Referenzumgebung für den Betrieb der PICTURE-Prozessplattform (Debian Linux Version 12, Codename "Bookworm"). Sie lässt sich sinngemäß auch für alle weiteren Plattformen, auf welchen die PPP einsetzbar ist, anwenden. Die dazu nötige Anpassung der entsprechenden Arbeitsschritte an die konkrete Zielumgebung liegt jedoch ausschließlich in der Verantwortung des Betreibers. Anspruch auf Unterstützung durch die PICTURE GmbH besteht nicht.
Die Umstellung auf das neue Release kann aus technischen Gründen nicht im Live-Betrieb durchgeführt werden und erfordert daher zwingend ein Wartungsfenster, innerhalb dessen die Software für die Anwender nicht zur Verfügung steht. Teilen Sie Ihren Anwendern daher die geplante Ausfallzeiten im Vorfeld mit und planen Sie angemessene Zeit-Reserven ein.
Inhaltsverzeichnis
Voraussetzungen prüfen
Prüfen Sie, ob Sie derzeit eine Version der PICTURE-Prozessplattform in Betrieb haben, für welche ein direkter Migrationspfad zur neuesten für Selbsthoster vorliegenden Version 2025.2.2 angeboten wird.
Das Migrationswerkzeug (und diese Anleitung) unterstützen folgende Migrationspfade:
v3.27.9 → v2025.1.3
v2025.1.3 → v2025.2.2
Sollten Sie eine ältere Version im Einsatz haben, wenden Sie sich gerne an unseren Support (support@picture-gmbh.de), um eine individuelle Unterstützung abzustimmen.
Achtung: Für die o.g. Update-Pfade wird eine Migration der bestehenden (Nutz-)Daten benötigt. Bitte führen Sie bei der Umstellung unbedingt die Arbeitsschritte "Probelauf der Bestandsdatenmigration durchführen" und "Bestandsdatenmigration durchführen" aus.
Download-Paket herunterladen und entpacken
Laden Sie das Download-Paket zur aktuellen Version der Prozessplattform aus unserem Download-Bereich herunter (https://download.prozessplattform.de/ppp/current.zip). Der Download-Bereich ist passwortgeschützt. Als registrierter On-Premise-Kunde verfügen Sie über einen individuellen Download-Zugang. Sollten Ihnen die Zugangsdaten hierfür nicht bekannt sein, wenden Sie sich bitte an support@picture-gmbh.de.
Das Download-Paket besteht aus einem ZIP-Archiv, das alle relevanten Programme, Tools und Daten zur Aktualisierung der PICTURE-Prozessplattform enthält. Entpacken Sie dieses nach dem Download in ein temporäres Arbeitsverzeichnis:
cd ~
wget --user BENUTZERNAME --password PASSWORT https://download.prozessplattform.de/ppp/current.zip
unzip current.zip
Nach dem Auspacken sollten im Verzeichnis "ppp_[Version]" (z.B. "ppp_2025-2-2") folgende Unterverzeichnisse existieren:
config_templates: Vorlagen für die Konfigurationsdateien der PICTURE-Prozessplattform-Webanwendung (wird für das Update eines vorhandenen Mandanten nicht benötigt)
db_template: Datenbankvorlage zum Einrichten eines neuen, "leeren" Mandanten (wird für das Update eines vorhandenen Mandanten nicht benötigt)
program_files: PPP-Webanwendung sowie Unterverzeichnis mit Datenbankmigrationstool für die Umstellung einer vorhandenen älteren PPP-Version
Probemigration durchführen
Datenbank, Dokumente und Versionshistorie für Probemigration sichern
Für die Probemigration der Produktivdaten ist es notwendig, Kopien der folgender Daten anzufertigen:
Datenbank-Schema
Dateiuploads & Versionshistorie
Im Folgenden ist das Vorgehen zur Anfertigung der Kopien beschrieben.
Bei den folgenden Pfaden der zu sichernden Dateien gehen wir davon aus, dass der zu aktualisierende Mandant nach der Anleitung in unserem Betreiberhandbuch (vgl. Abschnitt 4 - Installation und Konfiguration der PICTURE-Prozessplattform) installiert wurde. Haben Sie bei der Installation abweichende Pfade benutzt, müssen Sie dies bei der Erstellung der Sicherheitskopien entsprechend berücksichtigen. Um die abweichenden Pfade zu ermitteln, kann die Ausführung der folgenden Befehle (auf Ihrem Produktivsystem) hilfreich sein:
ps aux | grep ppp.config_directory
Dieser Befehl liefert eine Momentaufnahme der laufenden Prozesse inkl. der bei deren Start angegebenen Parameter. Suchen Sie in der Ausgabe die Zeichenfolgen “-Dppp.config_directory=${CONFIG_DIRECTORY}” bzw. “-Dcatalina.home=${TOMCAT_DIRECTORY}”.
Die zu sichernden Log-Dateien befinden sich im Verzeichnis ${TOMCAT_DIRECTORY}/logs/ppp, die zur Konfiguration der PICTURE-Prozessplattform relevanten Dateien im Verzeichnis ${CONFIG_DIRECTORY}/ppp.
Der Pfad zu den Dokumenten und der Versionshistorie ist in der Konfigurationsdatei ${CONFIG_DIRECTORY}/ppp/config.xml zu finden. Führen Sie folgenden Befehl aus um diese Datei im Texteditor “nano” zu öffnen:
nano ${CONFIG_DIRECTORY}/ppp/config.xml
Der relevante Pfad zu den Dokumenten findet sich unter dem XML-Tag “uploadDirectory” z.B. “<uploadDirectory>/srv/picture/ppp/documents</uploadDirectory>”.
Führen Sie die folgenden Befehle aus um die Kopien anzufertigen:
In das Home-Verzeichnis wechseln und ein Backup-Verzeichnis anlegen:
cd ~
mkdir backup
cd backup
Datenbank sichern:
mysqldump -uroot -p ppp > db_vor_upgrade.sql
Dokumente und Versionshistorie sichern:
cd /srv/picture/ppp/documents
tar -czf ~/backup/fileUploads.tgz *
Probelauf der Bestandsdatenmigration durchführen
Zur Durchführung der Bestandsdatenmigration steht ein Datenmigrationswerkzeug zur Verfügung. Mit dessen Hilfe können sämtliche mit der zuvor installierten Version der PICTURE-Prozessplattform verwalteten Daten ohne Informationsverlust in die neuen Datenstrukturen überführt werden.
Das Migrationsprogramm verfügt über einen integrierten Selbsttest, der im Anschluss an die Migration eine Konsistenzprüfung der Datenbank durchführt. Die ordnungsgemäße Funktionsfähigkeit des Releases können wir nur sicherstellen, wenn diese Konsistenzprüfung ohne Fehler abgeschlossen werden kann. Sollten bei der Prüfung Fehler gefunden werden, empfehlen wir Ihnen daher eine Rücksprache mit unserem Support zwecks Problem Behebung.
Datenbank, Dokumente und Versionshistorie für Probelauf einspielen
An der Datenbank anmelden:
mysql -uroot -p
Neues, leeres Datenbank-Schema anlegen und ausloggen:
CREATE DATABASE `ppp_probemigration`;
GRANT ALL PRIVILEGES ON ppp_probemigration.* TO 'ppp'@'localhost' IDENTIFIED BY 'StrengGeheim';
exit;
Datenbank-Snapshot in das neue Datenbank-Schema einspielen:
mysql -uroot -p ppp_probemigration < ~/backup/db_vor_upgrade.sql
Dokumente und Versionshistorie aus den zuvor gesicherten Dateien einspielen:
cd ~
mkdir -p /srv/picture/ppp_probemigration/documents
cp ~/backup/fileUploads.tgz /srv/picture/ppp_probemigration/documents
cd /srv/picture/ppp_probemigration/documents
tar -xzf fileUploads.tgz
rm fileUploads.tgz
Datenbank-Migrationstool für den Probelauf konfigurieren
Zur Vereinfachung der Ausführung der Migration wurde das Skript "on-premise-db-migration.sh" dem Download-Paket hinzugefügt. Vor dem Starten des Skripts müssen folgende Anpassungen für Ihr System vorgenommen werden.
Datenbank-Einstellung eintragen (db.config)
Öffnen Sie die Datenbank Konfigurations-Datei im Texteditor:
cd ~/ppp_2025-2-2/program_files/migration
nano db.config
Folgende Werte müssen in der "db.config" enthalten sein und auf Ihre Gegebenheiten angepasst werden:
Variable | Bedeutung | Beispiel |
---|---|---|
db.driver | Der Datenbank-Treiber, der verwendet werden soll | org.mariadb.jdbc.Driver |
db.host | Hostname des MySQL-Datenbank-Servers, auf dem das zu migrierende Datenbank-Schema betrieben wird | localhost |
db.port | Portnummer des MySQL-Servers auf dem o.g. Host | 3306 |
db.user | Name eines MySQL-Benutzerkontos, welches volle Privilegien für das o.g. Datenbank-Schema besitzt | ppp |
db.password | Passwort des o.g. MySQL-Benutzerkontos | StrengGeheim |
Datenbankschema in Datei databases.list eintragen
nano databases.list
In der "databases.list" muss das zu migrierende Datenbank Schema eingetragen werden. Hier muss darauf geachtet werden, dass nur das Datenbank Schema in der ersten Zeile eingetragen wird:
Variable | Bedeutung | Beispiel |
---|---|---|
DB_SCHEMA | Name des zu migrierenden Datenbankschemas (Achtung: Hier die Kopie für den Probelauf eintragen!) | ppp_probemigration |
Migrations-Skript anpassen (on-premise-db-migration.sh)
Im ersten Abschnitt des Scripts (gekennzeichnet durch den Kommentar "Skript Variablen - bitte passen Sie diese für Ihre individuelle Umgebung an") befinden sich Variablen, die Sie zur Vorbereitung der Probemigration ggf. an Ihre konkreten Gegebenheiten anpassen müssen. Öffnen Sie hierzu die o.g. Datei in einem Texteditor und passen Sie die u.g. Variablen an:
nano on-premise-db-migration.sh
Ggfs. müssen folgende Variablen angepasst werden:
Variable | Bedeutung | Beispiel |
---|---|---|
SOURCE_PPP_VERSION | Versionsnummer der zu migrierenden PPP-Installation | 3.27.9 |
TARGET_PPP_VERSION | Versionsnummer der Ziel-PPP-Installation | 2025-2-2 |
JAR_PATH | Der Pfad unter dem die Jar-Dateien für die Migration abgelegt sind | /home/picture/ppp_${TARGET_PPP_VERSION}/program_files/migration |
TOMCAT_UPLOADS_DIR | Der Pfad unter dem die Uploads der Prozessplattform abgelegt werden | /srv/picture/ppp_probemigration/documents |
Migration ausführen
Machen Sie das Migrations-Skript anschließend ausführbar:
chmod +x on-premise-db-migration.sh
Nun können Sie das Skript ausführen und somit die Probemigration starten:
./on-premise-db-migration.sh
Während der Migration protokolliert das Migrations-Skript per Konsolenausgabe den Bearbeitungsfortschritt:
Log-Auszug
Migration beendet. Die Migrations-Logs sind in der Log-Datei
/home/picture/ppp_2025-2-2/program_files/migration/migration_to_2025-2-2.log zu finden.
Wenn Sie sich während der längeren Wartezeit auf das Migrations-Ergebnis versichern möchten, dass das Migrations-Tool tatsächlich noch arbeitet und nicht etwa auf Grund eines technischen Fehlers abgestürzt ist, können Sie das Log-Level in der Logger-Konfiguration des Migrations-Tools auf das Level "debug" heraufsetzen (passen Sie hierzu die Vorlage-Datei “logback.xml” im Verzeichnis mit den Migrationstools an). Beobachten Sie dann in einem separaten Terminal-Fenster die verschiedenen Log-Dateien, die in das Log-Verzeichnis des Migrationstools geschrieben werden (z.B. mit dem Befehl "tail -f PFAD_ZUR_LOGDATEI").
Protokolldatei des Probelaufs der Datenbank-Migration auswerten
Während der Migration wird die Log-Datei "migration_to_2025-2-2.log" für die Migration angelegt. Sichten Sie diese Datei nach Abschluss des Migrationslaufs indem Sie den Inhalt der Datei auf der Konsole ausgeben
cat migration_to_2025-2-2.log
Prüfen Sie, ob sich hier Hinweise auf Fehler bei der Datenmigration bzw. der anschließenden Konsistenzprüfung finden. Falls ein Migrationsschritt erfolgreich durchgeführt wurde, finden Sie in den Logdateien keine Java-Stacktraces und am Anfang bzw. Ende der Datei finden sich Log-Ausgaben folgender Art:
Auszug migration_to_2025-2-2.log
2025-03-27 10:34:14,788 PICTURE INFO main org.flywaydb.core.internal.command.DbMigrate - Successfully applied 6 migrations to schema `ppp_probemigration` (execution time 00:09.970s).
Falls hier stattdessen Fehler gemeldet werden oder falls der Datenbankmigrationslauf sogar mit einer Fehlermeldung abbrechen sollte, fahren Sie bitte keinesfalls mit der Migration der Produktivdaten fort und nehmen Sie stattdessen bitte Kontakt mit dem PICTURE-Support auf. Schicken Sie bei Ihrer Anfrage bitte die Protokolldateien des fehlgeschlagenen Probelaufs mit.
Bei dieser Datenmigration können ggf. Warnungen (vgl. folgende Auszüge) ausgegeben werden, die keinen Einfluss auf die korrekte Migration Ihrer Daten haben.
2025-03-27 10:44:52,187 PICTURE WARN main org.flywaydb.core.internal.command.DbMigrate - Schema `ppp_probemigration` has a version (3.26.0.2) that is newer than the latest available migration (1) !
2025-03-27 10:44:56,309 PICTURE WARN main org.flywaydb.core.internal.dbsupport.JdbcTemplate - DB: Can't DROP COLUMN `lastCommentFeedVisit`; check that it exists (SQL State: null - Error Code: 1091)
Update der Produktiv-Installation durchführen
Tomcat-Server herunterfahren
Nachdem Sie diesen Schritt durchgeführt haben, ist das Produktivsystem nicht mehr erreichbar. Führen Sie diese Arbeiten deshalb in einem geeigneten Wartungsfenster aus.
Falls der Probelauf der Datenbank-Migration erfolgreich abgeschlossen werden konnte, können Sie mit der Bestandsdatenmigration der Nutzdaten des Produktivsystems beginnen. Fahren Sie hierzu zunächst den Tomcat-Server herunter (erfordert root-Berechtigung):
systemctl stop tomcat10
Bestandsdatenmigration durchführen
Datenbank-Schema der Produktiv-Datenbank eintragen (databases.list)
cd ~/ppp_2025-2-2/program_files/migration
nano databases.list
In der "databases.list" muss das zu migrierende Datenbank-Schema eingetragen werden (Hier muss darauf geachtet werden, dass nur das Datenbank-Schema in der ersten Zeile eingetragen wird):
Variable | Bedeutung | Beispiel |
---|---|---|
DB_SCHEMA | Name des zu migrierenden Datenbank-Schemas | ppp |
Migrations-Skript an Produktiv-Umgebung anpassen (on-premise-db-migration.sh)
nano on-premise-db-migration.sh
In der "on-premise-db-migration.sh" muss das zu migrierende Verzeichnis der Dokumente und Versionshistorie eingetragen werden:
Variable | Bedeutung | Beispiel |
---|---|---|
TOMCAT_UPLOADS_DIR | Der Pfad unter dem die Uploads der Prozessplattform abgelegt werden | /srv/picture/ppp/documents |
Nun können Sie das Script ausführen und somit die Migration starten:
./on-premise-db-migration.sh
Protokolldatei der Bestandsdatenmigration auswerten
Während der Bestandsdatenmigration wird die Log-Datei "migration_to_2025-2-2.log" für die Migration fortgeschrieben. Sichten Sie diese Datei nach Abschluss des Migrationslaufs nochmals mit einem Texteditor. Prüfen Sie, ob sich hier Hinweise auf Fehler bei der Bestandsdatenmigration bzw. der anschließenden Konsistenzprüfung finden.
WAR-Datei der Webanwendung austauschen
Löschen Sie nun die alte WAR-Datei der PPP und ersetzen Sie diese durch die WAR-Datei der PPP 2025-2-2 Führen Sie hierzu folgende Befehle aus:
rm -rf /var/lib/tomcat10/webapps/ppp.war
rm -rf /var/lib/tomcat10/webapps/ppp
cp ~/ppp_2025-2-2/program_files/ppp.war /var/lib/tomcat10/webapps/
Konfigurationsdatei anpassen
Mit der Version 2025.2.x wurde die PICTURE-Prozessplattform um einen Mechanismus erweitert, mittels dessen eine optionale automatische Güteprüfung für benutzerdefinierte Passwörter gegen den externen Webservice von “HIBP Passwords” durchgeführt werden kann (vgl. Passwortgüteprüfung über die externe API von "Have I Been Pwned?" ).
Mit einer neuen Einstellung in der Datei “config.xml” kann durch den technischen Betreiber eingestellt werden, ob diese zusätzliche Option den Fachadministratoren bei der Definition einer eigenen Passwortrichtlinie zur Verfügung stehen soll:
Durch Setzen der Einstellung auf
true
wird die Funktion den Fachadministratoren angeboten. Dies ist auch die Standard-Einstellung.Internetverbindung erforderlich: Damit die Prüfung funktioniert, muss der Hosting-Server der Prozessplattform-Webanwendung dauerhaft Zugriff auf den Webservice von HIBP haben. Das bedeutet insbesondere, dass der Zugriff in der Firewall freigegeben sein muss.
Offline-Betrieb: Wenn der Server dauerhaft keinen Internetzugang hat oder der Zugriff auf den Webservice nicht freigeschaltet werden kann, sollte der Wert auf
false
gesetzt werden, um Fehler bei der Passwortprüfung zu vermeiden.
Wichtig:
Das Setzen dieser Konfigurationsoption auf true
aktiviert die Prüfung nicht automatisch. Es handelt sich lediglich um eine technische Voraussetzung dafür, dass Fachadministratoren im Verwaltungsmodul der Prozessplattform unter:
Verwaltung → Rechtliches & Datenschutz → Passwort-Richtlinie
die Passwortgüteprüfung explizit aktivieren können. Nur wenn diese Option im Verwaltungsmodul durch den Fachadmin eingeschaltet wird, erfolgt tatsächlich eine Prüfung der Passwörter gegen den HIBP-Webservice.
Mit anderen Worten:
Die Konfigurationsdatei legt fest, ob die Funktionalität grundsätzlich zur Verfügung steht. Die tatsächliche Aktivierung erfolgt über die Benutzeroberfläche durch die Fachadministration im Rahmen der Definition einer individuellen Passwort-Richtlinie.
Bitte führen Sie folgenden Befehl aus, um die Konfigurationsdatei anzupassen:
nano /etc/picture/ppp/config.xml
Fügen Sie nun am Ende der Datei den folgenden Abschnitt - direkt über “</applicationSettings>” - hinzu:
</contextRepositories>
<cspSettings>
<mode>PRODUCTION</mode>
</cspSettings>
<!-- Beginn des neuen Eintrags -->
<externalPasswordCheckEnabled>true</externalPasswordCheckEnabled>
<!-- Ende des neuen Eingtrags -->
</applicationSettings>
Tomcat-Server starten
Die Vorbereitungen zum Update der PPP sind damit abgeschlossen. Starten Sie nun den Tomcat-Server:
systemctl start tomcat10
"Smoke-Test" durchführen
Ca. 10 - 30 Sekunden nach dem Start des Tomcat-Servers sollte der Tomcat-Server das Deployment der PPP-Webanwendung abgeschlossen haben und Beim Aufruf der URL der Webanwendung im Webbrowser sollte der Login-Bildschirm zur Verfügung stehen.
Falls bereits das Deployment der Webanwendung fehlschlagen sollte, sodass der Login-Bildschirm gar nicht erst aufgerufen werden kann, finden Sie in den folgenden Log-Dateien möglicherweise erste Ansätze zur Fehlersuche:
/var/lib/tomcat10/logs/ppp/PPP.log (Logdatei der PPP-Webanwendung; Pfad wird definiert in der Datei logback.xml im Konfigurationsverzeichnis der PPP-Webanwendung)
/var/lib/tomcat10/logs/catalina.{yyyy-mm-dd}.log (Logdatei des Tomcat-Servers)
/var/lib/tomcat10/logs/localhost.{yyyy-mm-dd}.log (enthält i.d.R. Hinweise auf schwerwiegende Fehler, derentwegen der Tomcat-Server so früh fehlschlägt, dass in die o.g. Log-Dateien gar nicht erst geschrieben wird).
/var/lib/tomcat10/logs/localhost_access_log.{yyyy-mm-dd}.txt (enthält die Informationen zu jeder Anfrage, die den Server erreicht. Es kann zum Verfolgen von Seitenzugriffszahlen, Benutzersitzungsaktivitäten usw. verwendet werden, da alle eingehenden Anforderungen zusammen mit Zeitstempel, HTTP-Anforderungsmethode und HTTP-Antwortcode protokolliert werden.)
Erscheint erwartungsgemäß der Login-Bildschirm, dann loggen Sie sich in die PPP ein und prüfen Sie deren prinzipielle Funktionsfähigkeit, in dem Sie zentrale Features stichprobenartig testen:
Suche nach Prozessnamen im Prozessregister
Öffnen eines Prozesssteckbriefs zur Ansicht
Exportieren des Steckbriefs als PDF-Datei (=> Kann die heruntergeladene PDF-Datei in einem PDF-Reader geöffnet werden und enthält sie keine offensichtlichen Fehler?)
Öffnen eines Prozess-Detailmodells (Kopie eines "echten" Prozesses bzw. Testdaten) zum Bearbeiten, Änderung durchführen, anschließend speichern
Ausführen einer Analyse-App und Durchführung eines Excel-Exports (=> Kann die heruntergeladene Excel-Datei in Excel geöffnet werden?)
Aufräumarbeiten durchführen
Wenn alle Schritte durchgeführt wurden und die PICTURE-Prozessplattform - wie gewünscht - läuft, nehmen Sie sich nun noch die Zeit das Home-Verzeichnis des User “picture” wieder aufzuräumen. Führen Sie dazu folgende Befehle aus:
rm -R ~/backup
rm -R ~/ppp_2025-2-2
rm ~/current.zip