Vergleichsreport

Diese Seite beschreibt, wie ein Update bzw. Upgrade von This page describes how an update or upgrade of Webdesk 4.x abläuft und wie es sicher durchgeführt wird. Sie erklärt, was Webdesk beim Start einer neuen Programmversion automatisch erledigt (Datenbankschema, Modul-Upgrade-Skripte, Registrierung) und welche Einstellungen dabei eine Rolle spielen. Zielgruppe sind Systemadministratoren und Consultants. Die Seite gilt für Webdesk 4.x, das als WAR-Datei in einem Tomcat oder als Container-Image betrieben wird. Das Update mit dem Windows-Installer works and how to carry it out safely. It explains what Webdesk does automatically when a new program version starts (database schema, module upgrade scripts, registration) and which settings play a role. The audience is system administrators and consultants.

The page applies to Webdesk 4.x operated as a WAR file in a Tomcat or as a container image. The update with the Windows installer (setup-...exe) ist auf der Seite is described on the page Webdesk Update beschrieben; diese Seite ergänzt sie um die Hintergründe und die Abläufe für WAR- und Container-Betrieb. Die Erstinstallation ist unter Webdesk 4 beschrieben.

Voraussetzungen

; this page complements it with the background and the procedures for WAR and container operation. The initial installation is described under Webdesk 4.

Prerequisites

• Java 17: Webdesk 4.64 und der and the IF6020 -TA-Connector laufen mit TA connector run on Java 17, ; Java 11 ist für diese Version nicht ausreichend (siehe is not sufficient for this version (see Breaking Changes 4.64). Das mitgelieferte Container-Image basiert auf einem The supplied container image is based on a JDK 17. Bei mehreren Java-Installationen ist zu prüfen, welche Java-Version der Dienst bzw. das Startskript tatsächlich verwendet. Tomcat 9: Das Container-Image If several Java installations exist, check which Java version the service or start script actually uses.
• Tomcat 9: The container image (webdesk-webapp/Dockerfile) basiert auf einem Tomcat-9-Image mit is based on a Tomcat 9 image with JDK 17. Auch der Windows-Installer liefert einen The Windows installer also ships a Tomcat 9 mit.
• JVM parameters -Parameter --add-opens: Je nach Betriebsart sind beim Start der JVM folgende Parameter erforderlich (Liste laut Neue Depending on the way Webdesk is operated, the following parameters are required when the JVM starts (list according to New Features 4.64):

  --add-opens java.base/jdk.internal.loader=ALL-UNNAMED
  --add-opens java.base/jdk.internal.module=ALL-UNNAMED
  --add-opens java.base/jdk.internal.reflect=ALL-UNNAMED
  --add-opens java.base/java.lang.module=ALL-UNNAMED
  --add-opens jdk.crypto.ec/sun.security.ec.point=ALL-UNNAMED
  --add-opens jdk.dynalink/jdk.dynalink.linker.support=ALL-UNNAMED
  --add-opens java.base/sun.util.calendar=ALL-UNNAMED
  --add-opens java.base/java.util.concurrent.locks=ALL-UNNAMED
  --add-opens java.base/java.lang=ALL-UNNAMED
  --add-opens java.base/java.lang.invoke=ALL-UNNAMED
  --add-opens java.base/java.lang.reflect=ALL-UNNAMED
  --add-opens java.base/java.io=ALL-UNNAMED
  --add-opens java.base/java.util=ALL-UNNAMED
  --add-opens java.rmi/sun.rmi.transport=ALL-UNNAMED
  --add-opens java.base/java.net=ALL-UNNAMED

  Die Parameter werden dort gesetzt, wo die JVM gestartet wird, z. B. über die Umgebungsvariable Set the parameters where the JVM is started, e.g. through the environment variable JDK_JAVA_OPTIONS (so setzt das mitgelieferte this is how the catalina.bat des Windows-Installers einige davon) oder über die Tomcat-Startoptionen. Im Container müssen sie an die JVM des Containers übergeben werden; das Dockerfile der Webanwendung setzt sie nicht selbst. Ausgangsversion: Webdesk-Versionen älter als 3.8 benötigen laut Webdesk Update zuerst ein Update auf die letzte supplied with the Windows installer sets some of them) or through the Tomcat start options. In a container they must be passed to the container's JVM; the Dockerfile of the web application does not set them itself.
• Source version: According to Webdesk Update, Webdesk versions older than 3.8 first require an update to the latest 3.8.x.
• Hinweise zur Zielversion: Vor jedem Update sind die Seiten "Neue Features" und Notes on the target version: Before every update, read the "New Features" and "Breaking Changes" der Zielversion zu lesen, z. Bpages of the target version, e.g. Breaking Changes 4.64. Beim Update auf When updating to Webdesk 4.56 oder höher werden gespeicherte Zugangsdaten neu verschlüsselt, siehe Neue or higher, stored credentials are re-encrypted, see New Features in 4.56.

Was beim Start einer neuen Version passiert

Ein Update besteht im Kern aus dem Austausch der Programmdateien und einem Neustart. Alle weiteren Schritte führt Webdesk beim Start selbst aus, in dieser Reihenfolge:

What happens when a new version starts

At its core, an update consists of replacing the program files and restarting. Webdesk performs all further steps itself during startup, in this order:

1. Hibernate schema update: When the Hibernate session factory is built, missing tables and columns of the Webdesk database are added automatically (property webdesk-sessionFactory.schemaUpdate, Standarddefault: aktivenabled). Umbenennungen, Löschungen und Datenmigrationen leistet das Schemaupdate nicht; dafür gibt es die Modul-Upgrade-Skripte. Index-Manager: Vergleicht die vorhandenen Datenbankindizes mit den erwarteten und legt fehlende an The schema update does not perform renames, deletions or data migrations; that is what the module upgrade scripts are for.
2. Index manager: Compares the existing database indexes with the expected ones and creates missing ones (PoStartup.executeIndexManager, Standarddefault: aktiv; Fehler hierbei führen nur zu einer Warnung im Log).
3. Modul-Upgrade-Skripte: Für jedes Modul werden die Upgrade-Schritte der neuen Version ausgeführt (siehe unten). Dieser Schritt läuft bei jedem Start und ist nicht abschaltbar.
4. Prüfungen: Konsistenzprüfungen der Datenbank (bei MySQL u. a. der Zeichensatz) und eine Zeitleisten-Prüfung der Personen (abschaltbar mit webdesk.disableTimeLineChecks).
5. Lizenz und Systemparameter: Die Lizenzdefinitionen werden geladen. Neue Systemparameter (Beanproperties) werden in die Datenbank geschrieben, bestehende Werte bleiben erhalten, und alle Werte werden angewendet.
6. Registrierung: Aktionen, Konfigurationen, Textbausteine, Jobs usw. der Module werden in die Datenbank übernommen. Ob und wie das geschieht, steuert webdesk.runRegistration (siehe unten).
7. Volltextindex: Der Suchindex wird aktualisiert (webdesk.luceneIndexing, Standard: aktiv).

Relevante Einstellungen in der webdesk.properties

Eigenschaft

Erklärung

mögliche Wert(e)

webdesk.runRegistration

1. enabled; errors here only cause a warning in the log).
2. Module upgrade scripts: For each module, the upgrade steps of the new version are executed (see below). This step runs on every startup and cannot be switched off.
3. Checks: Database consistency checks (for MySQL, among others, the character set) and a timeline check of the persons (can be switched off with webdesk.disableTimeLineChecks).
4. Licence and system parameters: The licence definitions are loaded. New system parameters (bean properties) are written to the database, existing values are kept, and all values are applied.
5. Registration: Actions, configurations, text modules, jobs etc. of the modules are transferred to the database. Whether and how this happens is controlled by webdesk.runRegistration (see below).
6. Full-text index: The search index is refreshed (webdesk.luceneIndexing, default: enabled).

