SuperX - Benutzerbeiträge [de]

Kernmodul Regelbetrieb

2026-06-15T13:02:19Z

Andrek: /* Migration auf die Webapp-Struktur */

Kernmodul Regelbetrieb

2026-06-12T08:37:26Z

Andrek: /* Ziel */

=BI Maintenance=
[[image:logobutton_maintenance2b.png|200px]]

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

=Migration auf die Webapp-Struktur=

==Ziel==
Mit dem Skript <code>migrate_superx_webapp.sh</code> kann eine bestehende SuperX-Installation automatisch auf die neue Verzeichnisstruktur migriert werden.

Die Migration unterstützt zwei Anwendungsfälle:

* vollständige Migration der Webapp inklusive DB-Verzeichnis
* Migration nur des DB-Verzeichnisses in eine bereits vorhandene Webapp

Die bisherige SuperX-Struktur:

<source lang="text">
/home/superx/db
/home/superx/webserver/tomcat/webapps/superx
</source>

kann damit in folgende Zielstruktur überführt werden:

<source lang="text">
<WEBAPP>
└── WEB-INF
└── conf
└── edustore
└── db
</source>

Beispiel:

<source lang="text">
/var/lib/tomcat10/webapps/superx
└── WEB-INF
└── conf
└── edustore
└── db
</source>

==Dateien==
Das Migrationsskript besteht aus zwei Dateien:

<source lang="text">
migrate_superx.conf
migrate_superx_webapp.sh
</source>

Beide Dateien müssen im selben Verzeichnis liegen.

Das Skript lädt die Konfigurationsdatei automatisch aus dem eigenen Skriptverzeichnis. Ein Pfad zur Konfigurationsdatei muss beim Aufruf nicht angegeben werden.

Aufruf:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

Für Produktivmigrationen mit Rechteanpassung wird in der Regel root benötigt:

<source lang="bash">
sudo ./migrate_superx_webapp.sh
</source>

==Grundlegende Konfiguration==

===Vorhandene SQL_ENV===
Die bestehende Installation wird über die vorhandene <code>SQL_ENV</code> ermittelt.

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"
</source>

Aus dieser Datei liest das Skript insbesondere:

<source lang="bash">
SUPERX_DIR
WEBAPP
</source>

Diese Werte werden als Quellpfade für die Migration verwendet.

==Migrationsmodus==

Die Variable <code>MIGRATION_MODE</code> steuert, ob die komplette Webapp oder nur das DB-Verzeichnis migriert wird.

<source lang="bash">
MIGRATION_MODE="full"
</source>

Erlaubte Werte:

<source lang="bash">
full
db_only
</source>

===MIGRATION_MODE=full===

Bei <code>full</code> wird die bestehende Webapp in ein neues Ziel-Webapp-Verzeichnis kopiert.

Zusätzlich wird das DB-Verzeichnis nach:

<source lang="text">
<TARGET_WEBAPP>/WEB-INF/conf/edustore/db
</source>

kopiert oder verschoben.

Dieser Modus ist für eine vollständige Migration auf einen neuen Tomcat-Webapp-Pfad vorgesehen.

Beispiel:

<source lang="bash">
MIGRATION_MODE="full"
TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"
DB_TRANSFER_MODE="copy"
</source>

Ablauf:

# bestehende Webapp wird nach <code>TARGET_WEBAPP</code> kopiert
# bestehendes DB-Verzeichnis wird nach <code>TARGET_WEBAPP/WEB-INF/conf/edustore/db</code> kopiert oder verschoben
# die neue <code>SQL_ENV</code> im Ziel wird angepasst

===MIGRATION_MODE=db_only===

Bei <code>db_only</code> wird keine Webapp kopiert.

Es wird nur das DB-Verzeichnis in die bereits vorhandene Webapp-Struktur übernommen.

Dieser Modus ist sinnvoll, wenn die Webapp bereits an der gewünschten Stelle liegt und nur noch das bisher externe DB-Verzeichnis in die neue Zielstruktur übernommen werden soll.

Beispiel:

<source lang="bash">
MIGRATION_MODE="db_only"
TARGET_WEBAPP="auto"
DB_TRANSFER_MODE="move"
</source>

Bei <code>TARGET_WEBAPP="auto"</code> verwendet das Skript automatisch den bestehenden Wert von <code>WEBAPP</code> aus der geladenen <code>SQL_ENV</code>.

Das DB-Verzeichnis wird dann nach:

<source lang="text">
$WEBAPP/WEB-INF/conf/edustore/db
</source>

kopiert oder verschoben.

==Übertragung des DB-Verzeichnisses==

Die Variable <code>DB_TRANSFER_MODE</code> steuert, ob das DB-Verzeichnis kopiert oder verschoben wird.

<source lang="bash">
DB_TRANSFER_MODE="copy"
</source>

Erlaubte Werte:

<source lang="bash">
copy
move
</source>

===DB_TRANSFER_MODE=copy===

Bei <code>copy</code> wird das DB-Verzeichnis per <code>rsync</code> kopiert.

<source lang="bash">
DB_TRANSFER_MODE="copy"
</source>

Die Quelle bleibt erhalten.

Das ist die sicherere Variante und eignet sich besonders für Produktivmigrationen, bei denen die alte Installation zunächst unverändert erhalten bleiben soll.

===DB_TRANSFER_MODE=move===

Bei <code>move</code> wird das DB-Verzeichnis per <code>mv</code> verschoben.

<source lang="bash">
DB_TRANSFER_MODE="move"
</source>

Die Quelle liegt danach nicht mehr am alten Ort.

