SuperX - Benutzerbeiträge [de]

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>

Datei:qhd.09.2025 1759152418659.png

2025-09-29T13:27:06Z

Andrek:

Datei:Huef NRW SuperX-Treffen 30.09.2025 1759150068265.09.2025 1759150068226.png

2025-09-29T12:47:50Z

Andrek:

Datei:Themenbaum Ausgeklappt.09.2025 1759146477481.png

2025-09-29T11:48:16Z

Andrek: