Umstellung von PPP ab 3.19.x nach PPP 3.23.x - Windows Server 2022

Owned by Andreas Hartz
Last updated: Feb. 23, 2024 by Malte Stockmann
9 min read

Auf dieser Seite erfahren Sie Schritt für Schritt, wie Sie eine Installation der PICTURE-Prozessplattform ab Version 3.19.x auf die Versionslinie 3.23.x aktualisieren können.

Diese Anleitung bezieht sich auf den Betrieb der PICTURE-Prozessplattform auf Basis des Betriebssystems Windows Server 2022.

Wir empfehlen für den Betrieb der PICTURE-Prozessplattform den Einsatz von Debian Linux Version 12 (Codename “Bookworm”). Hierbei handelt es sich um die Referenzumgebung, welche wir für unser SaaS-Hosting-Angebot selbst einsetzen. Aus betrieblichen Gründen (und wie im Dokument kommuniziert) bieten wir offiziellen Support für Selbsthoster ausschließlich dann an, wenn das Hosting in dieser Referenzumgebung erfolgt. Wie Sie die Installation des Systems in der Referenzumgebung vornehmen können, ist unserem beschrieben. Das Hosting der Prozessplattform in einer davon abweichenden Laufzeitumgebung erfolgt grundsätzlich auf eigenes Risiko des Betreibers und unter Ausschluss jeglicher Gewährleistung seitens der PICTURE GmbH.

Dieses Dokument (Umstellung von PPP ab 3.19.x nach PPP 3.23.x - Windows Server 2022) wird ausschließlich auf Kulanzbasis und unter Ausschluss jeglicher Gewährleistung seitens der der PICTURE GmbH angeboten.

Die Version 3.23 der PICTURE-Prozessplattform setzt den Einsatz folgender Drittanbieter-Software voraus:

  • Java Runtime Environment (JRE) 11 (z.B. Eclipse Temurin™ JRE 11) 

  • Apache Tomcat 10.1.x oder neuer

  • MariaDB 10.11.x oder neuer

 

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.23.3 angeboten wird. Das Migrationswerkzeug unterstützt folgende Migrationspfade:

  • v3.19.1 → v3.23.3

  • v3.21.1 → v3.23.3

Sollten Sie eine ältere Version im Einsatz haben, wenden Sie sich an unseren Support (support@picture-gmbh.de)!

Für die beiden unterstützten Navigationspfade 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. 

Sicherheitskopien anfertigen 

Vor der Migration der Produktivdaten und dem Einspielen des neuen Releases empfehlen wir Ihnen, Sicherheitskopien folgender Daten anzufertigen: 

  • Datenbank-Schema

  • Dateisystem-Repository (hochgeladene Dokumente und Versionshistorie)

  • Logdateien

Führen Sie dazu die folgenden Befehle aus: 

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

Log-Dateien sichern

Deinstallieren alter Versionen von Drittanbieter-Komponenten

Der Betrieb der PICTURE-Prozessplattform erfordert ab Version 3.23 die Installation neuer Versionen der Drittanbieter-Komponenten Tomcat sowie MariaDB. Deinstallieren Sie dazu zunächst die vorhandenen Versionen mithilfe der Systemsteuerung (Systemsteuerung\Programme\Programme und Features).

Installation neuer Versionen von Drittanbieter-Komponenten

Bitte folgen Sie den Anweisungen in den folgenden beiden Abschnitten aus unserer Installationsanleitung für die Ersteinrichtung der PICTURE-Prozessplattform:

(Die übrigen Abschnitte der Anleitung müssen nicht ausgeführt werden, da sich die Anforderungen bzgl. des Java Runtime Environments sowie der Schriftarten-Installation nicht von denen der Vorgänger-Version der PICTURE-Prozessplattform unterscheiden.)

Setzen Sie anschließend die Anweisungen zur Konfiguration von MariaDB und Tomcat wie im folgenden Artikel beschrieben um:

In den nachfolgenden Schritten ist beschrieben, wie Sie Ihre zuvor gesicherten Daten dorthin übertragen und die Installation und Konfiguration der PICTURE-Prozessplattform vornehmen können.

Download-Paket herunterladen und entpacken

Laden Sie das Download-Paket zur aktuellen Version aus unserem Download-Bereich herunter (https://download.prozessplattform.de/ppp/ppp_3-23-3.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-23-3") 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

Probelauf der Bestandsdatenmigration durchführen

Für alle in der o.g. Migrationspfade 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 (support@picture-gmbh.de) zwecks Problembehebung.

Neues, leeres Datenbank-Schema anlegen

Einloggen

Schema erstellen und ausloggen

Datenbank-Snapshot in das neue Datenbank-Schema einspielen

Dokumente und Versionshistorie aus den zuvor gesicherten Dateien einspielen


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:

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

Variable

Bedeutung

Beispiel

Variable

Bedeutung

Beispiel

db.driver

Der Datenbank-Treiber, der verwendet werden soll

org.mariadb.jdbc.Driver

db.hostname

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

GeheimesPasswort

Datenbankschema eintragen (databases.list)

In der Datei "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

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.cmd)

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:

Ggfs. müssen folgende Variablen angepasst werden:

Variable

Bedeutung

Beispiel

Variable

Bedeutung

Beispiel

SOURCE_PPP_VERSION

Versionsnummer der zu migrierenden PPP-Installation 

3.21.1

TARGET_PPP_VERSION

Versionsnummer der Ziel-PPP-Installation

3-23-3

JAR_PATH

Der Pfad unter dem die Jar-Dateien des Migrations-Tools abgelegt sind

C:\Windows\Temp\ppp_%TARGET_PPP_VERSION%\program_files\migration

TOMCAT_UPLOADS_DIR

Der Pfad unter dem die Uploads der Prozessplattform abgelegt werden

C:\PICTURE\data\uploads\ppp_probemigration\documents

Migration ausführen

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


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

Log-Auszug


Protokolldatei des Probelaufs der Datenbank-Migration auswerten

Während der Migration wird die Log-Datei "migration_to_3-23-3.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-23-3.log

Tomcat-Server herunterfahren

Falls der Probelauf der Datenbankmigration erfolgreich abgeschlossen werden konnte, können Sie mit der Migration des Produktivsystems beginnen. Fahren Sie hierzu zunächst den Tomcat-Server herunter (erfordert Administrator-Berechtigung): 

Bestandsdatenmigration durchführen

Datenbank-Schema des Probelauf löschen

Einloggen

Datenbank löschen

Neues, leeres Datenbank-Schema anlegen

Schema erstellen und ausloggen

Datenbank-Snapshot in das neue Datenbank-Schema einspielen

Datenbank-Schema eintragen (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

Variable

Bedeutung

Beispiel

DB_SCHEMA

Name des zu migrierenden Datenbank-Schemas

ppp

Dokumente und Versionshistorie des Probelauf löschen

Migrations-Skript anpassen (on-premise-db-migration.cmd)

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

Variable

Bedeutung

Beispiel

Variable

Bedeutung

Beispiel

TOMCAT_UPLOADS_DIR

Der Pfad unter dem die Uploads der Prozessplattform abgelegt werden

C:\PICTURE\data\uploads\ppp\documents

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

Protokolldatei der Bestandsdatenmigration auswerten

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

Änderungen an der Konfigurations-Datei durchführen

Die neue Version der PICTURE-Prozessplattform setzt neue Einstellungen im Bereich der Datenbank-Einstellungen voraus. Es haben sich folgenden Einstellungen geändert:

  • connectionUrl:

    • alt: jdbc:mysql://localhost/ppp

    • neu: jdbc:mariadb://localhost/ppp

  • sqlDialect:

    • alt: org.hibernate.dialect.MariaDB53Dialect

    • neu: org.hibernate.dialect.MariaDBDialect

Nach der Änderung sollten die Konfigurationseinträge das u.g. Format haben:

<connectionUrl>jdbc:mariadb://localhost/ppp</connectionUrl><sqlDialect>org.hibernate.dialect.MariaDBDialect</sqlDialect>

Zugangsdaten in einen geeigneten Passwort-Manager übertragen

In der Version 3.23 der PICTURE-Prozessplattform wurde eine automatische Verschlüsselung der Konfigurations-Datei “config.xml” eingeführt. Dieser Mechanismus verschlüsselt die Geheimnisse in der o.g. Datei, falls zum Zeitpunkt des Hochfahrens der PPP-Webanwendung noch unverschlüsselt sind.
Alle Zugangsdaten, wie zum Beispiel das Passwort für MariaDB, den Content Broker (Datenaustausch-Plattform für Zugriff auf das Prozessmanagement-Netzwerk “PICTURE improve”) sowie den Mail-Server, sollten Sie aus diesem Grund in einem geeigneten Passwort-Manager verwalten, da diese Geheimnisse nach dem ersten Start der Anwendung nicht mehr zugänglich sind. Sie können jederzeit die Geheimnisse in der Datei anpassen und im Klartext neu hinterlegen. Die Verschlüsselung wird dann beim Neustart der Anwendung durchgeführt. Auf diese Weise können Sie geänderte Passwörter leicht aktualisieren ohne diese aufwendig, manuell verschlüsseln zu müssen. Sie erkennen die verschlüsselten Geheimnisse an dem Schlüsselwort ENCRYPTED().

Log-Dateien wieder einspielen

In diesem Schritt werden die gesicherten Log-Dateien wiederhergestellt, damit Sie im Fehlerfall auch historische Log-Dateien zur Verfügung haben. Das Log-Verzeichnis wird mit den folgenden Befehlen zurückgesichert:

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: 

Tomcat-Server starten

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

"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

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.