Diese Variante kann sinnvoll sein, wenn das DB-Verzeichnis sehr groß ist, z. B. durch:

* unload-Dateien
* Exportdateien
* temporäre Arbeitsdateien
* lokale Sicherungen

Da beim Verschieben kein doppelter Speicherplatz benötigt wird, kann <code>move</code> bei knappen Plattenplatzverhältnissen sinnvoll sein.

Aus Sicherheitsgründen darf das Zielverzeichnis bei <code>move</code> noch nicht existieren. Das Skript bricht sonst ab, um unerwünschte Verschachtelungen wie <code>db/db</code> zu vermeiden.

==Ziel-Webapp==

Die Ziel-Webapp wird über <code>TARGET_WEBAPP</code> festgelegt.

<source lang="bash">
TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"
</source>

Bei <code>MIGRATION_MODE=full</code> muss hier ein konkreter Zielpfad eingetragen werden.

Bei <code>MIGRATION_MODE=db_only</code> kann stattdessen <code>auto</code> verwendet werden:

<source lang="bash">
TARGET_WEBAPP="auto"
</source>

Dann verwendet das Skript den bestehenden Wert von <code>WEBAPP</code> aus der alten <code>SQL_ENV</code>.

==Bestehende Zielverzeichnisse==

===ALLOW_EXISTING_TARGET===

Diese Variable steuert, ob eine bereits vorhandene Ziel-Webapp ergänzt werden darf.

<source lang="bash">
ALLOW_EXISTING_TARGET="true"
</source>

Bei <code>MIGRATION_MODE=full</code> kann damit erlaubt werden, dass eine vorhandene Ziel-Webapp per <code>rsync</code> ergänzt oder aktualisiert wird.

===ALLOW_EXISTING_TARGET_DB===

Diese Variable steuert, ob ein bereits vorhandenes Ziel-DB-Verzeichnis bei <code>DB_TRANSFER_MODE=copy</code> ergänzt werden darf.

<source lang="bash">
ALLOW_EXISTING_TARGET_DB="true"
</source>

Bei <code>DB_TRANSFER_MODE=copy</code> kann das Ziel per <code>rsync</code> ergänzt werden.

Bei <code>DB_TRANSFER_MODE=move</code> wird diese Einstellung ignoriert. In diesem Fall darf das Ziel-DB-Verzeichnis nicht existieren.

==SQL_ENV-Anpassung==

Nach der Migration wird die <code>SQL_ENV</code> im Ziel-DB-Verzeichnis angepasst.

Ziel:

<source lang="bash">
WEBAPP=<TARGET_WEBAPP>
SUPERX_DIR=<TARGET_WEBAPP>/WEB-INF/conf/edustore
umask 002
</source>

Beispiel:

<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
SUPERX_DIR=/var/lib/tomcat10/webapps/superx/WEB-INF/conf/edustore
umask 002
</source>

Vor der Änderung wird automatisch eine Sicherung der Ziel-<code>SQL_ENV</code> angelegt.

Die Anpassung kann über folgende Variable gesteuert werden:

<source lang="bash">
UPDATE_SQL_ENV="true"
</source>

==Automatische Rechtebehandlung==

Die Rechtebehandlung wird über folgende Variablen gesteuert:

<source lang="bash">
SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

Das Skript entscheidet automatisch, ob ein <code>chown</code> erforderlich ist:

* Wird das Skript als <code>root</code> ausgeführt, werden Besitzer und Gruppe gemäß <code>TOMCAT_USER</code> und <code>SUPERX_GROUP</code> gesetzt.
* Wird das Skript als derselbe Benutzer ausgeführt, der auch als <code>TOMCAT_USER</code> konfiguriert wurde und ist dieser Benutzer Mitglied der angegebenen Gruppe, wird auf das <code>chown</code> automatisch verzichtet.
* Ist eine Änderung des Besitzers erforderlich, das Skript läuft jedoch nicht als <code>root</code>, wird mit einer Fehlermeldung abgebrochen.

Beispiel Produktivsystem:

<source lang="bash">
TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"
SET_OWNER="auto"
</source>

Beispiel Testsystem ohne root:

<source lang="bash">
TOMCAT_USER="superx"
SUPERX_GROUP="superx"
SET_OWNER="auto"
</source>

===SET_OWNER=true===

<source lang="bash">
SET_OWNER="true"
</source>

Der Besitzer wird immer auf den konfigurierten Benutzer und die konfigurierte Gruppe gesetzt:

<source lang="bash">
chown -R $TOMCAT_USER:$SUPERX_GROUP ...
</source>

Dafür werden normalerweise root-Rechte benötigt.

===SET_OWNER=false===

<source lang="bash">
SET_OWNER="false"
</source>

Es wird kein <code>chown</code> ausgeführt.

Die vorhandenen Besitzer- und Gruppeninformationen bleiben unverändert.

===SET_CHMOD===

Mit <code>SET_CHMOD</code> wird gesteuert, ob Dateirechte gesetzt werden.

<source lang="bash">
SET_CHMOD="true"
</source>

Dabei werden u. a.:

* Verzeichnisse auf <code>2775</code> gesetzt
* Dateien auf <code>664</code> gesetzt
* Dateien unter <code>db/bin</code> ausführbar gesetzt
* Dateien mit Endung <code>.x</code> und <code>.sh</code> ausführbar gesetzt

Das gesetzte setgid-Bit auf Verzeichnissen sorgt dafür, dass neu angelegte Dateien und Verzeichnisse die Gruppe des übergeordneten Verzeichnisses erben.

==Tomcat-Gruppe==

Wenn mit Gruppenrechten gearbeitet wird, muss der Tomcat-Benutzer Mitglied der verwendeten Gruppe sein.

Beispiel:

<source lang="bash">
usermod -aG superx tomcat
</source>

Im Skript kann diese Zuordnung automatisch erfolgen:

<source lang="bash">
ADD_TOMCAT_TO_GROUP="true"
</source>

Falls die Gruppenmitgliedschaft neu gesetzt wurde, muss Tomcat anschließend neu gestartet werden, damit die neue Gruppenzugehörigkeit im laufenden Prozess wirksam wird.

==Sicherheitsprüfung bereits migrierter Installationen==

Um versehentliche Mehrfachmigrationen zu vermeiden, prüft das Skript standardmäßig, ob die Quelle bereits nach einer migrierten Webapp-Struktur aussieht.

Beispiel:

<source lang="bash">
SUPERX_DIR=/home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
</source>

Hier liegt <code>SUPERX_DIR</code> bereits innerhalb von <code>WEBAPP</code>.

In diesem Fall bricht das Skript standardmäßig ab.

Die Prüfung kann im Notfall übersteuert werden:

<source lang="bash">
FORCE_ALREADY_MIGRATED="true"
</source>

Standardwert:

<source lang="bash">
FORCE_ALREADY_MIGRATED="false"
</source>

Diese Option sollte nur verwendet werden, wenn die Auswirkungen bekannt sind. Andernfalls besteht die Gefahr, dass bereits migrierte Strukturen erneut kopiert oder ungewollt verschachtelt werden.

==Dry-Run==

Vor einer Produktivmigration empfiehlt sich ein Testlauf:

<source lang="bash">
DRY_RUN="true"
</source>

Danach:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

Es werden die geplanten Aktionen angezeigt, ohne Änderungen durchzuführen.

==Beispiele==

===Vollständige Migration mit Kopie des DB-Verzeichnisses===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="full"
DB_TRANSFER_MODE="copy"

TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"

TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

Aufruf:

<source lang="bash">
sudo ./migrate_superx_webapp.sh
</source>

===Vollständige Migration mit Verschieben des DB-Verzeichnisses===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="full"
DB_TRANSFER_MODE="move"

TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"

TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

In diesem Fall wird die Webapp kopiert, das DB-Verzeichnis jedoch verschoben.

===Nur DB-Verzeichnis in bestehende Webapp übernehmen===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"
TARGET_WEBAPP="auto"

SET_RIGHTS="false"
UPDATE_SQL_ENV="true"
</source>

Aufruf:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

In diesem Fall wird keine Webapp kopiert. Das DB-Verzeichnis wird in die bestehende Webapp unter <code>WEB-INF/conf/edustore/db</code> verschoben.

===Testmigration ohne root===

<source lang="bash">
SQL_ENV="/home/superx/test/db/bin/SQL_ENV"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="copy"
TARGET_WEBAPP="auto"

TOMCAT_USER="superx"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"

ADD_TOMCAT_TO_GROUP="false"
</source>

Wird das Skript als Benutzer <code>superx</code> ausgeführt, kann diese Migration ohne root-Rechte laufen.

==Ablauf der Migration==

Das Skript führt je nach Modus folgende Schritte aus:

# Laden von <code>migrate_superx.conf</code>
# Laden der bestehenden <code>SQL_ENV</code>
# Ermitteln von <code>SUPERX_DIR</code>, <code>WEBAPP</code> und dem bisherigen DB-Verzeichnis
# Sicherheitsprüfung, ob die Quelle bereits migriert aussieht
# Ermitteln der Zielstruktur
# Optional: Tomcat stoppen
# Bei <code>MIGRATION_MODE=full</code>: Webapp kopieren
# DB-Verzeichnis je nach <code>DB_TRANSFER_MODE</code> kopieren oder verschieben
# Backup der Ziel-<code>SQL_ENV</code>
# Anpassung von <code>WEBAPP</code>, <code>SUPERX_DIR</code> und <code>umask</code>
# Optional: Rechte setzen
# Optional: Tomcat starten

==Hinweise==

* Die Webapp wird vom Skript nie verschoben, sondern bei <code>MIGRATION_MODE=full</code> kopiert.
* Das DB-Verzeichnis kann wahlweise kopiert oder verschoben werden.
* Bei <code>DB_TRANSFER_MODE=move</code> ist die alte DB-Quelle nach der Migration nicht mehr vorhanden.
* Bei <code>DB_TRANSFER_MODE=move</code> darf das Ziel-DB-Verzeichnis nicht existieren.
* Für <code>copy</code> wird <code>rsync</code> verwendet.
* Die interne Zielstruktur ist fest vorgegeben: <code>WEB-INF/conf/edustore/db</code>.
* Für Produktivmigrationen ist ein vorheriger Dry-Run empfehlenswert.
* Bei Rechteänderungen auf andere Benutzer oder Gruppen sind root-Rechte erforderlich.

Kernmodul Regelbetrieb

2026-06-12T08:05:10Z

Andrek: /* Ziel */

=BI Maintenance=
[[image:logobutton_maintenance2b.png|200px]]

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

=Migration auf die Webapp-Struktur=

==Ziel==
Mit dem Skript <code>migrate_superx_webapp.sh</code> kann eine bestehende SuperX-Installation automatisch auf die neue Verzeichnisstruktur migriert werden.

Die Migration unterstützt zwei Anwendungsfälle:

* vollständige Migration der Webapp inklusive DB-Verzeichnis
* Migration nur des DB-Verzeichnisses in eine bereits vorhandene Webapp

Die bisherige SuperX-Struktur:

<source lang="text">
/home/superx/db
/home/superx/webserver/tomcat/webapps/superx
</source>

kann damit in folgende Zielstruktur überführt werden:

<source lang="text">
<WEBAPP>
└── WEB-INF
└── conf
└── edustore
└── db
</source>

Beispiel:

<source lang="text">
/var/lib/tomcat10/webapps/superx
└── WEB-INF
└── conf
└── edustore
└── db
</source>

Test

==Dateien==
Das Migrationsskript besteht aus zwei Dateien:

<source lang="text">
migrate_superx.conf
migrate_superx_webapp.sh
</source>

Beide Dateien müssen im selben Verzeichnis liegen.

Das Skript lädt die Konfigurationsdatei automatisch aus dem eigenen Skriptverzeichnis. Ein Pfad zur Konfigurationsdatei muss beim Aufruf nicht angegeben werden.

Aufruf:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

Für Produktivmigrationen mit Rechteanpassung wird in der Regel root benötigt:

<source lang="bash">
sudo ./migrate_superx_webapp.sh
</source>

==Grundlegende Konfiguration==

===Vorhandene SQL_ENV===
Die bestehende Installation wird über die vorhandene <code>SQL_ENV</code> ermittelt.

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"
</source>

Aus dieser Datei liest das Skript insbesondere:

<source lang="bash">
SUPERX_DIR
WEBAPP
</source>

Diese Werte werden als Quellpfade für die Migration verwendet.

==Migrationsmodus==

Die Variable <code>MIGRATION_MODE</code> steuert, ob die komplette Webapp oder nur das DB-Verzeichnis migriert wird.

<source lang="bash">
MIGRATION_MODE="full"
</source>

Erlaubte Werte:

<source lang="bash">
full
db_only
</source>

===MIGRATION_MODE=full===

Bei <code>full</code> wird die bestehende Webapp in ein neues Ziel-Webapp-Verzeichnis kopiert.

Zusätzlich wird das DB-Verzeichnis nach:

<source lang="text">
<TARGET_WEBAPP>/WEB-INF/conf/edustore/db
</source>

kopiert oder verschoben.

Dieser Modus ist für eine vollständige Migration auf einen neuen Tomcat-Webapp-Pfad vorgesehen.

Beispiel:

<source lang="bash">
MIGRATION_MODE="full"
TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"
DB_TRANSFER_MODE="copy"
</source>

Ablauf:

# bestehende Webapp wird nach <code>TARGET_WEBAPP</code> kopiert
# bestehendes DB-Verzeichnis wird nach <code>TARGET_WEBAPP/WEB-INF/conf/edustore/db</code> kopiert oder verschoben
# die neue <code>SQL_ENV</code> im Ziel wird angepasst

===MIGRATION_MODE=db_only===

Bei <code>db_only</code> wird keine Webapp kopiert.

Es wird nur das DB-Verzeichnis in die bereits vorhandene Webapp-Struktur übernommen.

Dieser Modus ist sinnvoll, wenn die Webapp bereits an der gewünschten Stelle liegt und nur noch das bisher externe DB-Verzeichnis in die neue Zielstruktur übernommen werden soll.

Beispiel:

<source lang="bash">
MIGRATION_MODE="db_only"
TARGET_WEBAPP="auto"
DB_TRANSFER_MODE="move"
</source>

Bei <code>TARGET_WEBAPP="auto"</code> verwendet das Skript automatisch den bestehenden Wert von <code>WEBAPP</code> aus der geladenen <code>SQL_ENV</code>.

Das DB-Verzeichnis wird dann nach:

<source lang="text">
$WEBAPP/WEB-INF/conf/edustore/db
</source>

kopiert oder verschoben.

==Übertragung des DB-Verzeichnisses==

Die Variable <code>DB_TRANSFER_MODE</code> steuert, ob das DB-Verzeichnis kopiert oder verschoben wird.

<source lang="bash">
DB_TRANSFER_MODE="copy"
</source>

Erlaubte Werte:

<source lang="bash">
copy
move
</source>

===DB_TRANSFER_MODE=copy===

Bei <code>copy</code> wird das DB-Verzeichnis per <code>rsync</code> kopiert.

<source lang="bash">
DB_TRANSFER_MODE="copy"
</source>

Die Quelle bleibt erhalten.

Das ist die sicherere Variante und eignet sich besonders für Produktivmigrationen, bei denen die alte Installation zunächst unverändert erhalten bleiben soll.

===DB_TRANSFER_MODE=move===

Bei <code>move</code> wird das DB-Verzeichnis per <code>mv</code> verschoben.

<source lang="bash">
DB_TRANSFER_MODE="move"
</source>

Die Quelle liegt danach nicht mehr am alten Ort.

Diese Variante kann sinnvoll sein, wenn das DB-Verzeichnis sehr groß ist, z. B. durch:

* unload-Dateien
* Exportdateien
* temporäre Arbeitsdateien
* lokale Sicherungen

Da beim Verschieben kein doppelter Speicherplatz benötigt wird, kann <code>move</code> bei knappen Plattenplatzverhältnissen sinnvoll sein.

Aus Sicherheitsgründen darf das Zielverzeichnis bei <code>move</code> noch nicht existieren. Das Skript bricht sonst ab, um unerwünschte Verschachtelungen wie <code>db/db</code> zu vermeiden.

==Ziel-Webapp==

Die Ziel-Webapp wird über <code>TARGET_WEBAPP</code> festgelegt.

<source lang="bash">
TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"
</source>

Bei <code>MIGRATION_MODE=full</code> muss hier ein konkreter Zielpfad eingetragen werden.

Bei <code>MIGRATION_MODE=db_only</code> kann stattdessen <code>auto</code> verwendet werden:

<source lang="bash">
TARGET_WEBAPP="auto"
</source>

Dann verwendet das Skript den bestehenden Wert von <code>WEBAPP</code> aus der alten <code>SQL_ENV</code>.

==Bestehende Zielverzeichnisse==

===ALLOW_EXISTING_TARGET===

Diese Variable steuert, ob eine bereits vorhandene Ziel-Webapp ergänzt werden darf.

<source lang="bash">
ALLOW_EXISTING_TARGET="true"
</source>

Bei <code>MIGRATION_MODE=full</code> kann damit erlaubt werden, dass eine vorhandene Ziel-Webapp per <code>rsync</code> ergänzt oder aktualisiert wird.

===ALLOW_EXISTING_TARGET_DB===

Diese Variable steuert, ob ein bereits vorhandenes Ziel-DB-Verzeichnis bei <code>DB_TRANSFER_MODE=copy</code> ergänzt werden darf.

<source lang="bash">
ALLOW_EXISTING_TARGET_DB="true"
</source>

Bei <code>DB_TRANSFER_MODE=copy</code> kann das Ziel per <code>rsync</code> ergänzt werden.

Bei <code>DB_TRANSFER_MODE=move</code> wird diese Einstellung ignoriert. In diesem Fall darf das Ziel-DB-Verzeichnis nicht existieren.

==SQL_ENV-Anpassung==

Nach der Migration wird die <code>SQL_ENV</code> im Ziel-DB-Verzeichnis angepasst.

Ziel:

<source lang="bash">
WEBAPP=<TARGET_WEBAPP>
SUPERX_DIR=<TARGET_WEBAPP>/WEB-INF/conf/edustore
umask 002
</source>

Beispiel:

<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
SUPERX_DIR=/var/lib/tomcat10/webapps/superx/WEB-INF/conf/edustore
umask 002
</source>

Vor der Änderung wird automatisch eine Sicherung der Ziel-<code>SQL_ENV</code> angelegt.

Die Anpassung kann über folgende Variable gesteuert werden:

<source lang="bash">
UPDATE_SQL_ENV="true"
</source>

==Automatische Rechtebehandlung==

Die Rechtebehandlung wird über folgende Variablen gesteuert:

<source lang="bash">
SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

Das Skript entscheidet automatisch, ob ein <code>chown</code> erforderlich ist:

* Wird das Skript als <code>root</code> ausgeführt, werden Besitzer und Gruppe gemäß <code>TOMCAT_USER</code> und <code>SUPERX_GROUP</code> gesetzt.
* Wird das Skript als derselbe Benutzer ausgeführt, der auch als <code>TOMCAT_USER</code> konfiguriert wurde und ist dieser Benutzer Mitglied der angegebenen Gruppe, wird auf das <code>chown</code> automatisch verzichtet.
* Ist eine Änderung des Besitzers erforderlich, das Skript läuft jedoch nicht als <code>root</code>, wird mit einer Fehlermeldung abgebrochen.

Beispiel Produktivsystem:

<source lang="bash">
TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"
SET_OWNER="auto"
</source>

Beispiel Testsystem ohne root:

<source lang="bash">
TOMCAT_USER="superx"
SUPERX_GROUP="superx"
SET_OWNER="auto"
</source>

===SET_OWNER=true===

<source lang="bash">
SET_OWNER="true"
</source>

Der Besitzer wird immer auf den konfigurierten Benutzer und die konfigurierte Gruppe gesetzt:

<source lang="bash">
chown -R $TOMCAT_USER:$SUPERX_GROUP ...
</source>

Dafür werden normalerweise root-Rechte benötigt.

===SET_OWNER=false===

<source lang="bash">
SET_OWNER="false"
</source>

Es wird kein <code>chown</code> ausgeführt.

Die vorhandenen Besitzer- und Gruppeninformationen bleiben unverändert.

===SET_CHMOD===

Mit <code>SET_CHMOD</code> wird gesteuert, ob Dateirechte gesetzt werden.

<source lang="bash">
SET_CHMOD="true"
</source>

Dabei werden u. a.:

* Verzeichnisse auf <code>2775</code> gesetzt
* Dateien auf <code>664</code> gesetzt
* Dateien unter <code>db/bin</code> ausführbar gesetzt
* Dateien mit Endung <code>.x</code> und <code>.sh</code> ausführbar gesetzt

Das gesetzte setgid-Bit auf Verzeichnissen sorgt dafür, dass neu angelegte Dateien und Verzeichnisse die Gruppe des übergeordneten Verzeichnisses erben.

==Tomcat-Gruppe==

Wenn mit Gruppenrechten gearbeitet wird, muss der Tomcat-Benutzer Mitglied der verwendeten Gruppe sein.

Beispiel:

<source lang="bash">
usermod -aG superx tomcat
</source>

Im Skript kann diese Zuordnung automatisch erfolgen:

<source lang="bash">
ADD_TOMCAT_TO_GROUP="true"
</source>

Falls die Gruppenmitgliedschaft neu gesetzt wurde, muss Tomcat anschließend neu gestartet werden, damit die neue Gruppenzugehörigkeit im laufenden Prozess wirksam wird.

==Sicherheitsprüfung bereits migrierter Installationen==

Um versehentliche Mehrfachmigrationen zu vermeiden, prüft das Skript standardmäßig, ob die Quelle bereits nach einer migrierten Webapp-Struktur aussieht.

Beispiel:

<source lang="bash">
SUPERX_DIR=/home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
</source>

Hier liegt <code>SUPERX_DIR</code> bereits innerhalb von <code>WEBAPP</code>.

In diesem Fall bricht das Skript standardmäßig ab.

Die Prüfung kann im Notfall übersteuert werden:

<source lang="bash">
FORCE_ALREADY_MIGRATED="true"
</source>

Standardwert:

<source lang="bash">
FORCE_ALREADY_MIGRATED="false"
</source>

Diese Option sollte nur verwendet werden, wenn die Auswirkungen bekannt sind. Andernfalls besteht die Gefahr, dass bereits migrierte Strukturen erneut kopiert oder ungewollt verschachtelt werden.

==Dry-Run==

Vor einer Produktivmigration empfiehlt sich ein Testlauf:

<source lang="bash">
DRY_RUN="true"
</source>

Danach:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

Es werden die geplanten Aktionen angezeigt, ohne Änderungen durchzuführen.

==Beispiele==

===Vollständige Migration mit Kopie des DB-Verzeichnisses===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="full"
DB_TRANSFER_MODE="copy"

TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"

TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

Aufruf:

<source lang="bash">
sudo ./migrate_superx_webapp.sh
</source>

===Vollständige Migration mit Verschieben des DB-Verzeichnisses===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="full"
DB_TRANSFER_MODE="move"

TARGET_WEBAPP="/var/lib/tomcat10/webapps/superx"

TOMCAT_USER="tomcat"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"
</source>

In diesem Fall wird die Webapp kopiert, das DB-Verzeichnis jedoch verschoben.

===Nur DB-Verzeichnis in bestehende Webapp übernehmen===

<source lang="bash">
SQL_ENV="/home/superx/db/bin/SQL_ENV"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"
TARGET_WEBAPP="auto"

SET_RIGHTS="false"
UPDATE_SQL_ENV="true"
</source>

Aufruf:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

In diesem Fall wird keine Webapp kopiert. Das DB-Verzeichnis wird in die bestehende Webapp unter <code>WEB-INF/conf/edustore/db</code> verschoben.

===Testmigration ohne root===

<source lang="bash">
SQL_ENV="/home/superx/test/db/bin/SQL_ENV"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="copy"
TARGET_WEBAPP="auto"

TOMCAT_USER="superx"
SUPERX_GROUP="superx"

SET_RIGHTS="true"
SET_OWNER="auto"
SET_CHMOD="true"

ADD_TOMCAT_TO_GROUP="false"
</source>

Wird das Skript als Benutzer <code>superx</code> ausgeführt, kann diese Migration ohne root-Rechte laufen.

==Ablauf der Migration==

Das Skript führt je nach Modus folgende Schritte aus:

# Laden von <code>migrate_superx.conf</code>
# Laden der bestehenden <code>SQL_ENV</code>
# Ermitteln von <code>SUPERX_DIR</code>, <code>WEBAPP</code> und dem bisherigen DB-Verzeichnis
# Sicherheitsprüfung, ob die Quelle bereits migriert aussieht
# Ermitteln der Zielstruktur
# Optional: Tomcat stoppen
# Bei <code>MIGRATION_MODE=full</code>: Webapp kopieren
# DB-Verzeichnis je nach <code>DB_TRANSFER_MODE</code> kopieren oder verschieben
# Backup der Ziel-<code>SQL_ENV</code>
# Anpassung von <code>WEBAPP</code>, <code>SUPERX_DIR</code> und <code>umask</code>
# Optional: Rechte setzen
# Optional: Tomcat starten

==Hinweise==

* Die Webapp wird vom Skript nie verschoben, sondern bei <code>MIGRATION_MODE=full</code> kopiert.
* Das DB-Verzeichnis kann wahlweise kopiert oder verschoben werden.
* Bei <code>DB_TRANSFER_MODE=move</code> ist die alte DB-Quelle nach der Migration nicht mehr vorhanden.
* Bei <code>DB_TRANSFER_MODE=move</code> darf das Ziel-DB-Verzeichnis nicht existieren.
* Für <code>copy</code> wird <code>rsync</code> verwendet.
* Die interne Zielstruktur ist fest vorgegeben: <code>WEB-INF/conf/edustore/db</code>.
* Für Produktivmigrationen ist ein vorheriger Dry-Run empfehlenswert.
* Bei Rechteänderungen auf andere Benutzer oder Gruppen sind root-Rechte erforderlich.

Kernmodul Regelbetrieb

2026-06-12T07:33:52Z

Andrek: /* Migration auf die Webapp-Struktur */

Kernmodul Regelbetrieb

2026-06-11T12:38:46Z

Andrek: /* Beispiele */

=BI Maintenance=
[[image:logobutton_maintenance2b.png|200px]]

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

=Migration auf die Webapp-Struktur=

==Ziel==
Mit dem Skript <code>migrate_superx_webapp.sh</code> kann eine bestehende SuperX-Installation automatisch auf die neue Verzeichnisstruktur migriert werden.

Dabei werden die Dateien nicht verschoben, sondern kopiert. Die bestehende Installation bleibt dadurch unverändert erhalten und kann bei Bedarf weiterhin verwendet werden.

Die Migration dient insbesondere dazu, die bisher getrennten Verzeichnisse:

<source lang="text">
/home/superx/db
/home/superx/webserver/tomcat/webapps/superx
</source>

in einer gemeinsamen Struktur innerhalb der Tomcat-Webapp zusammenzuführen.

==Neue Verzeichnisstruktur==
Nach der Migration befindet sich die komplette SuperX-Installation innerhalb der Webapp:

<source lang="text">
<WEBAPP>
├── WEB-INF
│ ├── conf
│ │ └── edustore
│ │ └── db
│ └── ...
└── ...
</source>