Relevant settings in webdesk.properties

Modul-Upgrade-Skripte

Wie die Version entscheidet, was ausgeführt wird

Module upgrade scripts

How the version decides what is executed

Each module (po, wf, ta, gw, ...) hat eine eigene Versionsnummer, eine fortlaufende ganze Zahl, die unabhängig von der Webdesk-Releasenummer ist. Der Stand pro Modul ist in der Datenbank gespeichert und wird in der Aktion "Module" in der Spalte "Version" angezeigt. Das Programm bringt für jedes Modul die Zielversion mit. Beim Start gilt:

has its own version number, a consecutive integer that is independent of the Webdesk release number. The current state per module is stored in the database and shown in the action "Modules" in the column "Version". The program brings the target version for each module. At startup:

• If the stored version equals the target version, nothing happens (log: Module ... is up-to-date).
• Ist die gespeicherte Version kleiner, werden für jede Version dazwischen die Dateien im Ordner If the stored version is lower, the files in the module's folder .../update/vNN/ des Moduls ausgeführt (NN ist die jeweilige Versionsnummer). Zuerst laufen die prepare.xml aller anstehenden Versionen, danach die upgrade.xml Version für Version. Nach jeder erfolgreich abgeschlossenen upgrade.xml wird die neue Versionsnummer in der Datenbank gespeichert.
• Ein neu hinzukommendes Modul (z. B. nach Lizenzerweiterung) wird direkt mit der Zielversion angelegt, es werden keine Upgrade-Schritte ausgeführt.
• Module, die in der neuen Version nicht mehr vorhanden bzw. lizenziert sind, werden auf "deaktiviert" (detached) gesetzt; sie werden wieder aktiviert, sobald sie erneut vorhanden sind.
• Die Module werden immer in derselben, durch ihre Abhängigkeiten festgelegten Reihenfolge verarbeitet, und jedes Modul wird vollständig (prepare und upgrade) abgeschlossen, bevor das nächste beginnt.

Ist die gespeicherte Version größer als die Zielversion (ältere Programmversion gegen neuere Datenbank), wird kein Skript ausgeführt; die gespeicherte Versionsnummer wird lediglich auf die niedrigere Zielversion gesetzt. Siehe Abschnitt "Rückweg".

Aufbau einer Upgrade-Datei

• are executed for every version in between (NN is the respective version number). First the prepare.xml files of all pending versions run, then the upgrade.xml files version by version. After each successfully completed upgrade.xml the new version number is saved in the database.
• A newly added module (e.g. after a licence extension) is created directly with the target version; no upgrade steps are executed.
• Modules that no longer exist or are no longer licensed in the new version are set to "detached"; they are reactivated as soon as they are available again.
• The modules are always processed in the same order, which is determined by their dependencies, and each module is completed entirely (prepare and upgrade) before the next one begins.

If the stored version is higher than the target version (older program version against a newer database), no script is executed; the stored version number is merely set to the lower target version. See the section "Rolling back".

Structure of an upgrade file

The scripts reside in the module under /at/workflow/webdesk/<modul><module>/<implFolder>/update/vNN/ und heißen and are named prepare.xml bzw. or upgrade.xml. Das Wurzelelement ist beliebig (üblich ist <upgrade>); die Kindelemente werden der Reihe nach abgearbeitet:

Element

Erklärung

Attribute

<sql>

The root element is arbitrary (usually <upgrade>); its child elements are processed in order:

Wichtig für die Fehlerbehandlung Important for error handling: failOnError ist standardmäßig is false. Ein fehlgeschlagener Schritt wird dann nur im Log protokolliert, und das Upgrade läuft weiter und gilt als erfolgreich.

Ergebnisse und Fehler finden

Es gibt keine eigene Maske mit einem Protokoll der Upgrade-Schritte. Die Ergebnisse stehen im Webdesk-Log (Datei webdesk.log bzw. error.log im Ordner webdesk-logs unterhalb des Cocoon-Arbeitsverzeichnisses, sowie auf der Konsole bzw. im Container-Log). Relevante Meldungen:

Meldung im Log

Bedeutung

Handlungsbedarf

by default. A failed step is then only recorded in the log, and the upgrade continues and counts as successful.

Finding results and errors

There is no separate mask with a log of the upgrade steps. The results are in the Webdesk log (file webdesk.log or error.log in the folder webdesk-logs below the Cocoon work directory, as well as on the console or in the container log). Relevant messages:

Registrierung

Was die Registrierung macht

Registration

What the registration does

The program files of a new version bring actions (act-descr.xml), Konfigurationenconfigurations, Textbausteine text modules (i18n.xml), Jobsjobs, Konnektorenconnectors, Schlüsselwerte, Hilfetexte und Menüvorlagen mit. Die Registrierung überträgt diese in die Datenbank. Ohne Registrierung bleiben die Datenbankinhalte auf dem Stand der Vorversion: neue Aktionen, Menüeinträge und Beschriftungen sind dann nicht vorhanden. Die Registrierung läuft in zwei Phasen: Phase key values, help texts and menu templates. The registration transfers them to the database. Without registration, the database contents stay at the level of the previous version: new actions, menu entries and captions are then missing.

The registration runs in two phases: phase 1 ("ESSENTIALS") registriert alles außer den Textbausteinen, Phase registers everything except the text modules, phase 2 ("LABELS (i18n)") die Textbausteine. Sie ist rechenintensiv und kann mehrere Minuten dauern.

Werte von webdesk.runRegistration

Besonderheiten:

• Ist die Datenbank noch leer (Neuinstallation), wird unabhängig von der Einstellung immer eine vollständige Registrierung im Vordergrund ausgeführt.
• Das automatische Zurücksetzen von 1 auf 0 schreibt in die Datei webdesk.properties. Gibt es diese Datei nicht (z. B. im Container), wird nichts zurückgesetzt, und der Wert 1 gilt bei jedem Start. Wird der Wert über die Umgebungsvariable WD_WEBDESK_RUNREGISTRATION gesetzt, bleibt diese maßgeblich: sie ist nach dem Update zu entfernen oder auf 0 zu setzen, sonst wird bei jedem Start vollständig registriert.
• Die Registrierung läuft standardmäßig im Hintergrund, die Anwendung ist währenddessen schon erreichbar. Anwender erst zulassen, wenn im Log REGISTRATION HAS FINISHED (bzw. REGISTRATION All Phases finished!) erscheint.
• Der INI-File-Cache (Dateien actions.ini und textmodules.ini im Unterordner inifiles des Cache-Verzeichnisses) merkt sich pro act-descr.xml und i18n.xml, wann die Datei zuletzt geändert war. Ist eine Datei nicht neuer als der gemerkte Stand, wird sie übersprungen. Wird der Cache ignoriert, werden alle Dateien neu gelesen. Der Cache gilt nur für die zugehörige Datenbank: bei geänderter Datenbankverbindung wird er verworfen.
• Kundenspezifische Änderungen werden geschützt: Ausgelieferte Konfigurationen und Textbausteine werden von der Registrierung nur überschrieben, wenn bei ihnen das Kennzeichen "Änderung bei Versionswechsel" (allowUpdateOnVersionChange) gesetzt ist. Neu angelegte Konfigurationen erhalten es nicht (sie werden danach nicht mehr überschrieben). Das Kennzeichen aller Textbausteine kann über die Aktionen "Entsperre alle Textmodule" bzw. "Sperre alle Textmodule" in "Erw. Funktionen" (siehe Erweiterte Funktionen) gesammelt gesetzt bzw. entfernt werden; "Entsperre alle Textmodule" erlaubt der Registrierung, alle ausgelieferten Textbausteine mit den Ursprungswerten zu überschreiben.

Registrierung manuell auslösen

In der Aktion "Erw. Funktionen" (Erweiterte Funktionen) lässt sich die Registrierung im laufenden Betrieb anstoßen, z. B. wenn webdesk.runRegistration auf 0 stand oder einzelne Module fehlgeschlagen sind:

the text modules. It is compute-intensive and can take several minutes.

Values of webdesk.runRegistration

Notes:

• If the database is still empty (new installation), a full registration is always run in the foreground, regardless of the setting.
• The automatic reset from 1 to 0 writes to the file webdesk.properties. If this file does not exist (e.g. in a container), nothing is reset and the value 1 applies on every startup. If the value is set through the environment variable WD_WEBDESK_RUNREGISTRATION, the variable remains authoritative: remove it after the update or set it to 0, otherwise a full registration runs on every startup.
• By default the registration runs in the background and the application is reachable in the meantime. Admit users only when REGISTRATION HAS FINISHED (or REGISTRATION All Phases finished!) appears in the log.
• The INI file cache (files actions.ini and textmodules.ini in the subfolder inifiles of the cache directory) remembers for every act-descr.xml and i18n.xml when the file was last changed. A file that is not newer than the remembered state is skipped. If the cache is ignored, all files are read again. The cache is bound to its database: if the database connection changes, it is discarded.
• Customer-specific changes are protected: shipped configurations and text modules are overwritten by the registration only if the flag "Update on version change" (allowUpdateOnVersionChange) is set on them. Newly created configurations do not get it (so they are not overwritten afterwards). The flag of all text modules can be set or removed in bulk with the actions "Unlock all Textmodules in Database" and "Lock all Textmodules in Database" in "Extended Tasks" (see Extended Tasks); "Unlock all Textmodules in Database" allows the registration to overwrite all shipped text modules with the original values.

Triggering the registration manually

In the action "Extended Tasks" (Extended Tasks), the registration can be started during operation, e.g. if webdesk.runRegistration was set to 0 or individual modules failed:

• "Registration mode": complete (everything), Everything except Textmodules, Actions and Flowscripts (ohne Jobs und Job-Konfigurationen) oder without jobs and job configurations) or Only text modules.
• "INIIgnore ini-File file cache ignorieren": nur bei selectable only for complete auswählbar; entspricht dem Verhalten bei Wert ; corresponds to the behavior with value 1.
• "Einschränkung der Registrierung aufRegister only this module:": registriert nur das gewählte Modulregisters only the selected module.
• Button "Starte RegistrierungRun Registration".
• Zusätzlich gibt es "INI In addition there are "Clear Ini-File Caches leeren" (die nächste Registrierung liest dann alle Dateien neu) und "Starte Modulupdate" (führt die Modul-Upgrades wie beim Start aus, ohne Neustart).

• the next registration then reads all files again) and "Start Update process of modules" (executes the module upgrades as at startup, without a restart).

Warning: The message "Registration successfully finished!" erscheint auch dann, wenn die Registrierung einzelner Module fehlgeschlagen ist, denn Fehler werden je Modul nur ins Log geschrieben. Der Erfolg ist daher immer im Log zu prüfen. Registrierung nicht während der Geschäftszeit ausführen.

Checkliste vor dem Update

also appears when the registration of individual modules has failed, because errors are only written to the log per module. Always verify success in the log. Do not run the registration during business hours.

Checklist before the update

