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 3.26.5 angeboten wird.

Das Migrationswerkzeug (und diese Anleitung) unterstützt folgende Migrationspfade:

• v3.23.3 → v3.26.5

• v3.24.4 → v3.26.5

• v3.25.6 → v3.26.5

• v3.26.4 → v3.26.5

Falls Sie bisher noch Version 3.19.x oder 3.21.x einsetzen, führen Sie zunächst das Update auf Version 3.23.3 durch. Hierzu können Sie den Migrationsleitfaden Umstellung von PPP ab 3.19.x nach PPP 3.23.x - Windows Server 2022 nutzen.

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.

Download-Paket herunterladen und entpacken

Laden Sie das Download-Paket zur aktuellen Version 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 (z.B. C:\Windows\Temp)

Nach dem Auspacken sollten in im Verzeichnis "ppp_[Version]" (z.B. "ppp_3-26-5") 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.

Führen Sie die folgenden Befehle aus um die Kopien anzufertigen: 

In das Windows-Temp-Verzeichnis wechseln und ein Backup-Verzeichnis anlegen

cd C:\Windows\Temp
mkdir backup
cd backup

Datenbankinhalte sichern (MariaDB)

mysqldump -uroot -p ppp > db_vor_upgrade.sql

Dateisystem-Repository (hochgeladene Dokumente und Versionshistorie) sichern

robocopy C:\PICTURE\data\uploads\ppp\documents C:\Windows\Temp\backup\documents /MIR

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.

2024-04-03 12:55:32,710 PICTURE INFO main picture.migration.R__MigrateProcessContexts - ---> Prüfe Prozesskontexte <---
2024-04-03 12:55:33,498 PICTURE INFO main picture.migration.R__MigrateProcessContexts - Anzahl Workspaces: 3
2024-04-03 12:55:33,499 PICTURE INFO main picture.migration.R__MigrateProcessContexts - --- Überprüfe Workspace Prozessregister Stadt Musterhausen ---
2024-04-03 12:55:34,580 PICTURE WARN main picture.migration.R__MigrateProcessContexts - 2 verwaiste Elemente im Baum Document gefunden
2024-04-03 12:55:34,652 PICTURE INFO main picture.migration.R__MigrateProcessContexts - korrigiere Baum Document
2024-04-03 12:55:34,652 PICTURE INFO main picture.migration.R__MigrateProcessContexts - füge 2 Document Elemente hinzu
2024-04-03 12:55:34,759 PICTURE INFO main picture.migration.R__MigrateProcessContexts - Füge neuen virtuellen Wurzelknoten im Baum Document zur Datenwiederherstellung ein. AB: Prozessregister Stadt Musterhausen
2024-04-03 12:55:35,039 PICTURE INFO main picture.migration.R__MigrateProcessContexts - --- Überprüfe Workspace Schulungs-/Testumgebung ---
2024-04-03 12:55:35,670 PICTURE INFO main picture.migration.R__MigrateProcessContexts - --- Überprüfe Workspace Querschnittsprozesse ---
2024-04-03 12:55:35,884 PICTURE INFO main picture.migration.R__MigrateProcessContexts - ---> Prozesskontexte Prüfung abgeschlossen <---

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 Problembehebung.

Datenbank, Dokumente und Versionshistorie für Probelauf einspielen 

An der Datenbank anmelden:

mysql -uroot

Neues, leeres Datenbank-Schema anlegen und ausloggen:

CREATE DATABASE `ppp_probemigration`;
GRANT ALL PRIVILEGES ON ppp_probemigration.* TO 'ppp'@'localhost' IDENTIFIED BY 'GeheimesPasswort';
exit;

Datenbank-Snapshot in das neue Datenbank-Schema einspielen:

mysql -uroot ppp_probemigration < C:\Windows\Temp\backup\db_vor_upgrade.sql

Dokumente und Versionshistorie aus den zuvor gesicherten Dateien einspielen

robocopy C:\Windows\Temp\backup\documents C:\PICTURE\data\uploads\ppp_probemigration\documents /MIR