Beispiel:

<source lang="text">
/var/lib/tomcat10/webapps/superx
└── WEB-INF
└── conf
└── edustore
└── db
</source>

Die Variablen in der SQL_ENV werden dabei automatisch angepasst:

<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx

SUPERX_DIR=/var/lib/tomcat10/webapps/superx/WEB-INF/conf/edustore
</source>

Zusätzlich wird die Umask auf:

<source lang="bash">
umask 002
</source>

gesetzt, damit Dateien und Verzeichnisse künftig gruppenweit bearbeitet werden können.

==Installation==
Das Migrationsskript wird zusammen mit einer Konfigurationsdatei ausgeliefert:

<source lang="text">
migrate_superx.conf
migrate_superx_webapp.sh
</source>

Beide Dateien müssen sich im selben Verzeichnis befinden.

Das Skript liest die Konfiguration automatisch aus der Datei:

<source lang="text">
migrate_superx.conf
</source>

im aktuellen Skriptverzeichnis ein.

==Konfiguration==

===Vorhandene SQL_ENV===
Pfad zur bestehenden Installation:

<source lang="bash">
SQL_ENV=/home/superx/db/bin/SQL_ENV
</source>

Über diese Datei werden die bisherigen Werte von SUPERX_DIR und WEBAPP ermittelt.

===Ziel-Webapp===
Zielverzeichnis der neuen Installation:

<source lang="bash">
TARGET_WEBAPP=/var/lib/tomcat10/webapps/superx
</source>

Die interne Struktur unterhalb dieses Verzeichnisses wird automatisch erzeugt.

===Benutzer und Gruppen===

<source lang="bash">
TOMCAT_USER=tomcat
SUPERX_GROUP=superx
</source>

Alternativ:

<source lang="bash">
TOMCAT_USER=superx
SUPERX_GROUP=superx
</source>

==Automatische Rechtebehandlung==

Die Variable

<source lang="bash">
SET_OWNER=auto
</source>

steuert, ob und wie Besitzer und Gruppen der migrierten Dateien gesetzt werden.

===SET_OWNER=auto (empfohlen)===

Dies ist die empfohlene Standardeinstellung.

Das Skript entscheidet automatisch, ob ein <code>chown</code> erforderlich ist:

*Wird das Skript als <code>root</code> ausgeführt, werden Besitzer und Gruppe gemäß den Variablen <code>TOMCAT_USER</code> und <code>SUPERX_GROUP</code> gesetzt.
*Wird das Skript als derselbe Benutzer ausgeführt, der auch als <code>TOMCAT_USER</code> konfiguriert wurde und ist dieser Benutzer Mitglied der angegebenen Gruppe, wird auf das <code>chown</code> automatisch verzichtet.
*Ist eine Änderung des Besitzers erforderlich, das Skript läuft jedoch nicht als <code>root</code>, wird die Ausführung mit einer entsprechenden Fehlermeldung abgebrochen.

Dadurch können Testmigrationen ohne Root-Rechte durchgeführt werden, während Produktivmigrationen weiterhin die korrekten Besitzer und Gruppen setzen.

===SET_OWNER=true===

<source lang="bash">
SET_OWNER=true
</source>

Der Besitzer wird immer auf den konfigurierten Benutzer und die konfigurierte Gruppe gesetzt:

<source lang="bash">
chown -R $TOMCAT_USER:$SUPERX_GROUP ...
</source>

Für diese Einstellung werden in der Regel Root-Rechte benötigt.

===SET_OWNER=false===

<source lang="bash">
SET_OWNER=false
</source>

Es wird kein <code>chown</code> ausgeführt.

Die vorhandenen Besitzer- und Gruppeninformationen bleiben unverändert erhalten.

Diese Einstellung eignet sich insbesondere für Testumgebungen oder Spezialfälle, in denen die Rechteverwaltung bereits anderweitig erfolgt.

===Sicherheitsprüfung bereits migrierter Installationen===

Um versehentliche Mehrfachmigrationen zu vermeiden, prüft das Skript standardmäßig, ob die Quellinstallation bereits die neue Webapp-Struktur verwendet.

Folgende Konstellationen werden erkannt:

<source lang="bash">
SUPERX_DIR=/home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
</source>

In diesem Fall liegt <code>SUPERX_DIR</code> bereits innerhalb von <code>WEBAPP</code> und die Installation sieht bereits wie eine migrierte Webapp-Struktur aus.

Zusätzlich wird geprüft, ob bereits folgendes Verzeichnis vorhanden ist:

<source lang="text">
WEB-INF/conf/edustore/db
</source>

Wird eine solche Struktur erkannt, bricht das Skript standardmäßig mit einer entsprechenden Fehlermeldung ab.

===FORCE_ALREADY_MIGRATED===

Für Sonderfälle kann diese Sicherheitsprüfung bewusst übersteuert werden:

<source lang="bash">
FORCE_ALREADY_MIGRATED=true
</source>

Dann wird die Migration trotz erkannter Webapp-Struktur fortgesetzt.

Diese Option sollte nur verwendet werden, wenn die Auswirkungen bekannt sind. Andernfalls besteht die Gefahr, dass bereits migrierte Strukturen erneut kopiert oder Verzeichnisstrukturen ungewollt verschachtelt werden.

Standardwert:

<source lang="bash">
FORCE_ALREADY_MIGRATED=false
</source>

===Beispiele===

Produktivsystem:

<source lang="bash">
TOMCAT_USER=tomcat
SUPERX_GROUP=superx
SET_OWNER=auto
FORCE_ALREADY_MIGRATED=false
</source>