• Release notes ("New Features", "Breaking Changes") der Zielversion gelesenof the target version read; Java 17 und die JVM-Parameter geprüft. Wartungsfenster vereinbart, Anwender informiert. In "Aktive and the JVM parameters checked.
• Maintenance window agreed, users informed. Check in "Active Jobs" (Aktive Active Jobs) prüfen, dass keine Jobs mehr laufen. Sicherung (Details auf der Seite that no jobs are running any more.
• Backup (details on the page "Backup, Restore und Verschlüsselungsschlüssel"):
  • Vollsicherung der Datenbanken webdesk und Full backup of the databases webdesk and shark.
  • Dateien The files webdesk.properties und and enc.key (liegen im Klassenpfad der Webanwendung, üblicherweise located on the classpath of the web application, usually WEB-INF/classes) sowie ggf. and, if applicable, tacon.properties des of the TA -Connectors. Ohne den Verschlüsselungsschlüssel lassen sich gespeicherte Zugangsdaten nicht mehr entschlüsseln.
• Bei Systemen mit Kundenanpassungen: Update zuvor an einer Kopie der Datenbanken testen.
• Die aktuellen Logdateien sichern: Die Logdateien werden laut log4j2.xml nicht angehängt, sondern beim Start der neuen Version neu begonnen.
• Bei Betrieb mit mehreren Knoten (Cluster): Vorgehen für den ersten Knoten festlegen (siehe unten).

Update mit klassischem Tomcat (WAR)

• • connector. Without the encryption key, stored credentials can no longer be decrypted.
• For systems with customer-specific adaptations: test the update beforehand on a copy of the databases.
• Save the current log files: according to log4j2.xml, log files are not appended to but started anew when the new version starts.
• For operation with several nodes (cluster): decide on the procedure for the first node (see below).

Update with a classic Tomcat (WAR)

1. Complete all preparations of the checklist, log users off.
2. Stop Tomcat or the Webdesk service.
3. Perform the backup (databases, webdesk.properties, enc.key, Logslogs).
4. In der Set webdesk.properties den Wert webdesk.runRegistration = 1 setzen. Hintergrund: Nach dem ersten Start steht der Wert auf 0, die Registrierung würde sonst ausbleiben und neue Aktionen, Menüeinträge und Beschriftungen wären nicht vorhanden. Die Modul-Upgrade-Skripte laufen unabhängig davon immer. Die alte Webanwendung (entpackter Ordner) entfernen und das neue WAR bereitstellen bzw. entpacken. Die gesicherte webdesk.properties und enc.key müssen anschließend wieder im Klassenpfad in webdesk.properties. Reason: after the first start the value is 0, so the registration would otherwise be skipped and new actions, menu entries and captions would be missing. The module upgrade scripts run independently of this setting, always.
5. Remove the old web application (unpacked folder) and deploy or unpack the new WAR. The saved webdesk.properties and enc.key must afterwards be back on the classpath (WEB-INF/classes) der neuen Webanwendung liegen, ebenso weitere dort abgelegte kundenspezifische Dateien. Tomcat starten und das Webdesk-Log beobachten, bis der Start beendet und die Registrierung abgeschlossen ist (Meldungen of the new web application, as must any other customer-specific files stored there.
6. Start Tomcat and watch the Webdesk log until startup has finished and the registration is complete (messages WebdeskStartup PoStartupImpl.start() finished after ... und and REGISTRATION HAS FINISHED AFTER ...; diese Meldung kommt je Phase).
7. Prüfung nach dem Update durchführen (siehe unten).

Update mit Container-Image

1. Das neue Image enthält keine webdesk.properties. Die Konfiguration und der Schlüssel the latter appears once per phase).
2. Carry out the post-update verification (see below).

Update with a container image

1. The new image does not contain a webdesk.properties. Configuration and key (webdesk.properties, enc.key) müssen wie bisher bereitgestellt werden. Folgende Einstellungen können alternativ über Umgebungsvariablen der Form WD_<EIGENSCHAFT> gesetzt werden (Punkte werden zu Unterstrichen, Großschreibung, z. Bmust be provided as before. Alternatively, the following settings can be set through environment variables of the form WD_<PROPERTY> (dots become underscores, upper case; e.g. webdesk.connection.url wird zu becomes WD_WEBDESK_CONNECTION_URL): Datenbankverbindungen database connections (webdesk.connection.*, shark.connection.*, webdesk.dialect), webdesk.ta.if6020impl.rmi, Cluster-Einstellungencluster settings, webdesk.runRegistration, webdesk.disableTimeLineChecks und einige weitere.
2. Datenbanken sichern, bisherige Container beenden.
3. Registrierung festlegen, entweder (empfohlen für automatisierte Abläufe) einen einmaligen Update-Container mit and a few more.
4. Back up the databases, stop the existing containers.
5. Decide on the registration, either
   • (recommended for automated procedures) start a one-off update container with webdesk.runRegistration = 4 starten. Er führt Schemaupdate, Modul-Upgrades und die vollständige Registrierung aus und beendet sich danach selbst. Erst danach die regulären Container mit Wert 0 starten; oder
   • die regulären Container mit Wert 1 starten.
6. Bei mehreren Knoten, die dieselbe Datenbank verwenden, zuerst nur einen Knoten starten und dessen vollständigen Start abwarten, bevor weitere gestartet werden. Hintergrund: Die Upgrade-Schritte werden beim Start jedes Knotens ausgeführt.
7. Umgebungsvariable WD_WEBDESK_RUNREGISTRATION nach dem Update entfernen bzw. auf 0 setzen (siehe oben).
8. Prüfung nach dem Update durchführen.

1. • . It performs the schema update, module upgrades and the full registration, and then terminates itself. Only then start the regular containers with value 0; or
   • start the regular containers with value 1.
2. With several nodes using the same database, start only one node first and wait for its complete startup before starting further ones. Reason: the upgrade steps are executed when each node starts.
3. Remove the environment variable WD_WEBDESK_RUNREGISTRATION after the update or set it to 0 (see above).
4. Carry out the post-update verification.

Note: The web application image contains Tomcat 9 and the session storage through Redis (context.xml). Der Redis-Dienst muss für den neuen Container erreichbar sein.

Prüfung nach dem Update

The Redis service must be reachable for the new container.

Verification after the update

1. Log: There are no messages Couldn't upgrade module, Registration of ... module failed oder or Action Registration failed!. Meldungen Messages Upgrade script couldn't be executed normally! wurden geprüft. Anmeldung: Anmelden als Administrator ist möglich; die Aktion have been reviewed.
2. Login: Logging in as administrator is possible; the action "Versions-Popup" zeigt Version, Revision und Build-Zeitpunkt der neuen Programmversion. Module: In der Aktion "Module" sind alle erwarteten Module vorhanden, die Spalte "deaktiviert" steht bei den lizenzierten Modulen auf false. Nach einem weiteren Neustart zeigt das Log für alle Module shows version, revision and build time of the new program version.
3. Modules: In the action "Modules" all expected modules are present and the column "detached" is false for the licensed modules. After another restart, the log shows is up-to-date for all modules, di. h. alle Upgrade-Schritte sind abgeschlossene. all upgrade steps are complete.
4. Jobs: In "Aktive Active Jobs" sind die erwarteten Jobs geplant und laufen. Falls nicht, in "Erw. Funktionen" die Aktion "Neuinitialisierung JobService" ausführen.
5. Caches: Die Registrierung leert die Caches der Aktionen und Zugriffsrechte selbst. Werden Berechtigungen trotzdem nicht wirksam, in "Erw. Funktionen" "Berechtigungs Cache leeren" ausführen; bei geänderten Flowscripts "Flowscripts neu laden".
6. Registrierung: webdesk.runRegistration steht wieder auf 0 (Betrieb nicht dauerhaft mit 2, 3 oder 4).
7. Fachliche Stichproben: Zentrale Abläufe (Zeiterfassung, Workflows, Reports, Schnittstellen und kundenspezifische Skripte) testen. Bei IF6020 den TA-Connector und tacon.properties gemäß den Hinweisen der Zielversion prüfen.

Wenn ein Upgrade-Schritt fehlschlägt

Was der Code im Fehlerfall tut:

1. the expected jobs are scheduled and running. If not, run the action "Reinitialization of JobService" in "Extended Tasks".
2. Caches: The registration clears the caches of actions and access rights itself. If permissions still do not take effect, run "Clear Permission Cache" in "Extended Tasks"; for changed flowscripts "Refresh all flowscripts".
3. Registration: webdesk.runRegistration is back at 0 (do not leave operation permanently at 2, 3 or 4).
4. Functional spot checks: Test central processes (time recording, workflows, reports, interfaces and customer-specific scripts). For IF6020, check the TA connector and tacon.properties according to the notes of the target version.

If an upgrade step fails

What the code does in case of an error:

• If an upgrade.xml or prepare.xml aborts (message Couldn't upgrade module ...), startet Webdesk nicht. Die weiteren Module werden dann nicht mehr verarbeitet.
• Die Versionsnummer des betroffenen Moduls bleibt auf der letzten vollständig abgeschlossenen Version stehen. Beim nächsten Start setzt Webdesk bei der fehlgeschlagenen Version wieder an. Dabei laufen auch die bereits ausgeführten Schritte dieser Version und alle prepare.xml der anstehenden Versionen erneut.
• Es gibt keine automatische Rücknahme (Rollback) der bereits ausgeführten Schritte.

Vorgehen:

• does not start. The remaining modules are then not processed.
• The version number of the affected module stays at the last fully completed version. At the next start Webdesk resumes at the failed version. In doing so, the steps of that version that were already executed and all prepare.xml files of the pending versions run again.
• There is no automatic rollback of the steps already executed.

Procedure:

1. Save the log files (they are overwritten at the next start) and look for the cause in the log: message Couldn't upgrade module ... mit der zugehörigen Fehlerursache.
2. Ursache beheben (z. B. fehlende Datenbankrechte für DDL-Anweisungen) und Webdesk erneut starten. Alternativ in "Erw. Funktionen" die Aktion "Starte Modulupdate" ausführen; Fehler werden dort in der Maske ausgegeben.
3. Lässt sich die Ursache nicht beheben, die Sicherung einspielen (siehe nächster Abschnitt) und den Support kontaktieren. Datenbank nicht manuell nacharbeiten, solange unklar ist, welche Schritte bereits gelaufen sind.

Rückweg (Rollback)

Achtung: Webdesk 4 führt keine Downgrade-Skripte aus. Die readme.txt im Update-Ordner des Moduls erwähnt zwar eine optionale downgrade.xml, im Programm wird eine solche Datei aber nirgends ausgeführt (und im Repository existiert keine). Wird eine ältere Programmversion gegen eine bereits aktualisierte Datenbank gestartet, werden keine Schritte rückgängig gemacht, und das Hibernate-Schemaupdate entfernt keine Spalten; Webdesk setzt lediglich die gespeicherten Modulversionen auf die niedrigeren Werte. Der Rückweg ist deshalb das Einspielen der Sicherung (Datenbanken webdesk und shark sowie webdesk.properties und enc.key) gemeinsam mit der alten Programmversion.

Registrierung fehlgeschlagen

1. with the associated error cause.
2. Fix the cause (e.g. missing database permissions for DDL statements) and restart Webdesk. Alternatively, run the action "Start Update process of modules" in "Extended Tasks"; errors are displayed in the mask there.
3. If the cause cannot be fixed, restore the backup (see next section) and contact support. Do not rework the database manually as long as it is unclear which steps have already run.

Rolling back

Warning: Webdesk 4 does not execute downgrade scripts. The readme.txt in the module's update folder does mention an optional downgrade.xml, but no such file is executed anywhere in the program (and none exists in the repository). If an older program version is started against an already updated database, no steps are reversed and the Hibernate schema update does not remove any columns; Webdesk merely sets the stored module versions to the lower values. The way back is therefore to restore the backup (databases webdesk and shark as well as webdesk.properties and enc.key) together with the old program version.

Registration failed

Errors during the registration of a module are reported in the log (Registration of ... module failed), but Webdesk läuft jedoch weiter. Nach Beheben der Ursache die Registrierung in "Erw. Funktionen" erneut auslösen, bei Bedarf eingeschränkt auf das betroffene Modul und mit "INI-File cache ignorierenkeeps running. After fixing the cause, trigger the registration again in "Extended Tasks", if necessary restricted to the affected module and with "Ignore ini-file cache".