Datenbank-Migrationstool für den Probelauf konfigurieren

Zur Vereinfachung der Ausführung der Migration wurde das Skript "on-premise-db-migration.cmd" 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 C:\Windows\Temp\ppp_[Version]\program_files\migration
notepad db.config

Folgende Werte müssen in der "db.config" enthalten sein und auf Ihre Gegebenheiten angepasst werden:

Datenbankschema in Datei databases.list eintragen

notepad 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:

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:

notepad on-premise-db-migration.cmd

Ggfs. müssen folgende Variablen angepasst werden:

Migration ausführen

Nun können Sie das Skript ausführen und somit die Probemigration starten:

on-premise-db-migration.cmd

Während der Migration protokolliert das Migrations-Skript per Konsolenausgabe den Bearbeitungsfortschritt: 

Log-Auszug

Migration beendet. Die Migrations-Logs sind in der Log-Datei C:\Windows\Temp\ppp_3-26-5\program_files\migration\migration_to_3-26-5.log zu finden.

Protokolldatei des Probelaufs der Datenbank-Migration auswerten

Während der Migration wird die Log-Datei "migration_to_3-26-5.log" angelegt. Sichten Sie diese Dateien nach Abschluss des Migrationslaufs jeweils mit einem Texteditor. 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_3-26-5.log

2023-08-28 14:28:07,481 PICTURE INFO main org.flywaydb.core.internal.dbsupport.DbSupportFactory - Database: jdbc:mariadb://localhost:3306/ppp_probemigration (MySQL 10.11)
[...]
2023-08-28 14:28:13,754 PICTURE INFO main org.flywaydb.core.internal.command.DbMigrate - Successfully applied 2 migrations to schema `ppp_probemigration` (execution time 00:03.565s).

2023-08-28 14:28:48,904 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) !

Update der Produktiv-Installation durchführen

Tomcat-Server herunterfahren

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): 

net stop Tomcat10

Bestandsdatenmigration durchführen

Datenbank-Schema der Produktiv-Datenbank eintragen (databases.list)

cd C:\Windows\Temp\ppp_[Version]\program_files\migration
notepad 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):

Migrations-Skript an Produktiv-Umgebung anpassen (on-premise-db-migration.sh)

notepad on-premise-db-migration.cmd

In der "on-premise-db-migration.cmd" muss das zu migrierende Verzeichnis der Dokumente und Versionshistorie eingetragen werden:

Nun können Sie das Script ausführen und somit die Migration starten:

on-premise-db-migration.cmd

Protokolldatei der Bestandsdatenmigration auswerten

Während der Bestandsdatenmigration wird die Log-Datei "migration_to_3-26-5.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 einspielen

Kopieren Sie nun die neue WAR-Datei der PPP in das “webapps”-Verzeichnis des Tomcat-10-Servers. Führen Sie hierzu folgende Befehle aus: 

copy C:\Windows\Temp\ppp_3-26-5\program_files\ppp.war "C:\Program Files\Apache Software Foundation\Tomcat 10.1\webapps" /y

Tomcat-Server starten

Die Vorbereitungen zum Update der PPP sind damit abgeschlossen. Starten Sie nun den Tomcat-Server: 

net 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: 

• C:\Program Files\Apache Software Foundation\Tomcat 10.1\logs\ppp\PPP.log (Logdatei der PPP-Webanwendung; Pfad wird definiert in der Datei logback.xml im Konfigurationsverzeichnis der PPP-Webanwendung)

• C:\Program Files\Apache Software Foundation\Tomcat 10.1\logs\catalina.{yyyy-mm-dd}.log (Logdatei des Tomcat-Servers)

• C:\Program Files\Apache Software Foundation\Tomcat 10.1\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).

• C:\Program Files\Apache Software Foundation\Tomcat 10.1\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 einen 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 Verzeichnis C:\Windows\Temp wieder aufzuräumen. Löschen Sie dazu das Verzeichnis C:\Windows\Temp\ppp_[Version] mithilfe des Windows Explorers.