Testsystem:

<source lang="bash">
TOMCAT_USER=superx
SUPERX_GROUP=superx
SET_OWNER=auto
FORCE_ALREADY_MIGRATED=false
</source>

Wird das Skript in diesem Beispiel als Benutzer <code>superx</code> ausgeführt, sind keine Root-Rechte erforderlich.

==Ablauf der Migration==

#Laden der Konfiguration aus migrate_superx.conf
#Laden der bestehenden SQL_ENV
#Ermitteln der bisherigen Verzeichnisse
#Anlegen der Zielstruktur
#Kopieren der Webapp mittels rsync
#Kopieren des DB-Verzeichnisses nach WEB-INF/conf/edustore/db
#Backup der neuen SQL_ENV
#Anpassung von WEBAPP, SUPERX_DIR und umask
#Optionales Setzen von Rechten
#Optionale Tomcat-Integration

==Dry-Run==

Vor einer Produktivmigration empfiehlt sich ein Testlauf:

<source lang="bash">
DRY_RUN=true
</source>

Anschließend:

<source lang="bash">
./migrate_superx_webapp.sh
</source>

Es werden alle geplanten Aktionen angezeigt, jedoch keine Änderungen durchgeführt.

==Produktivmigration==

<source lang="bash">
sudo ./migrate_superx_webapp.sh
</source>

Nach Abschluss sollte die neue SQL_ENV geprüft werden:

<source lang="bash">
. <WEBAPP>/WEB-INF/conf/edustore/db/bin/SQL_ENV

echo $SUPERX_DIR
echo $WEBAPP
</source>

==Hinweise==

*Die ursprüngliche Installation bleibt erhalten, da ausschließlich kopiert wird.
*Für die eigentliche Migration wird rsync benötigt.
*Das Skript kann mehrfach ausgeführt werden.
*Die interne Zielstruktur ist fest definiert und unabhängig vom gewählten Webapp-Pfad.
*Für Produktivmigrationen wird die Ausführung als root empfohlen.
*Testmigrationen können je nach Konfiguration auch ohne Root-Rechte durchgeführt werden.

Kernmodul Regelbetrieb

2026-06-11T12:08:56Z

Andrek: Migration auf die Webapp-Struktur

Datei:rpta tutorial pers erg.png

2026-05-19T11:47:28Z

Andrek:

Datei:rpta tutorial maske spaltenlayout.png

2026-05-19T11:45:09Z

Andrek:

Datei:rpta tutorial beispiel spaltenlayout erstellt.png

2026-05-19T10:24:09Z

Andrek:

Datei:rpta tutorial spaltenlayout anlegen.png

2026-05-19T10:13:24Z

Andrek:

Datei:rpta tutorial navigation spaltenlayout.png

2026-05-19T10:09:51Z

Andrek:

Datei:rpta tutorial layout uebersicht.png.png

2026-05-19T10:03:38Z

Andrek:

Dokumentation

2026-05-19T09:49:29Z

Andrek:

* [[Moduldokumentation]]
* [[DMS-Anbindungen]]
* Websites
** [[Memtext-Homepage]]
*** [[Memtext-Homepage Entwurf]]
*** [[Memtext-Homepage bis 2024]]
** [[Memtext-Academy]]
** [[Memtext-Journal]]
*** [[Memtext-Journal Entwurf]]
** [[SuperX-Homepage]]
* Projekt-Sites
**[[Studienverlauf Frühwarnsystem]]
**[[Lehrveranstaltungen (Stundenplan)]]
**[[Datenabzüge (Datenblätter einfrieren)]]
**[[Studiengangsmanagement (Begleitung des Studiengangsmanagements mit Kennzahlen)]]
*** [[Kennzahlen im Bereich Bewerbungen]]
** [[ZSL_Mittelverteilung|Berichte zur ZSL Mittelverteilung MWK BaWue]]
* Testfälle
**[[HIS-Demo_eduetl_davy]]
* Kurse
**SuperX
*** [[Kurs-SuperX-Nutzung|Nutzung]]
**Kettle
***[[Kettle-Grundlagen|Kettle Grundlagen]]: Einstieg in Kettle, erste Schritte zur Arbeit mit Spoon und Integration in SuperX/HISinOne-BI
***[[Kettle_Kurs_Teil_2|Kettle für Fortgeschrittene]]: Kettle-Monitoring und Mailversand, Automatisierung, weitere Integration in SuperX/
**[[Berichtsassistent-Grundlagen|Berichtsassistent Grundlagen]]: Einstieg in den Berichtsassistenten (RPTA)
HISinOne-BI
** [[LM-Vorstellung|LM-Vorstellung]]

Kernmodul Regelbetrieb

2025-12-17T08:33:02Z

Andrek: /* Mailversand */

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

Kernmodul Regelbetrieb

2025-12-17T08:32:28Z

Andrek: /* Mailversand */

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten Die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

Kernmodul Regelbetrieb

2025-12-17T08:31:26Z

Andrek: /* Mailversand */

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

Kernmodul Regelbetrieb

2025-12-17T08:30:09Z

Andrek: /* Mailversand */

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

Datei:Kernmodul Regelbetrieb Mailversand.png

2025-12-17T08:26:50Z

Andrek:

Kernmodul Regelbetrieb

2025-12-16T12:26:43Z

Andrek: /* Ziel und Überblick */

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

----

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

Kernmodul Regelbetrieb

2025-12-15T12:51:39Z

Andrek:

=BI Maintenance=

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von SuperX/HISinOne Modul-Updates und -Upgrades weiterhin zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell.
Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

----

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.
Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:
<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>