SuperX - Benutzerbeiträge [de]

Kernmodul Tomcat-Einrichtung

2026-10-09T06:16:22Z

Andrek:

Installation und Einrichtung von
[[Bild:tomcat.png]]
Tomcat

Für das SuperX-Kernmodul 6.0 empfehlen wir '''Tomcat 10.1''' mit '''Java 21'''. Die folgenden Beispiele beziehen sich überwiegend auf Ubuntu Linux 26.04. Bei anderen Linux-Distributionen sind die Konfigurationsschritte weitgehend identisch, die Paketnamen und Pfade können aber abweichen.
{{Achtung|Der Umstieg von Tomcat 9 auf Tomcat 10 ist kein reines Versionsupdate. Die Java-EE-Schnittstellen wurden von <code>javax.*</code> nach <code>jakarta.*</code> umgestellt. Für Tomcat 10 wird eine dafür geeignete SuperX-Webanwendung benötigt. Weitere Hinweise dazu stehen im Abschnitt [[#Wechsel_von_Tomcat_9_auf_Tomcat_10|Wechsel von Tomcat 9 auf Tomcat 10]].}}

=Tomcat aus Linux Distributionen=
Da die Versionsnummern des Tomcat nicht immer zu SuperX passen, können Sie einen eigenen Tomcat bzw. den im SuperX-Kernmodul mitgelieferten Tomcat nutzen. Auch wenn Sie mehrere Tomcats auf einem Server betreiben, kann es sinnvoll sein, Tomcat [[Kernmodul_Tomcat-Einrichtung#Tomcat_manuell_installieren|manuell]] zu installieren.
Der Betrieb von Tomcat aus der jeweiligen Linux-Distribution hat jedoch den Vorteil, dass man
* benötigte Drittsoftware direkt mitinstallieren kann
* die Apache-Integration einfacher einrichten kann
* regelmäßige Sicherheitsupdates und Bugfixes über die Paketverwaltung beziehen kann
* Tomcat in der Regel bereits als systemd-Dienst erhält
Wenn eine für SuperX geeignete Tomcat-Version in der Distribution enthalten ist, empfehlen wir daher die Installation aus der Distribution.

==Tomcat aus der Ubuntu-Distribution==
Im Folgenden wird das Vorgehen für Ubuntu Linux 26.04 mit Java 21 und Tomcat 10.1 beschrieben.
Zunächst wechseln Sie in die root-Shell mit
sudo -i
Java 21, Tomcat 10 und den Apache-Webserver installieren:
apt-get update
apt-get install -y openjdk-21-jdk tomcat10 apache2
Tomcat anschließend zunächst stoppen:
systemctl stop tomcat10.service
Die installierten Versionen können Sie prüfen mit
java -version
/usr/share/tomcat10/bin/version.sh
{{Hinweis|Das Ubuntu-Paket <code>tomcat10</code> enthält Tomcat 10.1. Die tatsächlich ausgelieferte Patchversion hängt vom Paketstand ab. Die hier empfohlene Kombination mit Java 21 ist eine SuperX-Empfehlung; Tomcat 10.1 selbst benötigt mindestens Java 11.}}

Die Konfiguration des Distributions-Tomcat liegt üblicherweise in
/etc/tomcat10/server.xml
und die Webanwendungen in
/var/lib/tomcat10/webapps
Kopieren Sie die zu Tomcat 10 passende SuperX-Webanwendung in das webapps-Verzeichnis. Der Tomcat-Dienstbenutzer muss auf die benötigten Dateien zugreifen können; die Eigentümer- und Schreibrechte sollten auf die tatsächlich erforderlichen Verzeichnisse begrenzt werden.
Beim HTTP-Connector in der <code>server.xml</code> setzen Sie die Zeichenkodierung auf UTF-8. Wenn Apache und Tomcat auf demselben Server laufen, empfehlen wir außerdem die Bindung an localhost:
<source lang="xml">
<Connector port="8080" protocol="HTTP/1.1"
address="127.0.0.1"
connectionTimeout="20000"
URIEncoding="UTF-8" />
</source>
Die weiteren Einstellungen für den Betrieb hinter Apache werden unter [[#Apache_Anbindung|Apache Anbindung]] erläutert. Weitere Details zur <code>server.xml</code> siehe [[Kern_Installation_Upgrade#Steuerung_des_Servers%3A_Die_server.xml|SuperX-Installationshandbuch]].

Unter Ubuntu können Java-Optionen üblicherweise in der Datei
/etc/default/tomcat10
hinterlegt werden, z.B.:
JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
JAVA_OPTS="-Djava.awt.headless=true -DSuperX-DB-PROPERTIES-SET=true -Xmx3700M"
Der Speicherwert ist nur ein Beispiel. Prüfen Sie mit <code>systemctl cat tomcat10</code>, welche Konfigurationsdateien der installierte Dienst tatsächlich einliest. Die vom Paket bereitgestellte systemd-Service-Datei sollte nicht direkt bearbeitet werden; bei Bedarf verwenden Sie eine systemd-Override-Datei.
Starten Sie Tomcat mit
systemctl start tomcat10.service
und prüfen Sie den Status mit
systemctl status tomcat10.service
Wenn der HTTP-Connector nur an <code>127.0.0.1</code> gebunden ist, kann der Zugriff auf demselben Server getestet werden mit
curl -I http://127.0.0.1:8080/superx/
Für den Aufruf vom Arbeitsplatzrechner wird anschließend die Apache-Anbindung eingerichtet.

==Tomcat unter anderen Linux-Distributionen==
Auch unter SUSE Linux und Red Hat Enterprise Linux können Sie den Tomcat aus der Distribution oder [[#Tomcat_manuell_installieren|manuell]] installieren. Die genauen Paketnamen, Dienstnamen und Verzeichnisse sind distributionsabhängig. Entscheidend sind eine geeignete Tomcat-10.1-Version, Java 21, eine kompatible SuperX-Webanwendung und die Konfiguration des HTTP-Connectors bzw. AJP-Connectors.
Ältere Verfahren mit <code>rctomcat</code>, <code>chkconfig</code> oder <code>SuSEconfig</code> werden hier nicht mehr beschrieben. Für die Dienstverwaltung wird systemd verwendet.

==Tomcat aus der Distribution mit abweichender Userkennung oder anderem webapps-Verzeichnis==
Wenn Sie Tomcat aus der Distribution nutzen, läuft der Dienst unter einer dafür eingerichteten Systemkennung. Bei Ubuntu liegt das webapps-Verzeichnis üblicherweise unter <code>/var/lib/tomcat10/webapps</code>.
{{Hinweis|Standardmäßig hat der Tomcat-Dienstbenutzer keine Login-Shell. Dies sollte aus Sicherheitsgründen so bleiben.}}
Sie können das Verzeichnis der Webanwendungen auch ändern, indem Sie in der Datei <code>/etc/tomcat10/server.xml</code> beim Element <code>Host</code> das Attribut <code>appBase</code> anpassen, z.B.:
<source lang="xml">
<Host name="localhost" appBase="/home/superx/webserver/tomcat/webapps"
unpackWARs="true" autoDeploy="false">
</source>
Beachten Sie, dass der Tomcat-Dienstbenutzer Lese- und Ausführungsrechte auf den gesamten benötigten Verzeichnispfad benötigt. Schreibrechte sollten nur für tatsächlich beschreibbare Verzeichnisse vergeben werden, etwa für temporäre Dateien oder SuperX-Logdateien. Auf gemeinsam verwendeten Verzeichnissen kann die Gruppenberechtigung entsprechend angepasst werden.
Wenn Sie als User <code>superx</code> neue Dateien anlegen und eine gemeinsam verwendete Gruppe eingerichtet haben, kann eine passende umask helfen:
# Full access to user and group, none for others:
umask u=rwx,g=rwx,o=
Die konkrete Gruppenkennung und die Eigentümerschaft richten sich nach der Installation. Beachten Sie auch die Hinweise für [[#Tomcat_und_Kettle|Tomcat und Kettle]].

==Tomcat und Kettle==
Im Homeverzeichnis des Benutzers, unter dem Tomcat läuft, sollte das Verzeichnis <code>.kettle</code> mit der Datei <code>kettle.properties</code> angelegt werden. Die Datei kann zunächst leer sein. Ermitteln Sie zuerst das Homeverzeichnis des Tomcat-Benutzers, z.B. mit
getent passwd tomcat
Liegt dieses bei Ubuntu unter <code>/var/lib/tomcat10</code>, können Sie als root Folgendes ausführen:
install -d -o tomcat -g tomcat /var/lib/tomcat10/.kettle
touch /var/lib/tomcat10/.kettle/kettle.properties
chown tomcat:tomcat /var/lib/tomcat10/.kettle/kettle.properties
{{Hinweis|Bei einer Distributionsaktualisierung sollte geprüft werden, ob das Homeverzeichnis des Tomcat-Benutzers weiterhin korrekt gesetzt ist.}}

=Tomcat manuell installieren=
Sie können auch spezielle Versionen von [https://tomcat.apache.org Tomcat] herunterladen und installieren. Oder Sie verwenden den im SuperX-Kernmodul mitgelieferten Tomcat. Speicherort ist z.B. <code>/home/superx/webserver/tomcat</code>.
Bei einer Neuinstallation bzw. einem Versionswechsel sollten Sie die Konfiguration der neuen Tomcat-Version als Ausgangspunkt verwenden. Kopieren Sie nicht einfach die kompletten alten Verzeichnisse <code>bin</code>, <code>lib</code> und <code>conf</code> darüber. Auch bisher benötigte Zusatzbibliotheken und Java-Optionen müssen auf Kompatibilität geprüft werden.

==Tomcat als Dienst==
Damit Tomcat beim Systemstart automatisch hochfährt und beim Herunterfahren kontrolliert gestoppt wird, kann man einen systemd-Dienst anlegen. Im Beispiel liegt SuperX unter <code>/home/superx</code> und Tomcat wird vom Benutzer <code>superx</code> gestartet. Für eine Installation aus der Linux-Distribution ist der Dienst in der Regel bereits vorhanden.

===Service-Scripte===
Zunächst legen wir als User <code>superx</code> im Verzeichnis <code>tomcat/bin</code> zwei Dateien an.
<code>startup_service.x</code>:
#!/bin/bash
# Startup script for Apache Tomcat with systemd
set -e
# Load the service settings
. /home/superx/db/bin/SQL_ENV
export CATALINA_BASE=/home/superx/webserver/tomcat
export CATALINA_HOME=/home/superx/webserver/tomcat
export CATALINA_TMPDIR=/home/superx/webserver/tomcat/temp
# Start Tomcat
cd "$CATALINA_BASE" && exec "$CATALINA_HOME/bin/catalina.sh" run
und <code>shutdown_service.x</code>:
#!/bin/bash
# Shutdown script for Apache Tomcat with systemd
set -e
# Load the service settings
. /home/superx/db/bin/SQL_ENV
export CATALINA_BASE=/home/superx/webserver/tomcat
export CATALINA_HOME=/home/superx/webserver/tomcat
export CATALINA_TMPDIR=/home/superx/webserver/tomcat/temp
# Stop Tomcat
cd "$CATALINA_BASE" && exec "$CATALINA_HOME/bin/catalina.sh" stop
In der Datei <code>SQL_ENV</code> sollten die für Tomcat benötigten Umgebungsvariablen, insbesondere <code>JAVA_HOME</code> für Java 21 und die Java-Optionen, korrekt gesetzt bzw. exportiert werden. Der Pfad zu Java ist von der Distribution abhängig.

===Dienst einrichten===
Legen Sie als User root die Datei <code>/etc/systemd/system/tomcat_superx.service</code> an, mit dem Inhalt:
[Unit]
Description=Tomcat SuperX
After=network.target

[Service]
Type=simple
User=superx
Group=users
WorkingDirectory=/home/superx/webserver/tomcat/bin
ExecStart=/bin/bash /home/superx/webserver/tomcat/bin/startup_service.x
ExecStop=/bin/bash /home/superx/webserver/tomcat/bin/shutdown_service.x

[Install]
WantedBy=multi-user.target
Die Gruppe <code>users</code> ist hier nur ein Beispiel und muss gegebenenfalls angepasst werden. Der Eintrag <code>EnvironmentFile=/home/superx/db/bin/SQL_ENV</code> wird nicht benötigt, da die Skripte die <code>SQL_ENV</code> bereits als Bash-Skript einlesen. systemd kann unter <code>EnvironmentFile</code> keine beliebigen Bash-Befehle ausführen.
Den Dienst aktivieren und starten Sie mit
systemctl daemon-reload
systemctl enable tomcat_superx
systemctl start tomcat_superx
Den Status und die Logmeldungen können Sie prüfen mit
systemctl status tomcat_superx
journalctl -u tomcat_superx -e
Wenn Sie die Service-Datei ändern, müssen Sie danach <code>systemctl daemon-reload</code> ausführen. Den Dienst deaktivieren Sie mit
systemctl disable tomcat_superx
{{Achtung|Ein Fallstrick: Wenn die <code>SQL_ENV</code> komplexe Bash-Kommandos enthält oder für einen systemd-Dienst ungeeignete Einstellungen setzt, kann der Dienststart scheitern. In diesem Fall kann eine separate, vereinfachte <code>TOMCAT_ENV</code> sinnvoll sein, die von den Startskripten eingelesen wird.}}
Für mögliche SELinux-Probleme bei Shell-Skripten in systemd-Diensten siehe [[Kern_Installation_Upgrade#SELinux_(Security-Enhanced_Linux)|SELinux im SuperX-Installationshandbuch]].

=Tomcat Logging=
==Tomcat Logging mit systemd==
Je nach Installationsart erscheinen Tomcat-Meldungen im systemd-Journal oder in Dateien unter <code>$CATALINA_BASE/logs</code>. Bei einem manuell installierten Tomcat kann z.B. die Datei <code>catalina.out</code> vorhanden sein. Bei der Ubuntu-Distributionsinstallation sollte auch das systemd-Journal geprüft werden.
Alle Journalmeldungen anzeigen:
journalctl
Die Meldungen eines bestimmten Tomcat-Dienstes anzeigen, z.B.:
journalctl -u tomcat10 -e
journalctl -u tomcat_superx -e
Die Meldungen live verfolgen:
journalctl -u tomcat10 -f
{{Hinweis|Ab SuperX 5.1 bzw. HISinOne-BI 2023.12 werden SuperX-spezifische Logmeldungen in der Datei <code>$CATALINA_BASE/logs/superx.log</code> ausgegeben. Je nach Fehlerbild sind sowohl diese Datei als auch die Tomcat-/systemd-Meldungen relevant.}}

=Apache Anbindung=
In Systemumgebungen, in denen bereits ein Webserver wie Apache läuft, bietet es sich an, den SuperX-Tomcat mit dem Webserver zu verbinden. Der Webserver kann so konfiguriert werden, dass Aufrufe zu <code>https://superx.example.de/superx/</code> an Tomcat weitergeleitet werden. Dadurch müssen die internen Tomcat-Ports nicht nach außen freigegeben werden. Die HTTPS-Verschlüsselung und die Zertifikatsverwaltung können vom Apache übernommen werden. Wir empfehlen daher generell die Anbindung von Tomcat an Apache für einen Produktivbetrieb.
Für die Verbindung zwischen Apache und Tomcat gibt es verschiedene Möglichkeiten:
* '''HTTP über Port 8080 mit ProxyPass (empfohlen)'''
* '''AJP über Port 8009 mit ProxyPass (Alternative)'''
* Mod-JK für bestehende Installationen
Wenn Apache und Tomcat auf demselben Server laufen, sollten die internen Connectoren nur an <code>127.0.0.1</code> gebunden werden. Bei getrennten Servern muss die Verbindung über ein vertrauenswürdiges und entsprechend geschütztes Netzwerk erfolgen.

==ProxyPass über HTTP (Port 8080)==
Wir empfehlen die HTTP-Anbindung über <code>mod_proxy</code> und <code>mod_proxy_http</code>. Sie ist einfach zu konfigurieren, verwendet das übliche HTTP-Protokoll und benötigt keinen AJP-Connector. AJP bietet zusätzliche Zugriffsmöglichkeiten auf Tomcat-interne Informationen und benötigt deshalb besondere Absicherung. HTTP über localhost ist damit bei gleicher Zugangsbeschränkung die einfacher zu betreibende Variante. Der interne HTTP-Verkehr ist dabei nicht verschlüsselt; dieses Beispiel gilt deshalb für Apache und Tomcat auf demselben Server.
Unter Ubuntu aktivieren Sie die benötigten Apache-Module mit
a2enmod proxy proxy_http ssl

===Tomcat konfigurieren===
In der <code>server.xml</code> (bei Ubuntu <code>/etc/tomcat10/server.xml</code>) richten Sie den HTTP-Connector ein:
<source lang="xml">
<Connector port="8080" protocol="HTTP/1.1"
address="127.0.0.1"
connectionTimeout="20000"
URIEncoding="UTF-8"
proxyName="superx.example.de"
proxyPort="443"
scheme="https"
secure="true" />
</source>
Der Wert <code>proxyName</code> muss dem öffentlich verwendeten Hostnamen entsprechen. Die Angaben <code>proxyPort="443"</code>, <code>scheme="https"</code> und <code>secure="true"</code> teilen Tomcat mit, dass die Anwender die Webanwendung über HTTPS am Apache aufrufen. Diese Konfiguration ist für eine ausschließlich über HTTPS erreichbare SuperX-Anwendung mit einem festen öffentlichen Hostnamen gedacht.

===Apache konfigurieren===
Im Apache-VirtualHost für HTTPS (unter Ubuntu z.B. in <code>/etc/apache2/sites-available/superx.conf</code>) ergänzen Sie die Weiterleitung:
<source lang="apache">
<VirtualHost *:443>
ServerName superx.example.de
SSLEngine on
SSLCertificateFile /etc/ssl/certs/superx.crt
SSLCertificateKeyFile /etc/ssl/private/superx.key
ProxyRequests Off
ProxyPass "/superx" "http://127.0.0.1:8080/superx"
ProxyPassReverse "/superx" "http://127.0.0.1:8080/superx"
</VirtualHost>
</source>
Die Zertifikatspfade sind Beispiele. Bestehende VirtualHosts werden entsprechend ergänzt; die SSL-Konfiguration muss nicht doppelt angelegt werden. <code>ProxyPass</code> leitet die Anfragen an Tomcat weiter, <code>ProxyPassReverse</code> passt bestimmte vom Backend gelieferte HTTP-Weiterleitungen an. URLs, die eine Webanwendung direkt in HTML erzeugt, werden dadurch nicht automatisch korrigiert.
Nach den Änderungen prüfen Sie die Konfiguration und starten die Dienste neu:
apache2ctl configtest
systemctl restart tomcat10
systemctl reload apache2
Der Dienstname muss gegebenenfalls an die eigene Installation angepasst werden.

===Falsche localhost-Adressen in DBForms bzw. HTML-Ausgaben===
Wenn die öffentliche SuperX-Adresse über HTTPS aufgerufen wird, Tomcat intern aber nur den HTTP-Aufruf über <code>localhost:8080</code> erkennt, können Webanwendungen fehlerhafte absolute URLs erzeugen. Das kann z.B. bei DBForms zu einem solchen HTML-Eintrag führen:
<source lang="html">
<base href="http://localhost:8080/superx/" />
</source>
Der Browser des Anwenders versucht dann, Ressourcen von seinem eigenen Rechner (<code>localhost</code>) zu laden. Bilder, Skripte oder Verweise funktionieren deshalb gegebenenfalls nicht. Mit den oben beschriebenen Connector-Attributen <code>proxyName</code>, <code>proxyPort</code>, <code>scheme</code> und <code>secure</code> kann Tomcat den korrekten öffentlichen Servernamen und das HTTPS-Schema an die Webanwendung melden.
{{Hinweis|Das Element <code><Host name="localhost"></code> in der Tomcat-<code>server.xml</code> bezeichnet einen virtuellen Tomcat-Host und muss dafür nicht in den öffentlichen DNS-Namen umbenannt werden. Entscheidend sind die für den Proxy verwendeten Connector-Einstellungen.}}
Wenn mehrere öffentliche Hostnamen oder unterschiedliche Zugriffsschemata benötigt werden, reicht ein fest eingetragener <code>proxyName</code> gegebenenfalls nicht aus. Dann kann eine Konfiguration mit vertrauenswürdigen Proxy-Headern und der Tomcat-<code>RemoteIpValve</code> sinnvoll sein. Der Proxy muss solche Header kontrolliert setzen; unkontrolliert vom Client übernommene Header sind aus Sicherheitsgründen ungeeignet.

==ProxyPass über AJP (Port 8009)==
Alternativ kann die Verbindung über das AJP-Protokoll erfolgen. Dafür benötigen Sie beim Apache das Modul <code>mod_proxy_ajp</code> und auf Tomcat-Seite einen AJP-Connector. AJP ist weiterhin unterstützt, sollte aber nur in einem vertrauenswürdigen Netzwerk oder lokal verwendet werden. Das Secret schützt vor unberechtigten AJP-Verbindungen, verschlüsselt die Übertragung jedoch nicht.
Unter Ubuntu aktivieren Sie das Modul mit
a2enmod proxy proxy_ajp
In der Tomcat-<code>server.xml</code>:
<source lang="xml">
<Connector protocol="AJP/1.3"
address="127.0.0.1"
port="8009"
secretRequired="true"
secret="HIER_EIN_LANGES_ZUFAELLIGES_SECRET_EINTRAGEN"
URIEncoding="UTF-8" />
</source>
Im Apache-VirtualHost wird anstelle der HTTP-Weiterleitung die AJP-Weiterleitung verwendet:
<source lang="apache">
ProxyPass "/superx" "ajp://127.0.0.1:8009/superx" secret=HIER_EIN_LANGES_ZUFAELLIGES_SECRET_EINTRAGEN
</source>
Beide Secrets müssen übereinstimmen und dürfen nicht als öffentliche Beispielwerte übernommen werden. Der Parameter <code>secret</code> bei <code>ProxyPass</code> ist ab Apache 2.4.42 verfügbar. Auf beiden Seiten sollte die Konfiguration vor unberechtigtem Zugriff geschützt werden. Eine parallele HTTP- und AJP-Weiterleitung für denselben Pfad ist nicht erforderlich.
Wenn Apache auf einem separaten Server läuft, muss statt <code>127.0.0.1</code> die geeignete interne IP-Adresse des Tomcat-Servers verwendet werden. Zusätzlich müssen Firewall und Netzabsicherung passend konfiguriert werden.
Weitere Details siehe [https://tomcat.apache.org/tomcat-10.1-doc/config/ajp.html Tomcat AJP Connector].

==Mod-JK==
Das Apache-Modul <code>mod_jk</code> wird weiterhin für bestehende AJP-Installationen unterstützt. Für neue SuperX-Installationen empfehlen wir jedoch die oben beschriebene Anbindung über <code>ProxyPass</code>. Unter Ubuntu können Sie Mod-JK bei Bedarf installieren und aktivieren mit
apt-get install -y libapache2-mod-jk
a2enmod jk
Der AJP-Connector in Tomcat benötigt dieselben Sicherheitsvorgaben wie bei <code>mod_proxy_ajp</code>. In der <code>workers.properties</code> wird der Worker z.B. so eingerichtet:
worker.list=superx_tomcat
worker.superx_tomcat.type=ajp13
worker.superx_tomcat.host=127.0.0.1
worker.superx_tomcat.port=8009
worker.superx_tomcat.secret=HIER_EIN_LANGES_ZUFAELLIGES_SECRET_EINTRAGEN
Die Weiterleitung kann in der Apache-Konfiguration so erfolgen:
JkMount /superx/* superx_tomcat
JkMount /superx superx_tomcat
{{Hinweis|Falls bereits eine Mod-JK-Konfiguration aus dem SuperX-Kernmodul verwendet wird, können Sie diese weiter pflegen. Alte Beispielkonfigurationen mit einem ungeschützten AJP-Port oder unnötigen Apache-Dateisystem-Aliases sollten jedoch nicht unverändert übernommen werden.}}

==Apache und Tomcat Sicherheit==
Für den Produktivbetrieb empfehlen wir folgende Grundeinstellungen:
* HTTPS wird nach außen am Apache bereitgestellt. Die internen Ports 8080 bzw. 8009 werden nicht über die öffentliche Firewall freigegeben.
* Bei Betrieb auf demselben Server werden die Tomcat-Connectoren an <code>127.0.0.1</code> gebunden.
* Nicht benötigte Connectoren werden in der <code>server.xml</code> deaktiviert.
* Bei AJP wird ein eigenes, langes Secret verwendet; AJP sollte nicht über ungeschützte Netze betrieben werden.
* Der Tomcat-Dienst läuft ohne Root-Rechte. Konfigurationsdateien und die Webanwendung erhalten nur die benötigten Dateirechte.
* Apache, Tomcat und Java werden regelmäßig mit Sicherheitsupdates versorgt.
* Bei SELinux-bedingten Verbindungsproblemen oder Problemen mit systemd-Shell-Skripten siehe [[Kern_Installation_Upgrade#SELinux_(Security-Enhanced_Linux)|SELinux (Security-Enhanced Linux) im SuperX-Installationshandbuch]].
Weitere Tipps zur Tomcat-Sicherheit siehe [https://tomcat.apache.org/tomcat-10.1-doc/security-howto.html Tomcat Security How-To].

=Einrichtung SSL=
==SSL Varianten==
Sie können SSL/TLS direkt in Tomcat einrichten, normalerweise wird die Verschlüsselung aber im [[#SSL_im_Webserver|Webserver]] konfiguriert. Bei einer Apache-Tomcat-Anbindung empfehlen wir, HTTPS beim Apache zu beenden und den internen Tomcat-Connector nur lokal erreichbar zu machen.

==SSL im Webserver==
Unter Ubuntu benötigen Sie das Apache-Modul <code>ssl</code>. Es kann aktiviert werden mit
a2enmod ssl
Im HTTPS-VirtualHost wird das Zertifikat eingebunden, z.B.:
<source lang="apache">
<VirtualHost *:443>
ServerName superx.example.de
SSLEngine on
SSLCertificateFile /etc/ssl/certs/superx.crt
SSLCertificateKeyFile /etc/ssl/private/superx.key
# Weitere Einstellungen, z.B. die ProxyPass-Anbindung, siehe oben.
</VirtualHost>
</source>
Zertifikat und Schlüssel müssen zum öffentlichen Hostnamen passen. Die Datei mit dem privaten Schlüssel darf nur von berechtigten Systembenutzern gelesen werden. Die tatsächlich verwendeten Pfade richten sich nach der Zertifikatsverwaltung vor Ort.
Wenn zusätzlich Zugriffe auf Port 80 auf HTTPS umgeleitet werden sollen, kann ein eigener VirtualHost verwendet werden:
<source lang="apache">
<VirtualHost *:80>
ServerName superx.example.de
Redirect permanent / https://superx.example.de/
</VirtualHost>
</source>
Die Apache-Konfiguration prüfen und neu laden:
apache2ctl configtest
systemctl reload apache2

===Zertifikate mit Let's Encrypt===
Wenn der Server die Voraussetzungen für eine öffentliche ACME-Zertifikatsprüfung erfüllt, können Sie z.B. Let's Encrypt in Verbindung mit Certbot verwenden. Unter Ubuntu stehen dafür passende Pakete bereit:
apt-get install -y certbot python3-certbot-apache
Die konkrete Ausstellung, Einrichtung und automatische Verlängerung hängen davon ab, ob der Webserver öffentlich erreichbar ist und welche Zertifikatsverwaltung die Hochschule einsetzt. Weitere Informationen siehe [https://certbot.eff.org/ Certbot] und [https://letsencrypt.org/de/ Let's Encrypt].

==SSL im Tomcat==
Falls kein vorgeschalteter Apache-Webserver vorhanden ist, kann Tomcat HTTPS auch direkt bereitstellen. In Tomcat 10.1 wird die TLS-Konfiguration über <code>SSLHostConfig</code> und <code>Certificate</code> vorgenommen. Beispiel mit vorhandenem PKCS12-Keystore:
<source lang="xml">
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateKeystoreFile="/home/superx/tomcat-keystore.p12"
certificateKeystoreType="PKCS12"
certificateKeystorePassword="HIER_DAS_KEYSTORE_PASSWORT" />
</SSLHostConfig>
</Connector>
</source>
Der Keystore muss ein zum öffentlichen Hostnamen passendes Zertifikat und den privaten Schlüssel enthalten. Das Passwort im Beispiel muss durch einen eigenen sicheren Wert ersetzt und entsprechend geschützt werden. Bei direkt von außen erreichbarem Tomcat muss außerdem Port 8443 entsprechend abgesichert werden.
Eine ausführliche Anleitung zum Erzeugen bzw. Einbinden von Zertifikaten steht in der [https://tomcat.apache.org/tomcat-10.1-doc/ssl-howto.html offiziellen Tomcat-10.1-Dokumentation].

=Wechsel von Tomcat 9 auf Tomcat 10=
Mit Tomcat 10 wurden die Java-EE-Schnittstellen auf Jakarta EE umgestellt. Insbesondere wurden viele Paketnamen von <code>javax.*</code> nach <code>jakarta.*</code> geändert. Eine für Tomcat 9 bereitgestellte Webanwendung kann deshalb nicht ohne Weiteres mit Tomcat 10 verwendet werden. Für das SuperX-Kernmodul 6.0 empfehlen wir Tomcat 10.1 und Java 21.
Für den Versionswechsel muss insbesondere geprüft werden, ob die SuperX-Webanwendung und zusätzlich eingesetzte Bibliotheken für Tomcat 10 geeignet sind. Die Konfiguration der neuen Tomcat-Version sollte als Grundlage verwendet werden; die bisherigen Konfigurationsdateien sollten nicht vollständig übernommen werden. Auch bestehende Java-Optionen sowie die Apache-Anbindung müssen geprüft werden.
{{Hinweis|Der Wechsel von Tomcat 9 auf Tomcat 10 wird wegen der umfangreicheren Umstellung in einem separaten Migrationsleitfaden behandelt. Bis dahin siehe [https://tomcat.apache.org/migration.html offizielle Tomcat-Migrationshinweise].}}

Kernmodul Regelbetrieb

2026-10-02T06:21:12Z

Andrek: SuperX Pfade angepasst

=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">
. /home/superx/git/BI_Maintenance/env/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=/home/superx/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 die automatische Ausführung==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript. Dieses kann sowohl über einen klassischen Cronjob als auch über einen systemd-Service gestartet werden.

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>, zum Update-Skript und zur Logdatei anpassen.

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>
* Umleitung der Ausgabe in die konfigurierte Logdatei

===Ausführung über Cron===
Für die regelmäßige Ausführung kann beispielsweise ein Cronjob eingerichtet werden, der das Update werktags um 18 Uhr startet:

<source lang="bash">
0 18 * * 1-5 /home/superx/git/BI_Maintenance/update/modules_update_cron.sh
</source>

Der Cronjob sollte unter dem Benutzer ausgeführt werden, unter dem auch die BI-Installation betrieben wird, üblicherweise <code>superx</code>.

===Ausführung über systemd===
Alternativ zum klassischen Cronjob kann die Laderoutine über einen systemd-Service und einen systemd-Timer ausgeführt werden.

Im Verzeichnis

<source lang="text">
update/systemd/
</source>

werden hierfür die beiden Beispieldateien

<source lang="text">
superx_update.service
superx_update.timer
</source>

bereitgestellt.

Der Service führt das Wrapper-Skript <code>modules_update_cron.sh</code> unter dem Benutzer <code>superx</code> aus.

Beispiel <code>superx_update.service</code>:

<source lang="ini">
[Unit]
Description=SuperX BI Laderoutine

[Service]
Type=oneshot
User=superx
Group=superx
WorkingDirectory=/home/superx
ExecStart=/bin/bash /home/superx/git/BI_Maintenance/update/modules_update_cron.sh
</source>

Die Pfade sowie Benutzer und Gruppe müssen bei Bedarf an die lokale Installation angepasst werden.

Durch den expliziten Aufruf über <code>/bin/bash</code> können insbesondere auf Systemen mit SELinux Probleme bei der direkten Ausführung von Skripten aus Benutzerverzeichnissen vermieden werden.

Der zugehörige Timer legt fest, wann der Service gestartet wird.

Beispiel <code>superx_update.timer</code>:

<source lang="ini">
[Unit]
Description=Timer für SuperX BI Laderoutine

[Timer]
OnCalendar=Mon..Fri *-*-* 18:00:00
Unit=superx_update.service

# Optional:
# Verpassten Lauf nach Server-Neustart nachholen:
# Persistent=true

[Install]
WantedBy=timers.target
</source>

Im Beispiel wird die Laderoutine montags bis freitags jeweils um 18 Uhr ausgeführt. Der Zeitplan kann über <code>OnCalendar</code> an die lokalen Anforderungen angepasst werden.

Die beiden Dateien werden nach <code>/etc/systemd/system</code> kopiert:

<source lang="bash">
cp systemd/superx_update.service /etc/systemd/system/
cp systemd/superx_update.timer /etc/systemd/system/
</source>

Anschließend wird die systemd-Konfiguration neu eingelesen und der Timer aktiviert:

<source lang="bash">
systemctl daemon-reload
systemctl enable --now superx_update.timer
</source>

Der Status des Timers und die nächste geplante Ausführung können anschließend geprüft werden:

<source lang="bash">
systemctl status superx_update.timer
systemctl list-timers --all | grep superx
</source>

Der Service kann unabhängig vom Timer auch manuell gestartet und geprüft werden:

<source lang="bash">
systemctl start superx_update.service
systemctl status superx_update.service
</source>

Der <code>superx_update.service</code> selbst muss nicht mit <code>systemctl enable</code> aktiviert werden. Er wird bei Bedarf durch den Timer gestartet.

Optional kann im Timer

<source lang="ini">
Persistent=true
</source>

gesetzt werden. In diesem Fall holt systemd einen verpassten Lauf nach, beispielsweise wenn der Server zum geplanten Ausführungszeitpunkt ausgeschaltet war. Ob dieses Verhalten gewünscht ist, sollte für die jeweilige Installation entschieden werden.

----

=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 /home/superx/git/BI_Maintenance/upgrade
./modules_upgrade.sh
</source>

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

<source lang="bash">
. /home/superx/git/BI_Maintenance/env/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=

Das bereitgestellte Migrationsskript ermöglicht die Umstellung einer bestehenden SuperX-Installation auf die empfohlene Webapp-Struktur.

Dabei können sowohl klassische Installationen mit separatem DB-Verzeichnis als auch bestehende Webapp-Installationen migriert werden. Die Migration kann je nach Anwendungsfall vollständig oder ausschließlich für das DB-Verzeichnis durchgeführt werden.
Hier eine Anleitung "in short", wenn Sie bisher das "klasssische" Layout genutzt haben (also Unix Benutzer "superx", Installation in "/home/superx").

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git
#Script ausführen und neues ENV laden:
cd BI_Maintenance/webapps_migration
./migrate_superx_webapp.sh

Das Skript liest die bestehende Installation anhand der vorhandenen SQL_ENV-Datei ein und erzeugt daraus die gewünschte Zielstruktur. Details können in der Konfigurationsdatei
<source lang="text">
migrate_superx.conf
</source>
konfiguriert, siehe folgende Dokumentation.

==Zielstruktur==

Die Webapp wird standardmäßig nicht direkt im Tomcat-Webapp-Verzeichnis abgelegt, sondern unter:

<source lang="text">
/home/superx/webapps/superx
</source>

Dadurch bleibt die Installation unabhängig von der verwendeten Tomcat-Distribution und kann einfacher per Git, rsync oder Modulupdate gepflegt werden.

Die zugehörige DB-Struktur befindet sich anschließend unter:

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

==Tomcat-Anbindung==

Für den Zugriff des Tomcat-Servers auf die Webapp gibt es grundsätzlich zwei Möglichkeiten:

* Verwendung eines symbolischen Links vom Tomcat-Webapp-Verzeichnis auf die eigentliche Webapp.
* Anpassung der Tomcat-Konfiguration (z. B. appBase oder Context-Konfiguration).

Empfohlen wird die Verwendung eines symbolischen Links.

Beispiel:

<source lang="text">
/srv/tomcat/webapps/superx
-> /home/superx/webapps/superx
</source>

==Wichtige Variablen==

Die wichtigsten Einstellungen erfolgen in der Datei:

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

===TARGET_WEBAPP===

Definiert das Zielverzeichnis der Webapp.

Beispiel:

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"
</source>

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Ergebnis:

<source lang="text">
Owner: superx
Group: tomcat
</source>

===MIGRATION_MODE===

Steuert die Art der Migration.

Vollständige Migration:

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

Nur Migration des DB-Verzeichnisses:

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

==Migration des DB-Verzeichnisses==

Das DB-Verzeichnis kann entweder kopiert oder verschoben werden.

===DB_TRANSFER_MODE=copy===

Das bestehende DB-Verzeichnis bleibt erhalten.

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

Intern wird hierfür rsync verwendet.

===DB_TRANSFER_MODE=move===

Das DB-Verzeichnis wird verschoben.

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

Intern wird hierfür mv verwendet. Ist das Zielverzeichnis bereits vorhanden und
<code>ALLOW_EXISTING_TARGET_DB="true"</code> gesetzt, wird das vorhandene Ziel-DB-Verzeichnis vor dem Verschieben vollständig ersetzt. Damit verbleiben keine alten Dateien im Ziel.

Dies ist der empfohlene Standard für die Migration klassischer SuperX-Installationen und vermeidet unnötigen zusätzlichen Speicherbedarf.

==Automatische Anpassung der SQL_ENV==

Nach der Migration kann die SQL_ENV-Datei automatisch angepasst werden.

Dabei werden insbesondere folgende Variablen aktualisiert:

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

Zusätzlich wird sichergestellt, dass folgende Einstellung vorhanden ist:

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

Vor der Änderung wird automatisch eine Sicherungskopie der SQL_ENV-Datei angelegt.

==Benutzer und Gruppen==

Die folgenden Variablen steuern, welchem Benutzer und welcher Gruppe die Ziel-Webapp nach der Migration zugeordnet wird.

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

Alle Dateien und Verzeichnisse der Ziel-Webapp werden diesem Benutzer zugeordnet, sofern die Rechteverwaltung aktiviert ist.

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Die Gruppe wird für alle Dateien und Verzeichnisse der Ziel-Webapp verwendet.

Durch das gesetzte setgid-Bit auf den Verzeichnissen erben neu angelegte Dateien und Unterverzeichnisse automatisch diese Gruppe.

==Automatische Rechtebehandlung==

Die Migration kann sowohl als root als auch – unter bestimmten Voraussetzungen – direkt als Anwendungsbenutzer ausgeführt werden.

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

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

Das Skript entscheidet abhängig vom aktuellen Benutzer automatisch, ob ein Besitzerwechsel erforderlich ist.

====Ausführung als root====

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe der Ziel-Webapp auf die konfigurierten Werte gesetzt.

<source lang="bash">
chown -R $WEBAPP_USER:$WEBAPP_GROUP ...
</source>

Zusätzlich wird auch das übergeordnete Verzeichnis der Webapp (z. B. /home/superx/webapps) auf die gleichen Besitz- und Gruppenrechte gesetzt.

====Ausführung als WEBAPP_USER====

Wird das Skript direkt als der konfigurierte WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der konfigurierten WEBAPP_GROUP, wird kein chown ausgeführt.

Stattdessen verwendet das Skript bei Bedarf ein chgrp, um die Gruppenzugehörigkeit der Dateien anzupassen.

In diesem Fall kann die Migration häufig vollständig ohne root-Rechte durchgeführt werden.

====Ausführung als anderer Benutzer====

Wird das Skript weder als root noch als WEBAPP_USER mit passender Gruppenmitgliedschaft ausgeführt, bricht das Skript mit einer entsprechenden Fehlermeldung ab.

===ADD_WEBAPP_USER_TO_GROUP===

Optional kann das Skript die Gruppenmitgliedschaft des Zielbenutzers automatisch anpassen.

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

Hierfür sind root-Rechte erforderlich.

==Tomcat-Symlink==

Optional kann das Skript den Symlink für den Tomcat automatisch erzeugen.

===CREATE_TOMCAT_SYMLINK===

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

===TOMCAT_WEBAPPS_DIR===

<source lang="bash">
TOMCAT_WEBAPPS_DIR="/srv/tomcat/webapps"
</source>

===TOMCAT_CONTEXT_NAME===

<source lang="bash">
TOMCAT_CONTEXT_NAME="superx"
</source>

===REPLACE_EXISTING_SYMLINK===

Bestehende Symlinks können bei Bedarf automatisch ersetzt werden.

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

Normale Dateien oder Verzeichnisse werden dabei niemals automatisch gelöscht.

==Sicherheitsprüfungen==

Vor Beginn der Migration werden verschiedene Sicherheitsprüfungen durchgeführt.

Unter anderem wird geprüft:

* Existiert die SQL_ENV-Datei?
* Existiert der konfigurierte Benutzer?
* Existiert die konfigurierte Gruppe?
* Sind Quell- und Zielverzeichnis identisch?
* Würde eine Verzeichnisverschachtelung entstehen?
* Befindet sich SUPERX_DIR bereits innerhalb von WEBAPP?

Wird erkannt, dass die Installation bereits der neuen Struktur entspricht, bricht das Skript standardmäßig ab.

===FORCE_ALREADY_MIGRATED===

In Ausnahmefällen kann diese Prüfung übersteuert werden.

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

Dies sollte nur verwendet werden, wenn die Auswirkungen bekannt sind.

==Typischer Ablauf==

# Laden der migrate_superx.conf
# Laden der bestehenden SQL_ENV
# Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
# Sicherheitsprüfungen
# Optionales Stoppen des Tomcat-Dienstes
# Kopieren der Webapp
# Kopieren oder Verschieben des DB-Verzeichnisses
# Anpassen der SQL_ENV
# Setzen von Besitzern, Gruppen und Rechten
# Optionales Erzeugen des Tomcat-Symlinks
# Optionales Starten des Tomcat-Dienstes

==Empfohlene Standardkonfiguration==

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"

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

CREATE_TOMCAT_SYMLINK="true"
</source>

==Hinweise==

* Standardziel ist /home/superx/webapps/superx.
* Die Tomcat-Anbindung kann über einen Symlink erfolgen.
* Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen, sofern der Benutzer Mitglied der Gruppe tomcat ist.
* Root wird nur benötigt, wenn Besitzer geändert, Benutzer oder Gruppen angepasst oder Systemkonfigurationen verändert werden müssen.

Kernmodul Regelbetrieb

2026-10-01T15:11:55Z

Andrek: /* Module Updates */

=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 die automatische Ausführung==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript. Dieses kann sowohl über einen klassischen Cronjob als auch über einen systemd-Service gestartet werden.

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>, zum Update-Skript und zur Logdatei anpassen.

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>
* Umleitung der Ausgabe in die konfigurierte Logdatei

===Ausführung über Cron===
Für die regelmäßige Ausführung kann beispielsweise ein Cronjob eingerichtet werden, der das Update werktags um 18 Uhr startet:

<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Der Cronjob sollte unter dem Benutzer ausgeführt werden, unter dem auch die BI-Installation betrieben wird, üblicherweise <code>superx</code>.

===Ausführung über systemd===
Alternativ zum klassischen Cronjob kann die Laderoutine über einen systemd-Service und einen systemd-Timer ausgeführt werden.

Im Verzeichnis

<source lang="text">
update/systemd/
</source>

werden hierfür die beiden Beispieldateien

<source lang="text">
superx_update.service
superx_update.timer
</source>

bereitgestellt.

Der Service führt das Wrapper-Skript <code>modules_update_cron.sh</code> unter dem Benutzer <code>superx</code> aus.

Beispiel <code>superx_update.service</code>:

<source lang="ini">
[Unit]
Description=SuperX BI Laderoutine

[Service]
Type=oneshot
User=superx
Group=superx
WorkingDirectory=/home/superx
ExecStart=/bin/bash /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update/modules_update_cron.sh
</source>

Die Pfade sowie Benutzer und Gruppe müssen bei Bedarf an die lokale Installation angepasst werden.

Durch den expliziten Aufruf über <code>/bin/bash</code> können insbesondere auf Systemen mit SELinux Probleme bei der direkten Ausführung von Skripten aus Benutzerverzeichnissen vermieden werden.

Der zugehörige Timer legt fest, wann der Service gestartet wird.

Beispiel <code>superx_update.timer</code>:

<source lang="ini">
[Unit]
Description=Timer für SuperX BI Laderoutine

[Timer]
OnCalendar=Mon..Fri *-*-* 18:00:00
Unit=superx_update.service

# Optional:
# Verpassten Lauf nach Server-Neustart nachholen:
# Persistent=true

[Install]
WantedBy=timers.target
</source>

Im Beispiel wird die Laderoutine montags bis freitags jeweils um 18 Uhr ausgeführt. Der Zeitplan kann über <code>OnCalendar</code> an die lokalen Anforderungen angepasst werden.

Die beiden Dateien werden nach <code>/etc/systemd/system</code> kopiert:

<source lang="bash">
cp systemd/superx_update.service /etc/systemd/system/
cp systemd/superx_update.timer /etc/systemd/system/
</source>

Anschließend wird die systemd-Konfiguration neu eingelesen und der Timer aktiviert:

<source lang="bash">
systemctl daemon-reload
systemctl enable --now superx_update.timer
</source>

Der Status des Timers und die nächste geplante Ausführung können anschließend geprüft werden:

<source lang="bash">
systemctl status superx_update.timer
systemctl list-timers --all | grep superx
</source>

Der Service kann unabhängig vom Timer auch manuell gestartet und geprüft werden:

<source lang="bash">
systemctl start superx_update.service
systemctl status superx_update.service
</source>

Der <code>superx_update.service</code> selbst muss nicht mit <code>systemctl enable</code> aktiviert werden. Er wird bei Bedarf durch den Timer gestartet.

Optional kann im Timer

<source lang="ini">
Persistent=true
</source>

gesetzt werden. In diesem Fall holt systemd einen verpassten Lauf nach, beispielsweise wenn der Server zum geplanten Ausführungszeitpunkt ausgeschaltet war. Ob dieses Verhalten gewünscht ist, sollte für die jeweilige Installation entschieden werden.

----

=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=

Das bereitgestellte Migrationsskript ermöglicht die Umstellung einer bestehenden SuperX-Installation auf die empfohlene Webapp-Struktur.

Dabei können sowohl klassische Installationen mit separatem DB-Verzeichnis als auch bestehende Webapp-Installationen migriert werden. Die Migration kann je nach Anwendungsfall vollständig oder ausschließlich für das DB-Verzeichnis durchgeführt werden.
Hier eine Anleitung "in short", wenn Sie bisher das "klasssische" Layout genutzt haben (also Unix Benutzer "superx", Installation in "/home/superx").

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git
#Script ausführen und neues ENV laden:
cd BI_Maintenance/webapps_migration
./migrate_superx_webapp.sh

Das Skript liest die bestehende Installation anhand der vorhandenen SQL_ENV-Datei ein und erzeugt daraus die gewünschte Zielstruktur. Details können in der Konfigurationsdatei
<source lang="text">
migrate_superx.conf
</source>
konfiguriert, siehe folgende Dokumentation.

==Zielstruktur==

Die Webapp wird standardmäßig nicht direkt im Tomcat-Webapp-Verzeichnis abgelegt, sondern unter:

<source lang="text">
/home/superx/webapps/superx
</source>

Dadurch bleibt die Installation unabhängig von der verwendeten Tomcat-Distribution und kann einfacher per Git, rsync oder Modulupdate gepflegt werden.

Die zugehörige DB-Struktur befindet sich anschließend unter:

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

==Tomcat-Anbindung==

Für den Zugriff des Tomcat-Servers auf die Webapp gibt es grundsätzlich zwei Möglichkeiten:

* Verwendung eines symbolischen Links vom Tomcat-Webapp-Verzeichnis auf die eigentliche Webapp.
* Anpassung der Tomcat-Konfiguration (z. B. appBase oder Context-Konfiguration).

Empfohlen wird die Verwendung eines symbolischen Links.

Beispiel:

<source lang="text">
/srv/tomcat/webapps/superx
-> /home/superx/webapps/superx
</source>

==Wichtige Variablen==

Die wichtigsten Einstellungen erfolgen in der Datei:

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

===TARGET_WEBAPP===

Definiert das Zielverzeichnis der Webapp.

Beispiel:

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"
</source>

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Ergebnis:

<source lang="text">
Owner: superx
Group: tomcat
</source>

===MIGRATION_MODE===

Steuert die Art der Migration.

Vollständige Migration:

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

Nur Migration des DB-Verzeichnisses:

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

==Migration des DB-Verzeichnisses==

Das DB-Verzeichnis kann entweder kopiert oder verschoben werden.

===DB_TRANSFER_MODE=copy===

Das bestehende DB-Verzeichnis bleibt erhalten.

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

Intern wird hierfür rsync verwendet.

===DB_TRANSFER_MODE=move===

Das DB-Verzeichnis wird verschoben.

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

Intern wird hierfür mv verwendet. Ist das Zielverzeichnis bereits vorhanden und
<code>ALLOW_EXISTING_TARGET_DB="true"</code> gesetzt, wird das vorhandene Ziel-DB-Verzeichnis vor dem Verschieben vollständig ersetzt. Damit verbleiben keine alten Dateien im Ziel.

Dies ist der empfohlene Standard für die Migration klassischer SuperX-Installationen und vermeidet unnötigen zusätzlichen Speicherbedarf.

==Automatische Anpassung der SQL_ENV==

Nach der Migration kann die SQL_ENV-Datei automatisch angepasst werden.

Dabei werden insbesondere folgende Variablen aktualisiert:

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

Zusätzlich wird sichergestellt, dass folgende Einstellung vorhanden ist:

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

Vor der Änderung wird automatisch eine Sicherungskopie der SQL_ENV-Datei angelegt.

==Benutzer und Gruppen==

Die folgenden Variablen steuern, welchem Benutzer und welcher Gruppe die Ziel-Webapp nach der Migration zugeordnet wird.

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

Alle Dateien und Verzeichnisse der Ziel-Webapp werden diesem Benutzer zugeordnet, sofern die Rechteverwaltung aktiviert ist.

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Die Gruppe wird für alle Dateien und Verzeichnisse der Ziel-Webapp verwendet.

Durch das gesetzte setgid-Bit auf den Verzeichnissen erben neu angelegte Dateien und Unterverzeichnisse automatisch diese Gruppe.

==Automatische Rechtebehandlung==

Die Migration kann sowohl als root als auch – unter bestimmten Voraussetzungen – direkt als Anwendungsbenutzer ausgeführt werden.

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

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

Das Skript entscheidet abhängig vom aktuellen Benutzer automatisch, ob ein Besitzerwechsel erforderlich ist.

====Ausführung als root====

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe der Ziel-Webapp auf die konfigurierten Werte gesetzt.

<source lang="bash">
chown -R $WEBAPP_USER:$WEBAPP_GROUP ...
</source>

Zusätzlich wird auch das übergeordnete Verzeichnis der Webapp (z. B. /home/superx/webapps) auf die gleichen Besitz- und Gruppenrechte gesetzt.

====Ausführung als WEBAPP_USER====

Wird das Skript direkt als der konfigurierte WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der konfigurierten WEBAPP_GROUP, wird kein chown ausgeführt.

Stattdessen verwendet das Skript bei Bedarf ein chgrp, um die Gruppenzugehörigkeit der Dateien anzupassen.

In diesem Fall kann die Migration häufig vollständig ohne root-Rechte durchgeführt werden.

====Ausführung als anderer Benutzer====

Wird das Skript weder als root noch als WEBAPP_USER mit passender Gruppenmitgliedschaft ausgeführt, bricht das Skript mit einer entsprechenden Fehlermeldung ab.

===ADD_WEBAPP_USER_TO_GROUP===

Optional kann das Skript die Gruppenmitgliedschaft des Zielbenutzers automatisch anpassen.

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

Hierfür sind root-Rechte erforderlich.

==Tomcat-Symlink==

Optional kann das Skript den Symlink für den Tomcat automatisch erzeugen.

===CREATE_TOMCAT_SYMLINK===

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

===TOMCAT_WEBAPPS_DIR===

<source lang="bash">
TOMCAT_WEBAPPS_DIR="/srv/tomcat/webapps"
</source>

===TOMCAT_CONTEXT_NAME===

<source lang="bash">
TOMCAT_CONTEXT_NAME="superx"
</source>

===REPLACE_EXISTING_SYMLINK===

Bestehende Symlinks können bei Bedarf automatisch ersetzt werden.

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

Normale Dateien oder Verzeichnisse werden dabei niemals automatisch gelöscht.

==Sicherheitsprüfungen==

Vor Beginn der Migration werden verschiedene Sicherheitsprüfungen durchgeführt.

Unter anderem wird geprüft:

* Existiert die SQL_ENV-Datei?
* Existiert der konfigurierte Benutzer?
* Existiert die konfigurierte Gruppe?
* Sind Quell- und Zielverzeichnis identisch?
* Würde eine Verzeichnisverschachtelung entstehen?
* Befindet sich SUPERX_DIR bereits innerhalb von WEBAPP?

Wird erkannt, dass die Installation bereits der neuen Struktur entspricht, bricht das Skript standardmäßig ab.

===FORCE_ALREADY_MIGRATED===

In Ausnahmefällen kann diese Prüfung übersteuert werden.

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

Dies sollte nur verwendet werden, wenn die Auswirkungen bekannt sind.

==Typischer Ablauf==

# Laden der migrate_superx.conf
# Laden der bestehenden SQL_ENV
# Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
# Sicherheitsprüfungen
# Optionales Stoppen des Tomcat-Dienstes
# Kopieren der Webapp
# Kopieren oder Verschieben des DB-Verzeichnisses
# Anpassen der SQL_ENV
# Setzen von Besitzern, Gruppen und Rechten
# Optionales Erzeugen des Tomcat-Symlinks
# Optionales Starten des Tomcat-Dienstes

==Empfohlene Standardkonfiguration==

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"

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

CREATE_TOMCAT_SYMLINK="true"
</source>

==Hinweise==

* Standardziel ist /home/superx/webapps/superx.
* Die Tomcat-Anbindung kann über einen Symlink erfolgen.
* Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen, sofern der Benutzer Mitglied der Gruppe tomcat ist.
* Root wird nur benötigt, wenn Besitzer geändert, Benutzer oder Gruppen angepasst oder Systemkonfigurationen verändert werden müssen.

SuperX REST Schnittstelle

2026-09-22T08:15:50Z

Andrek: /* Übersicht der wichtigsten Masken- und Berichtsaufrufe */

=REST-Schnittstelle=

Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.

Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.

Zu den wichtigsten Einsatzbereichen gehören:

* Komponentenverwaltung und ETL-Jobs
* Status- und Protokollabfragen
* SuperX-Masken und deren Eingabefelder
* Ausführung von Masken und Abruf der Ergebnistabellen
* Export von Berichtsergebnissen
* Einbindung von SuperX-Funktionen in eigene Weboberflächen

In den folgenden Beispielen wird diese Beispielinstallation verwendet:

<source lang="text">
https://demo.superx-testserver.de/superx/
</source>

Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.

==Grundlagen==

Die REST-Endpunkte befinden sich unterhalb von:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/
</source>

Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.

Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.

==Einrichtung und Voraussetzungen==

Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.

Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:

* die SuperX-Webapp ist über Tomcat erreichbar,
* die Datenbankverbindung funktioniert,
* ein aktueller Kernstand ist installiert,
* die benötigten Modulverzeichnisse sind eingebunden,
* die ETL- und Jobdefinitionen wurden eingelesen.

===Aktuelles Kernpaket verwenden===

Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.

Beispiel:

<source lang="bash">
wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz
</source>

Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in <code>WEB-INF/lib</code> liegen bleiben.

Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.

Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden:

<source lang="text">
WEB-INF/classes/spring-batch.properties
WEB-INF/classes/hikari.properties
WEB-INF/classes/quartz.properties
</source>

===Datenbankverbindung prüfen===

Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der <code>dbforms-config.xml</code> sollte der <code>SpringBeanConnectionProvider</code> verwendet werden:

<source lang="xml">
<dbconnection connectionProviderClass="de.superx.db.SpringBeanConnectionProvider"
default="true"
id="datasourceBean"
isJndi="false"
isPow2="true"/>
</source>

Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.

===module_ignore.properties prüfen===

Für die Komponentenverwaltung muss folgende Datei vorhanden sein:

<source lang="text">
WEB-INF/conf/edustore/db/module/module_ignore.properties
</source>

Beispielinhalt:

<source lang="text">
ignore.modules=kennx,gxstage,bil
</source>

Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.

===Modulverzeichnisse bereitstellen===

Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus:

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

Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.

Beispiel:

<source lang="bash">
cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
</source>

===Zusätzliche Kern-ETL-Dateien prüfen===

Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.

Quellverzeichnis im SuperX-Git:

<source lang="text">
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>

Zielverzeichnis in der Webapp:

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

Benötigte Dateien:

* edustore_kern_man_unload_config_ids.xml
* edustore_kern_man_unload_config_pg.xml
* edustore_kern_man_upload_config_ids.xml
* edustore_kern_man_upload_config_pg.xml

Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.

===ETL-Steuerdaten einlesen===

Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -r
</source>

Der Parameter <code>-r</code> liest die Komponenten- und Jobdefinitionen neu ein.

Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb
</source>

===Einzelnen Job über die CLI testen===

Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
</source>

Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.

===Tomcat neu starten===

Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.

Beispiel:

<source lang="bash">
systemctl restart tomcat10
</source>

Je nach Installation kann der Dienst auch anders heißen.

===REST-Schnittstelle prüfen===

Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/list
</source>

Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.

Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

===Fehlersuche bei der Einrichtung===

Bei Problemen sollten insbesondere folgende Punkte geprüft werden:

{| class="wikitable"
!Problem!!Prüfung
|-
|REST-Endpunkt liefert HTTP 500
|Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren.
|-
|Komponentenliste ist leer oder fehlerhaft
|Modulverzeichnis und <code>module_ignore.properties</code> prüfen.
|-
|Jobs fehlen
|ETL-Steuerdaten mit <code>ComponentAdminCLI -r</code> oder über <code>/etl/job/writeJobsToDb</code> neu einlesen.
|-
|Job funktioniert über REST nicht
|Denselben Job testweise über die CLI starten und Tomcat-Log prüfen.
|-
|Spezialjobs fehlen
|Zusätzliche ETL-XML-Dateien im Verzeichnis <code>edustore_update</code> prüfen.
|-
|REST-Aufruf funktioniert nach einem Upgrade nicht
|Bibliotheken in <code>WEB-INF/lib</code> sowie <code>spring-batch.properties</code>, <code>hikari.properties</code> und <code>quartz.properties</code> prüfen.
|-
|POST auf eine Maske liefert "Required request body is missing"
|Einen JSON-Body mitsenden, mindestens <code>{}</code>.
|-
|POST liefert "application/octet-stream is not supported"
|Header <code>Content-Type: application/json</code> setzen.
|}

In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.

==Komponentenverwaltung und ETL==

Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.

Der Basis-Pfad lautet:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl
</source>

===Übersicht der wichtigsten ETL-Aufrufe===

Die in der Tabelle angegebenen Aufrufe sind relativ zu der Basis-URL. Ein vollständiger Aufruf sieht zum Beispiel so aus:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>

{| class="wikitable"
!Funktion
!Methode
!Aufruf
!Zweck
|-
|Komponenten anzeigen
|GET
|<code>ds/api/etl/list</code>
|Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen.
|-
|Installierbare Komponenten
|GET
|<code>ds/api/etl/installables/list</code>
|Zeigt Komponenten, die grundsätzlich installiert werden können.
|-
|Alle ETL-Jobs
|GET
|<code>ds/api/etl/job/list</code>
|Liefert alle bekannten ETL- und Batch-Jobs.
|-
|Jobs einer Komponente
|GET
|<code>ds/api/etl/job/list/hrstage</code>
|Zeigt nur die Jobs einer bestimmten Komponente.
|-
|Jobdetails
|GET
|<code>ds/api/etl/job/hrstage_load_and_transform</code>
|Liefert technische Informationen zu einem bestimmten Job.
|-
|Jobdefinitionen neu einlesen
|GET
|<code>ds/api/etl/job/writeJobsToDb</code>
|Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein.
|-
|Job starten
|GET
|<code>ds/api/etl/job/execute/eduetl/hrstage_load_and_transform</code>
|Startet einen bestimmten Job und liefert eine JobExecutionId zurück.
|-
|Installation starten
|GET
|<code>ds/api/etl/job/install/hrstage</code>
|Startet die Installation einer Komponente.
|-
|Upgrade starten
|GET
|<code>ds/api/etl/job/upgrade/hrstage</code>
|Startet ein Upgrade einer installierten Komponente.
|-
|Alle Upgrades starten
|GET
|<code>ds/api/etl/job/upgrade_all</code>
|Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten.
|-
|Komponente deinstallieren
|GET
|<code>ds/api/etl/job/uninstall/hrstage</code>
|Startet die Deinstallation einer Komponente.
|-
|Unload starten
|GET
|<code>ds/api/etl/unload/hrstage</code>
|Startet den Unload einer Komponente.
|-
|Transform starten
|GET
|<code>ds/api/etl/transform/hrstage</code>
|Startet die Transformation bereits vorhandener Daten.
|-
|Complete starten
|GET
|<code>ds/api/etl/complete/hrstage</code>
|Startet modulabhängige Abschlussarbeiten.
|-
|Installationsfunktionen
|GET
|<code>ds/api/etl/installFunctions/hrstage</code>
|Zeigt zusätzliche Installationsfunktionen einer Komponente.
|-
|Laufende Jobs
|GET
|<code>ds/api/etl/running</code>
|Zeigt aktuell laufende Jobs.
|-
|Jobstatus
|GET
|<code>ds/api/etl/jobExecutionStatus/12345</code>
|Liefert den aktuellen Status einer Jobausführung.
|-
|Joblog
|GET
|<code>ds/api/etl/jobLog/12345</code>
|Liefert das Protokoll einer Jobausführung.
|-
|Jobausführungen
|GET
|<code>ds/api/etl/jobExecutionInfos</code>
|Liefert Informationen zu Jobausführungen.
|-
|Job stoppen
|GET
|<code>ds/api/etl/stop/12345</code>
|Stoppt eine bestimmte Jobausführung.
|-
|Job starten oder fortsetzen
|GET
|<code>ds/api/etl/start/12345</code>
|Spricht eine vorhandene Jobausführung erneut an.
|-
|Alle Jobs stoppen
|GET
|<code>ds/api/etl/job/stopAll</code>
|Stoppt alle laufenden Jobs.
|}

===Typischer ETL-Ablauf===

Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.

Ein typischer Ablauf für ein Modulupdate ist:

<source lang="text">
1. Komponenten laden
/etl/list

2. Jobs des Moduls laden
/etl/job/list/hrstage

3. Gewünschten Job starten
/etl/job/execute/eduetl/hrstage_unload_load_transform

4. Jobstatus abfragen
/etl/jobExecutionStatus/12345

5. Jobprotokoll anzeigen
/etl/jobLog/12345
</source>

Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.

Spezialjobs wie beispielsweise

<source lang="text">
kern_unload_config_special
kern_upload_config_special
</source>

können ebenfalls über den generischen Execute-Endpunkt gestartet werden.

==SuperX-Masken und Berichte==

Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.

Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.

===Übersicht der wichtigsten Masken- und Berichtsaufrufe===

Die in der Tabelle angegebenen Aufrufe sind relativ zu der Basis-URL. Ein vollständiger Aufruf sieht zum Beispiel so aus:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

{| class="wikitable"
!Funktion
!Methode
!Aufruf
!Zweck
|-
|Maskenaufbau laden
|GET
|<code>ds/api/form/71030</code>
|Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften.
|-
|Abhängige Felder aktualisieren
|POST
|<code>ds/api/form/71030/inputupdate</code>
|Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu.
|-
|Informationen zur Maske
|GET
|<code>ds/api/report?tid=71030</code>
|Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet.
|-
|Maske ausführen
|POST
|<code>ds/api/report?tid=71030</code>
|Führt die Maske aus und liefert die Ergebnistabelle als JSON.
|-
|Ergebnis-Stylesheets
|GET
|<code>ds/api/report/stylesheets?tid=71030</code>
|Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets.
|-
|Sichten eines Feldes
|GET
|<code>ds/api/report/views?tid=71030&fieldName=Institution</code>
|Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes.
|-
|Inhalt einer Sicht
|GET
|<code>ds/api/report/view?tid=71030&fieldName=Institution&viewId=...</code>
|Liefert den Inhalt einer bestimmten Sicht.
|-
|Bericht herunterladen
|POST
|<code>ds/api/report/download?tid=71030</code>
|Erzeugt einen Export des Berichtsergebnisses.
|-
|Themenbaum
|GET
|<code>ds/api/menu/tree</code>
|Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum.
|-
|Teil des Themenbaums
|GET
|<code>ds/api/menu?tid=71030</code>
|Liefert einen bestimmten Bereich des Themenbaums.
|}

===Masken verwenden===

Der Aufruf

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

liefert unter anderem:

* Namen der Eingabefelder
* Feldtypen
* Beschriftungen
* Pflichtfelder
* Defaultwerte
* Auswahllisten
* Baum- beziehungsweise TreeSelect-Inhalte
* verfügbare Stylesheets

Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.

Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet:

<source lang="text">
POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030
</source>

Der Request benötigt:

<source lang="text">
Content-Type: application/json
</source>

Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden:

<source lang="json">
{}
</source>

Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.

Beispiel:

<source lang="json">
{
"Kennung": "admin",
"Gruppe": "",
"Name": "",
"Institution": ""
}
</source>

Die Antwort enthält die Ergebnistabelle als JSON.

===POST-Aufruf im Browser testen===

GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.

Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:

# Entwicklertools mit F12 öffnen.
# ''Netzwerkanalyse'' auswählen.
# Einen REST-Aufruf markieren und ''Bearbeiten und erneut senden'' auswählen.
# Methode von GET auf POST ändern.
# Header ergänzen:
#:<code>Content-Type: application/json</code>
# Unter ''Inhalt'' mindestens folgenden JSON-Body eintragen:
#:<code>{}</code>
# Anfrage senden.

Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu:

<source lang="text">
Content-Type: application/json
Content-Length: 2
</source>

Typische Fehler:

{| class="wikitable"
!Fehler!!Ursache!!Lösung
|-
|<code>Required request body is missing</code>
|Der POST-Request enthält keinen Body.
|Mindestens <code>{}</code> als Inhalt mitsenden.
|-
|<code>Content-Type 'application/octet-stream' is not supported</code>
|Der Body wird ohne passenden Content-Type übertragen.
|<code>Content-Type: application/json</code> setzen.
|}

==Hinweise zur Verwendung==

REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.

Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.

Für die Komponentenverwaltung sind insbesondere die Kombinationen aus

<source lang="text">
/etl/list
/etl/job/list/{component}
</source>

und für Masken

<source lang="text">
/form/{tid}
/report?tid={tid}
</source>

relevant.

SuperX REST Schnittstelle

2026-09-22T08:14:11Z

Andrek: /* Übersicht der wichtigsten ETL-Aufrufe */

=REST-Schnittstelle=

Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.

Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.

Zu den wichtigsten Einsatzbereichen gehören:

* Komponentenverwaltung und ETL-Jobs
* Status- und Protokollabfragen
* SuperX-Masken und deren Eingabefelder
* Ausführung von Masken und Abruf der Ergebnistabellen
* Export von Berichtsergebnissen
* Einbindung von SuperX-Funktionen in eigene Weboberflächen

In den folgenden Beispielen wird diese Beispielinstallation verwendet:

<source lang="text">
https://demo.superx-testserver.de/superx/
</source>

Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.

==Grundlagen==

Die REST-Endpunkte befinden sich unterhalb von:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/
</source>

Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.

Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.

==Einrichtung und Voraussetzungen==

Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.

Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:

* die SuperX-Webapp ist über Tomcat erreichbar,
* die Datenbankverbindung funktioniert,
* ein aktueller Kernstand ist installiert,
* die benötigten Modulverzeichnisse sind eingebunden,
* die ETL- und Jobdefinitionen wurden eingelesen.

===Aktuelles Kernpaket verwenden===

Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.

Beispiel:

<source lang="bash">
wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz
</source>

Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in <code>WEB-INF/lib</code> liegen bleiben.

Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.

Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden:

<source lang="text">
WEB-INF/classes/spring-batch.properties
WEB-INF/classes/hikari.properties
WEB-INF/classes/quartz.properties
</source>

===Datenbankverbindung prüfen===

Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der <code>dbforms-config.xml</code> sollte der <code>SpringBeanConnectionProvider</code> verwendet werden:

<source lang="xml">
<dbconnection connectionProviderClass="de.superx.db.SpringBeanConnectionProvider"
default="true"
id="datasourceBean"
isJndi="false"
isPow2="true"/>
</source>

Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.

===module_ignore.properties prüfen===

Für die Komponentenverwaltung muss folgende Datei vorhanden sein:

<source lang="text">
WEB-INF/conf/edustore/db/module/module_ignore.properties
</source>

Beispielinhalt:

<source lang="text">
ignore.modules=kennx,gxstage,bil
</source>

Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.

===Modulverzeichnisse bereitstellen===

Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus:

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

Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.

Beispiel:

<source lang="bash">
cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
</source>

===Zusätzliche Kern-ETL-Dateien prüfen===

Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.

Quellverzeichnis im SuperX-Git:

<source lang="text">
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>

Zielverzeichnis in der Webapp:

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

Benötigte Dateien:

* edustore_kern_man_unload_config_ids.xml
* edustore_kern_man_unload_config_pg.xml
* edustore_kern_man_upload_config_ids.xml
* edustore_kern_man_upload_config_pg.xml

Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.

===ETL-Steuerdaten einlesen===

Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -r
</source>

Der Parameter <code>-r</code> liest die Komponenten- und Jobdefinitionen neu ein.

Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb
</source>

===Einzelnen Job über die CLI testen===

Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
</source>

Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.

===Tomcat neu starten===

Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.

Beispiel:

<source lang="bash">
systemctl restart tomcat10
</source>

Je nach Installation kann der Dienst auch anders heißen.

===REST-Schnittstelle prüfen===

Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/list
</source>

Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.

Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

===Fehlersuche bei der Einrichtung===

Bei Problemen sollten insbesondere folgende Punkte geprüft werden:

{| class="wikitable"
!Problem!!Prüfung
|-
|REST-Endpunkt liefert HTTP 500
|Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren.
|-
|Komponentenliste ist leer oder fehlerhaft
|Modulverzeichnis und <code>module_ignore.properties</code> prüfen.
|-
|Jobs fehlen
|ETL-Steuerdaten mit <code>ComponentAdminCLI -r</code> oder über <code>/etl/job/writeJobsToDb</code> neu einlesen.
|-
|Job funktioniert über REST nicht
|Denselben Job testweise über die CLI starten und Tomcat-Log prüfen.
|-
|Spezialjobs fehlen
|Zusätzliche ETL-XML-Dateien im Verzeichnis <code>edustore_update</code> prüfen.
|-
|REST-Aufruf funktioniert nach einem Upgrade nicht
|Bibliotheken in <code>WEB-INF/lib</code> sowie <code>spring-batch.properties</code>, <code>hikari.properties</code> und <code>quartz.properties</code> prüfen.
|-
|POST auf eine Maske liefert "Required request body is missing"
|Einen JSON-Body mitsenden, mindestens <code>{}</code>.
|-
|POST liefert "application/octet-stream is not supported"
|Header <code>Content-Type: application/json</code> setzen.
|}

In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.

==Komponentenverwaltung und ETL==

Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.

Der Basis-Pfad lautet:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl
</source>

===Übersicht der wichtigsten ETL-Aufrufe===

Die in der Tabelle angegebenen Aufrufe sind relativ zu der Basis-URL. Ein vollständiger Aufruf sieht zum Beispiel so aus:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>

{| class="wikitable"
!Funktion
!Methode
!Aufruf
!Zweck
|-
|Komponenten anzeigen
|GET
|<code>ds/api/etl/list</code>
|Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen.
|-
|Installierbare Komponenten
|GET
|<code>ds/api/etl/installables/list</code>
|Zeigt Komponenten, die grundsätzlich installiert werden können.
|-
|Alle ETL-Jobs
|GET
|<code>ds/api/etl/job/list</code>
|Liefert alle bekannten ETL- und Batch-Jobs.
|-
|Jobs einer Komponente
|GET
|<code>ds/api/etl/job/list/hrstage</code>
|Zeigt nur die Jobs einer bestimmten Komponente.
|-
|Jobdetails
|GET
|<code>ds/api/etl/job/hrstage_load_and_transform</code>
|Liefert technische Informationen zu einem bestimmten Job.
|-
|Jobdefinitionen neu einlesen
|GET
|<code>ds/api/etl/job/writeJobsToDb</code>
|Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein.
|-
|Job starten
|GET
|<code>ds/api/etl/job/execute/eduetl/hrstage_load_and_transform</code>
|Startet einen bestimmten Job und liefert eine JobExecutionId zurück.
|-
|Installation starten
|GET
|<code>ds/api/etl/job/install/hrstage</code>
|Startet die Installation einer Komponente.
|-
|Upgrade starten
|GET
|<code>ds/api/etl/job/upgrade/hrstage</code>
|Startet ein Upgrade einer installierten Komponente.
|-
|Alle Upgrades starten
|GET
|<code>ds/api/etl/job/upgrade_all</code>
|Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten.
|-
|Komponente deinstallieren
|GET
|<code>ds/api/etl/job/uninstall/hrstage</code>
|Startet die Deinstallation einer Komponente.
|-
|Unload starten
|GET
|<code>ds/api/etl/unload/hrstage</code>
|Startet den Unload einer Komponente.
|-
|Transform starten
|GET
|<code>ds/api/etl/transform/hrstage</code>
|Startet die Transformation bereits vorhandener Daten.
|-
|Complete starten
|GET
|<code>ds/api/etl/complete/hrstage</code>
|Startet modulabhängige Abschlussarbeiten.
|-
|Installationsfunktionen
|GET
|<code>ds/api/etl/installFunctions/hrstage</code>
|Zeigt zusätzliche Installationsfunktionen einer Komponente.
|-
|Laufende Jobs
|GET
|<code>ds/api/etl/running</code>
|Zeigt aktuell laufende Jobs.
|-
|Jobstatus
|GET
|<code>ds/api/etl/jobExecutionStatus/12345</code>
|Liefert den aktuellen Status einer Jobausführung.
|-
|Joblog
|GET
|<code>ds/api/etl/jobLog/12345</code>
|Liefert das Protokoll einer Jobausführung.
|-
|Jobausführungen
|GET
|<code>ds/api/etl/jobExecutionInfos</code>
|Liefert Informationen zu Jobausführungen.
|-
|Job stoppen
|GET
|<code>ds/api/etl/stop/12345</code>
|Stoppt eine bestimmte Jobausführung.
|-
|Job starten oder fortsetzen
|GET
|<code>ds/api/etl/start/12345</code>
|Spricht eine vorhandene Jobausführung erneut an.
|-
|Alle Jobs stoppen
|GET
|<code>ds/api/etl/job/stopAll</code>
|Stoppt alle laufenden Jobs.
|}

===Typischer ETL-Ablauf===

Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.

Ein typischer Ablauf für ein Modulupdate ist:

<source lang="text">
1. Komponenten laden
/etl/list

2. Jobs des Moduls laden
/etl/job/list/hrstage

3. Gewünschten Job starten
/etl/job/execute/eduetl/hrstage_unload_load_transform

4. Jobstatus abfragen
/etl/jobExecutionStatus/12345

5. Jobprotokoll anzeigen
/etl/jobLog/12345
</source>

Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.

Spezialjobs wie beispielsweise

<source lang="text">
kern_unload_config_special
kern_upload_config_special
</source>

können ebenfalls über den generischen Execute-Endpunkt gestartet werden.

==SuperX-Masken und Berichte==

Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.

Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.

===Übersicht der wichtigsten Masken- und Berichtsaufrufe===

{| class="wikitable"
!Funktion
!Methode
!Beispiel
!Zweck
|-
|Maskenaufbau laden
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030</code>
|Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften.
|-
|Abhängige Felder aktualisieren
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030/inputupdate</code>
|Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu.
|-
|Informationen zur Maske
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet.
|-
|Maske ausführen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Führt die Maske aus und liefert die Ergebnistabelle als JSON.
|-
|Ergebnis-Stylesheets
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/stylesheets?tid=71030</code>
|Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets.
|-
|Sichten eines Feldes
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/views?tid=71030&fieldName=Institution</code>
|Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes.
|-
|Inhalt einer Sicht
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/view?tid=71030&fieldName=Institution&viewId=...</code>
|Liefert den Inhalt einer bestimmten Sicht.
|-
|Bericht herunterladen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report/download?tid=71030</code>
|Erzeugt einen Export des Berichtsergebnisses.
|-
|Themenbaum
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu/tree</code>
|Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum.
|-
|Teil des Themenbaums
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu?tid=71030</code>
|Liefert einen bestimmten Bereich des Themenbaums.
|}

===Masken verwenden===

Der Aufruf

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

liefert unter anderem:

* Namen der Eingabefelder
* Feldtypen
* Beschriftungen
* Pflichtfelder
* Defaultwerte
* Auswahllisten
* Baum- beziehungsweise TreeSelect-Inhalte
* verfügbare Stylesheets

Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.

Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet:

<source lang="text">
POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030
</source>

Der Request benötigt:

<source lang="text">
Content-Type: application/json
</source>

Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden:

<source lang="json">
{}
</source>

Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.

Beispiel:

<source lang="json">
{
"Kennung": "admin",
"Gruppe": "",
"Name": "",
"Institution": ""
}
</source>

Die Antwort enthält die Ergebnistabelle als JSON.

===POST-Aufruf im Browser testen===

GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.

Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:

# Entwicklertools mit F12 öffnen.
# ''Netzwerkanalyse'' auswählen.
# Einen REST-Aufruf markieren und ''Bearbeiten und erneut senden'' auswählen.
# Methode von GET auf POST ändern.
# Header ergänzen:
#:<code>Content-Type: application/json</code>
# Unter ''Inhalt'' mindestens folgenden JSON-Body eintragen:
#:<code>{}</code>
# Anfrage senden.

Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu:

<source lang="text">
Content-Type: application/json
Content-Length: 2
</source>

Typische Fehler:

{| class="wikitable"
!Fehler!!Ursache!!Lösung
|-
|<code>Required request body is missing</code>
|Der POST-Request enthält keinen Body.
|Mindestens <code>{}</code> als Inhalt mitsenden.
|-
|<code>Content-Type 'application/octet-stream' is not supported</code>
|Der Body wird ohne passenden Content-Type übertragen.
|<code>Content-Type: application/json</code> setzen.
|}

==Hinweise zur Verwendung==

REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.

Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.

Für die Komponentenverwaltung sind insbesondere die Kombinationen aus

<source lang="text">
/etl/list
/etl/job/list/{component}
</source>

und für Masken

<source lang="text">
/form/{tid}
/report?tid={tid}
</source>

relevant.

SuperX REST Schnittstelle

2026-09-22T08:09:57Z

Andrek:

=REST-Schnittstelle=

Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.

Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.

Zu den wichtigsten Einsatzbereichen gehören:

* Komponentenverwaltung und ETL-Jobs
* Status- und Protokollabfragen
* SuperX-Masken und deren Eingabefelder
* Ausführung von Masken und Abruf der Ergebnistabellen
* Export von Berichtsergebnissen
* Einbindung von SuperX-Funktionen in eigene Weboberflächen

In den folgenden Beispielen wird diese Beispielinstallation verwendet:

<source lang="text">
https://demo.superx-testserver.de/superx/
</source>

Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.

==Grundlagen==

Die REST-Endpunkte befinden sich unterhalb von:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/
</source>

Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.

Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.

==Einrichtung und Voraussetzungen==

Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.

Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:

* die SuperX-Webapp ist über Tomcat erreichbar,
* die Datenbankverbindung funktioniert,
* ein aktueller Kernstand ist installiert,
* die benötigten Modulverzeichnisse sind eingebunden,
* die ETL- und Jobdefinitionen wurden eingelesen.

===Aktuelles Kernpaket verwenden===

Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.

Beispiel:

<source lang="bash">
wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz
</source>

Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in <code>WEB-INF/lib</code> liegen bleiben.

Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.

Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden:

<source lang="text">
WEB-INF/classes/spring-batch.properties
WEB-INF/classes/hikari.properties
WEB-INF/classes/quartz.properties
</source>

===Datenbankverbindung prüfen===

Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der <code>dbforms-config.xml</code> sollte der <code>SpringBeanConnectionProvider</code> verwendet werden:

<source lang="xml">
<dbconnection connectionProviderClass="de.superx.db.SpringBeanConnectionProvider"
default="true"
id="datasourceBean"
isJndi="false"
isPow2="true"/>
</source>

Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.

===module_ignore.properties prüfen===

Für die Komponentenverwaltung muss folgende Datei vorhanden sein:

<source lang="text">
WEB-INF/conf/edustore/db/module/module_ignore.properties
</source>

Beispielinhalt:

<source lang="text">
ignore.modules=kennx,gxstage,bil
</source>

Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.

===Modulverzeichnisse bereitstellen===

Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus:

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

Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.

Beispiel:

<source lang="bash">
cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
</source>

===Zusätzliche Kern-ETL-Dateien prüfen===

Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.

Quellverzeichnis im SuperX-Git:

<source lang="text">
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>

Zielverzeichnis in der Webapp:

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

Benötigte Dateien:

* edustore_kern_man_unload_config_ids.xml
* edustore_kern_man_unload_config_pg.xml
* edustore_kern_man_upload_config_ids.xml
* edustore_kern_man_upload_config_pg.xml

Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.

===ETL-Steuerdaten einlesen===

Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -r
</source>

Der Parameter <code>-r</code> liest die Komponenten- und Jobdefinitionen neu ein.

Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb
</source>

===Einzelnen Job über die CLI testen===

Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.

Beispiel:

<source lang="bash">
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
</source>

Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.

===Tomcat neu starten===

Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.

Beispiel:

<source lang="bash">
systemctl restart tomcat10
</source>

Je nach Installation kann der Dienst auch anders heißen.

===REST-Schnittstelle prüfen===

Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl/job/list
</source>

Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.

Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

===Fehlersuche bei der Einrichtung===

Bei Problemen sollten insbesondere folgende Punkte geprüft werden:

{| class="wikitable"
!Problem!!Prüfung
|-
|REST-Endpunkt liefert HTTP 500
|Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren.
|-
|Komponentenliste ist leer oder fehlerhaft
|Modulverzeichnis und <code>module_ignore.properties</code> prüfen.
|-
|Jobs fehlen
|ETL-Steuerdaten mit <code>ComponentAdminCLI -r</code> oder über <code>/etl/job/writeJobsToDb</code> neu einlesen.
|-
|Job funktioniert über REST nicht
|Denselben Job testweise über die CLI starten und Tomcat-Log prüfen.
|-
|Spezialjobs fehlen
|Zusätzliche ETL-XML-Dateien im Verzeichnis <code>edustore_update</code> prüfen.
|-
|REST-Aufruf funktioniert nach einem Upgrade nicht
|Bibliotheken in <code>WEB-INF/lib</code> sowie <code>spring-batch.properties</code>, <code>hikari.properties</code> und <code>quartz.properties</code> prüfen.
|-
|POST auf eine Maske liefert "Required request body is missing"
|Einen JSON-Body mitsenden, mindestens <code>{}</code>.
|-
|POST liefert "application/octet-stream is not supported"
|Header <code>Content-Type: application/json</code> setzen.
|}

In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.

==Komponentenverwaltung und ETL==

Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.

Der Basis-Pfad lautet:

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/etl
</source>

===Übersicht der wichtigsten ETL-Aufrufe===

{| class="wikitable"
!Funktion
!Methode
!Beispiel
!Zweck
|-
|Komponenten anzeigen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/list</code>
|Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen.
|-
|Installierbare Komponenten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/installables/list</code>
|Zeigt Komponenten, die grundsätzlich installiert werden können.
|-
|Alle ETL-Jobs
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/list</code>
|Liefert alle bekannten ETL- und Batch-Jobs.
|-
|Jobs einer Komponente
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/list/hrstage</code>
|Zeigt nur die Jobs einer bestimmten Komponente.
|-
|Jobdetails
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/hrstage_load_and_transform</code>
|Liefert technische Informationen zu einem bestimmten Job.
|-
|Jobdefinitionen neu einlesen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb</code>
|Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein.
|-
|Job starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform</code>
|Startet einen bestimmten Job und liefert eine JobExecutionId zurück.
|-
|Installation starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/install/hrstage</code>
|Startet die Installation einer Komponente.
|-
|Upgrade starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade/hrstage</code>
|Startet ein Upgrade einer installierten Komponente.
|-
|Alle Upgrades starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade_all</code>
|Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten.
|-
|Komponente deinstallieren
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/uninstall/hrstage</code>
|Startet die Deinstallation einer Komponente.
|-
|Unload starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/unload/hrstage</code>
|Startet den Unload einer Komponente.
|-
|Transform starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/transform/hrstage</code>
|Startet die Transformation bereits vorhandener Daten.
|-
|Complete starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/complete/hrstage</code>
|Startet modulabhängige Abschlussarbeiten.
|-
|Installationsfunktionen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/installFunctions/hrstage</code>
|Zeigt zusätzliche Installationsfunktionen einer Komponente.
|-
|Laufende Jobs
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/running</code>
|Zeigt aktuell laufende Jobs.
|-
|Jobstatus
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionStatus/12345</code>
|Liefert den aktuellen Status einer Jobausführung.
|-
|Joblog
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobLog/12345</code>
|Liefert das Protokoll einer Jobausführung.
|-
|Jobausführungen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionInfos</code>
|Liefert Informationen zu Jobausführungen.
|-
|Job stoppen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/stop/12345</code>
|Stoppt eine bestimmte Jobausführung.
|-
|Job starten oder fortsetzen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/start/12345</code>
|Spricht eine vorhandene Jobausführung erneut an.
|-
|Alle Jobs stoppen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/stopAll</code>
|Stoppt alle laufenden Jobs.
|}

===Typischer ETL-Ablauf===

Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.

Ein typischer Ablauf für ein Modulupdate ist:

<source lang="text">
1. Komponenten laden
/etl/list

2. Jobs des Moduls laden
/etl/job/list/hrstage

3. Gewünschten Job starten
/etl/job/execute/eduetl/hrstage_unload_load_transform

4. Jobstatus abfragen
/etl/jobExecutionStatus/12345

5. Jobprotokoll anzeigen
/etl/jobLog/12345
</source>

Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.

Spezialjobs wie beispielsweise

<source lang="text">
kern_unload_config_special
kern_upload_config_special
</source>

können ebenfalls über den generischen Execute-Endpunkt gestartet werden.

==SuperX-Masken und Berichte==

Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.

Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.

===Übersicht der wichtigsten Masken- und Berichtsaufrufe===

{| class="wikitable"
!Funktion
!Methode
!Beispiel
!Zweck
|-
|Maskenaufbau laden
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030</code>
|Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften.
|-
|Abhängige Felder aktualisieren
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030/inputupdate</code>
|Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu.
|-
|Informationen zur Maske
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet.
|-
|Maske ausführen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Führt die Maske aus und liefert die Ergebnistabelle als JSON.
|-
|Ergebnis-Stylesheets
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/stylesheets?tid=71030</code>
|Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets.
|-
|Sichten eines Feldes
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/views?tid=71030&fieldName=Institution</code>
|Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes.
|-
|Inhalt einer Sicht
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/view?tid=71030&fieldName=Institution&viewId=...</code>
|Liefert den Inhalt einer bestimmten Sicht.
|-
|Bericht herunterladen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report/download?tid=71030</code>
|Erzeugt einen Export des Berichtsergebnisses.
|-
|Themenbaum
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu/tree</code>
|Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum.
|-
|Teil des Themenbaums
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu?tid=71030</code>
|Liefert einen bestimmten Bereich des Themenbaums.
|}

===Masken verwenden===

Der Aufruf

<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>

liefert unter anderem:

* Namen der Eingabefelder
* Feldtypen
* Beschriftungen
* Pflichtfelder
* Defaultwerte
* Auswahllisten
* Baum- beziehungsweise TreeSelect-Inhalte
* verfügbare Stylesheets

Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.

Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet:

<source lang="text">
POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030
</source>

Der Request benötigt:

<source lang="text">
Content-Type: application/json
</source>

Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden:

<source lang="json">
{}
</source>

Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.

Beispiel:

<source lang="json">
{
"Kennung": "admin",
"Gruppe": "",
"Name": "",
"Institution": ""
}
</source>

Die Antwort enthält die Ergebnistabelle als JSON.

===POST-Aufruf im Browser testen===

GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.

Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:

# Entwicklertools mit F12 öffnen.
# ''Netzwerkanalyse'' auswählen.
# Einen REST-Aufruf markieren und ''Bearbeiten und erneut senden'' auswählen.
# Methode von GET auf POST ändern.
# Header ergänzen:
#:<code>Content-Type: application/json</code>
# Unter ''Inhalt'' mindestens folgenden JSON-Body eintragen:
#:<code>{}</code>
# Anfrage senden.

Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu:

<source lang="text">
Content-Type: application/json
Content-Length: 2
</source>

Typische Fehler:

{| class="wikitable"
!Fehler!!Ursache!!Lösung
|-
|<code>Required request body is missing</code>
|Der POST-Request enthält keinen Body.
|Mindestens <code>{}</code> als Inhalt mitsenden.
|-
|<code>Content-Type 'application/octet-stream' is not supported</code>
|Der Body wird ohne passenden Content-Type übertragen.
|<code>Content-Type: application/json</code> setzen.
|}

==Hinweise zur Verwendung==

REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.

Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.

Für die Komponentenverwaltung sind insbesondere die Kombinationen aus

<source lang="text">
/etl/list
/etl/job/list/{component}
</source>

und für Masken

<source lang="text">
/form/{tid}
/report?tid={tid}
</source>

relevant.

Datei:BI Konnektoren.png

2026-09-21T13:37:47Z

Andrek:

Datei:SuperX ETL Manager Uebersicht.png

2026-09-21T11:47:22Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

Kernmodul Sonderladeroutinen

2026-09-16T09:28:02Z

Andrek: Die Seite wurde neu angelegt: „=Sonderladeroutinen in SuperX= Sonderladeroutinen ermöglichen es, zusätzliche Lade- und Verarbeitungsschritte in SuperX abzubilden, ohne dafür eine reguläre Modulladeroutine verändern zu müssen. Eine Sonderladeroutine besteht aus einem ETL-Job mit mehreren ETL-Schritten. Die einzelnen Schritte können beispielsweise Daten aus einer Datenbank entladen, UNL-Dateien in Tabellen laden, SQL-Befehle ausführen oder vorhandene SQL-Skripte starten. Damit…“

=Sonderladeroutinen in SuperX=

Sonderladeroutinen ermöglichen es, zusätzliche Lade- und Verarbeitungsschritte in SuperX abzubilden, ohne dafür eine reguläre Modulladeroutine verändern zu müssen.

Eine Sonderladeroutine besteht aus einem ETL-Job mit mehreren ETL-Schritten. Die einzelnen Schritte können beispielsweise Daten aus einer Datenbank entladen, UNL-Dateien in Tabellen laden, SQL-Befehle ausführen oder vorhandene SQL-Skripte starten.

Damit lassen sich sowohl kleine Datenübernahmen als auch umfangreichere und komplexere Ladeprozesse individuell zusammenstellen.

==Aufbau der Definitionsdatei==

Am Anfang der Definitionsdatei befinden sich die FreeMarker-Definitionen der Sonderladeroutine:

<source lang="text">
etl_jobs
etl_job_params
etl_steps
etl_step_properties
testfaelle
</source>

Dieser obere Bereich wird bei der Erstellung oder Anpassung einer Sonderladeroutine bearbeitet.

Darunter beginnt das erste Makro, beispielsweise:

<source lang="text">
<#macro etl_steps_def_check>
</source>

Ab diesem ersten Makro sollte die Datei nicht mehr verändert werden.

Für eine neue Sonderladeroutine wird daher am besten eine vorhandene Vorlage kopiert und ausschließlich der Definitionsbereich am Anfang der Datei angepasst.

Am Ende der Datei wird die Verarbeitung mit

<source lang="text">
<@ETL_STEPS_FUELLEN/>
</source>

gestartet.

==ETL-Job==

In <code>etl_jobs</code> wird der eigentliche Ladejob definiert.

Beispiel:

<source lang="text">
<#assign etl_jobs = [
{"uniquename":"kern_special_demo_special",
"name":"Demo Sonderladeroutine",
"systeminfo_id":9,
"logfile":""}
] />
</source>

Die wichtigsten Angaben sind:

===uniquename===

Technisch eindeutiger Name des Jobs.

Bei einer Sonderladeroutine muss der <code>uniquename</code> auf

<source lang="text">
_special
</source>

enden.

Nur dann wird der Job in SuperX als Sonderladeroutine erkannt und entsprechend angezeigt.

Beispiel:

<source lang="text">
kern_special_demo_special
</source>

Die Namen der einzelnen ETL-Schritte müssen dagegen nicht auf <code>_special</code> enden.

===name===

Bezeichnung des Jobs, die in der Oberfläche angezeigt wird.

===systeminfo_id===

Komponente beziehungsweise SuperX-Modul, zu dem die Sonderladeroutine gehört.

Für das Kernmodul ist dies beispielsweise:

<source lang="text">
9
</source>

===logfile===

Optionales Feld für eine Logdatei. Für normale Sonderladeroutinen kann dieser Wert leer bleiben:

<source lang="text">
"logfile":""
</source>

Die bei der Ausführung erzeugten Jobprotokolle befinden sich normalerweise unter:

<source lang="text">
webapps/superx/WEB-INF/logs/jobs/
</source>

Für einen Job wird dort eine Logdatei nach dem Schema

<source lang="text">
JOBNAME.log
</source>

erzeugt.

Für die Demo-Sonderladeroutine wäre dies beispielsweise:

<source lang="text">
webapps/superx/WEB-INF/logs/jobs/kern_special_demo_special.log
</source>

Das Jobprotokoll ist insbesondere bei Fehlern hilfreich, da dort die Ausführung der einzelnen ETL-Schritte und mögliche Fehlermeldungen protokolliert werden.

==Datenbankverbindungen==

Bei einer Sonderladeroutine können unterschiedliche Datenbankverbindungen verwendet werden.

Je nach Step-Typ heißen die entsprechenden Properties beispielsweise:

<source lang="text">
datasource
dataSource
database
sqlVarSource
sqlVarDataSource
</source>

Wichtig ist dabei, dass hier nicht zwingend der physische Name der Datenbank angegeben wird.

Verwendet wird der in SuperX konfigurierte Name der Datenbankverbindung.

Die Datenbankverbindungen werden in

<source lang="text">
webapps/superx/WEB-INF/conf/his1_databases.properties
</source>

konfiguriert.

Dort kann beispielsweise eine Verbindung unter dem Namen

<source lang="text">
eduetl
</source>

definiert sein.

Dieser Name wird dann auch in der Sonderladeroutine verwendet:

<source lang="text">
{"prop_name":"dataSource",
"prop_value":"eduetl"}
</source>

oder bei einem LOAD-Schritt:

<source lang="text">
{"prop_name":"database",
"prop_value":"eduetl"}
</source>

Der physische Datenbankname kann davon abweichen.

Für die Sonderladeroutine ist daher der in <code>his1_databases.properties</code> vergebene Name der Datenbankverbindung maßgeblich.

Die genaue Konfiguration der Datei <code>his1_databases.properties</code> wird separat beschrieben.

==ETL-Jobparameter==

Über <code>etl_job_params</code> können Parameter für einen Ladejob definiert werden.

Wenn keine Parameter benötigt werden, bleibt die Definition leer:

<source lang="text">
<#assign etl_job_params = [
] />
</source>

Ein Parameter besitzt drei wesentliche Angaben:

<source lang="text">
param_name
name
param_default
</source>

Beispiel:

<source lang="text">
<#assign etl_job_params = [
{"etl_job":"kern_special_demo_special",
"param_name":"semester",
"name":"Semester",
"param_default":"20262"}
] />
</source>

Dabei bedeutet:

;etl_job
:Der Job, zu dem der Parameter gehört.

;param_name
:Technischer Name des Parameters, im Beispiel <code>semester</code>.

;name
:Bezeichnung des Parameters, im Beispiel <code>Semester</code>.

;param_default
:Defaultwert, der verwendet beziehungsweise bei der Ausführung vorbelegt werden kann, im Beispiel <code>20262</code>.

Weitere denkbare Parameter wären beispielsweise:

<source lang="text">
startdatum
dateiname
nur_pruefen
</source>

mit Defaultwerten wie:

<source lang="text">
2026-01-01
daten.unl
false
</source>

Damit können Werte, die sich zwischen einzelnen Jobausführungen ändern sollen, als Jobparameter definiert werden, anstatt sie fest in der Laderoutine zu hinterlegen.

Welche Parameter tatsächlich sinnvoll sind und wie sie innerhalb eines konkreten ETL-Schrittes verwendet werden, hängt vom jeweiligen Step-Typ und dessen Handler ab.

Für einfache Sonderladeroutinen werden Jobparameter normalerweise nicht benötigt.

==ETL-Schritte==

Die einzelnen Verarbeitungsschritte werden in <code>etl_steps</code> definiert.

Beispiel:

<source lang="text">
<#assign etl_steps = [
{"etl_job":"kern_special_demo_special",
"uniquename":"kern_special_demo_unload",
"name":"Demo-Daten entladen",
"type":"UNLOAD",
"parent":""},

{"etl_job":"kern_special_demo_special",
"uniquename":"kern_special_demo_create",
"name":"Demo-Zieltabelle anlegen",
"type":"DOQUERY",
"parent":""},

{"etl_job":"kern_special_demo_special",
"uniquename":"kern_special_demo_load",
"name":"Demo-Daten laden",
"type":"LOAD",
"parent":""}
] />
</source>

Die wichtigsten Angaben sind:

;etl_job
:Technischer Name des Jobs, zu dem der Step gehört.

;uniquename
:Technisch eindeutiger Name des ETL-Schrittes.

;name
:Bezeichnung des Schrittes.

;type
:Art des auszuführenden ETL-Schrittes.

;parent
:Optionaler übergeordneter Step. Bei einem einfachen linearen Ablauf bleibt dieser Wert leer.

Die Reihenfolge der Einträge in <code>etl_steps</code> bestimmt die Ausführungsreihenfolge.

==Verfügbare Step-Typen==

Das Template unterstützt folgende Step-Typen:

{| class="wikitable"
|-
!Typ
!Funktion
|-
|<code>UNLOAD</code>
|Ergebnis einer SQL-Abfrage in eine Datei schreiben
|-
|<code>LOAD</code>
|Datei in eine Datenbanktabelle laden
|-
|<code>DOQUERY</code>
|SQL-Befehl direkt ausführen
|-
|<code>DOSQL</code>
|SQL-Skriptdatei ausführen
|-
|<code>MSG</code>
|Ausgabe beziehungsweise Nachricht innerhalb der Verarbeitung
|}

Für typische Sonderladeroutinen werden insbesondere <code>UNLOAD</code>, <code>LOAD</code>, <code>DOQUERY</code> und <code>DOSQL</code> verwendet.

==Step-Properties==

Die Eigenschaften der einzelnen ETL-Schritte werden über <code>etl_step_properties</code> definiert.

Der allgemeine Aufbau lautet:

<source lang="text">
{"etl_step":"NAME_DES_SCHRITTES",
"prop_name":"PROPERTY",
"prop_value":"WERT"}
</source>

<code>etl_step</code> verweist dabei auf den <code>uniquename</code> eines zuvor definierten ETL-Schrittes.

Je nach Step-Typ stehen unterschiedliche Properties zur Verfügung.

==UNLOAD==

Ein <code>UNLOAD</code>-Schritt führt eine SQL-Abfrage auf einer Datenbank aus und schreibt deren Ergebnis in eine Datei.

Beispiel:

<source lang="text">
{"etl_step":"kern_special_demo_unload",
"prop_name":"datasource",
"prop_value":"eduetl"},

{"etl_step":"kern_special_demo_unload",
"prop_name":"sqlVarSource",
"prop_value":"eduetl"},

{"etl_step":"kern_special_demo_unload",
"prop_name":"sql",
"prop_value":"select 1 as id, ''Demo'' as name"},

{"etl_step":"kern_special_demo_unload",
"prop_name":"unlFile",
"prop_value":"$KERN_LOAD_PFAD/unl/kern_special_demo.unl"}
</source>

Wichtige Properties:

;datasource
:Datenbankverbindung, auf der die SQL-Abfrage ausgeführt wird.

;sqlVarSource
:Datenbankverbindung für die Verarbeitung von SQL-Variablen. In der Regel wird hier dieselbe Datenbankverbindung wie bei <code>datasource</code> verwendet.

;sql
:SQL-Abfrage, deren Ergebnis entladen werden soll.

;unlFile
:Datei, in die das Ergebnis geschrieben wird.

;sourceVersions
:Optionale Einschränkung nach Versionen des Vorsystems.

==DOQUERY==

Mit <code>DOQUERY</code> kann ein SQL-Befehl direkt ausgeführt werden.

Beispiel:

<source lang="text">
{"etl_step":"kern_special_demo_create",
"prop_name":"dataSource",
"prop_value":"eduetl"},

{"etl_step":"kern_special_demo_create",
"prop_name":"sqlVarDataSource",
"prop_value":"eduetl"},

{"etl_step":"kern_special_demo_create",
"prop_name":"sql",
"prop_value":"create table if not exists tmp_kern_special_demo (id integer, name varchar(20))"}
</source>

Wichtige Properties:

;dataSource
:Datenbankverbindung, auf der der SQL-Befehl ausgeführt wird.

;sqlVarDataSource
:Datenbankverbindung für die Verarbeitung von SQL-Variablen.

;sql
:Auszuführender SQL-Befehl.

;databaseSystem
:Verwendetes Datenbanksystem, standardmäßig <code>postgres</code>.

;sourceVersions
:Optionale Einschränkung nach Quellversionen.

Für kurze SQL-Anweisungen ist <code>DOQUERY</code> meist die einfachste Möglichkeit.

==LOAD==

Mit <code>LOAD</code> wird eine Datei in eine Datenbanktabelle geladen.

Beispiel:

<source lang="text">
{"etl_step":"kern_special_demo_load",
"prop_name":"database",
"prop_value":"eduetl"},

{"etl_step":"kern_special_demo_load",
"prop_name":"unlFilePath",
"prop_value":"$KERN_LOAD_PFAD/unl/kern_special_demo.unl"},

{"etl_step":"kern_special_demo_load",
"prop_name":"tableName",
"prop_value":"tmp_kern_special_demo"}
</source>

Wichtige Properties:

;database
:Datenbankverbindung der Zieltabelle.

;unlFilePath
:Pfad der einzulesenden Datei.

;tableName
:Zieltabelle.

;delimiter
:Feldtrenner. Standard ist <code>^</code>.

;header
:Gibt an, ob die Datei eine Kopfzeile enthält. Standard ist <code>false</code>.

;refresh
:Legt fest, ob die Tabelle vor dem Laden geleert wird. Standard ist <code>true</code>.

;usePostgresCopyApi
:Verwendet bei PostgreSQL die COPY-basierte Ladefunktion. Standard ist <code>true</code>.

Die Anzahl und Reihenfolge der Felder in der Datei müssen zur Zieltabelle passen.

==DOSQL==

Mit <code>DOSQL</code> wird eine vorhandene SQL-Skriptdatei ausgeführt.

Dies ist sinnvoll, wenn die Verarbeitung umfangreicher ist oder bereits ein SQL-Skript vorhanden ist.

Beispiel:

<source lang="text">
{"etl_step":"mein_update",
"prop_name":"sqlScriptPath",
"prop_value":"$KERN_PFAD/schluesseltabellen/mein_update.sql"},

{"etl_step":"mein_update",
"prop_name":"dataSource",
"prop_value":"eduetl"},

{"etl_step":"mein_update",
"prop_name":"sqlVarDataSource",
"prop_value":"eduetl"}
</source>

Wichtige Properties sind:

<source lang="text">
sqlScriptPath
dataSource
sqlVarDataSource
databaseSystem
limitDebugStmts
</source>

Kurze SQL-Befehle können direkt über <code>DOQUERY</code> definiert werden. Umfangreichere SQL-Verarbeitungen können mit <code>DOSQL</code> in eine eigene Datei ausgelagert werden.

==Unterschiedliche Datenbank-Properties==

Je nach Step-Typ wird für die Datenbankverbindung ein unterschiedlicher Property-Name verwendet.

{| class="wikitable"
|-
!Step-Typ
!Datenbank-Property
|-
|<code>UNLOAD</code>
|<code>datasource</code>
|-
|<code>DOQUERY</code>
|<code>dataSource</code>
|-
|<code>DOSQL</code>
|<code>dataSource</code>
|-
|<code>LOAD</code>
|<code>database</code>
|}

Die Groß- und Kleinschreibung sollte exakt übernommen werden.

Zusätzlich gibt es für die SQL-Variablenverarbeitung <code>sqlVarSource</code> beziehungsweise <code>sqlVarDataSource</code>.

==Automatische Standardwerte==

Das Template ergänzt verschiedene Properties automatisch, wenn sie nicht ausdrücklich definiert wurden.

Für alle Steps werden unter anderem folgende Werte gesetzt:

<source lang="text">
systemInfoId
active = true
custom = true
</source>

Je nach Step-Typ werden weitere Standardwerte ergänzt.

Beispielsweise bei <code>LOAD</code>:

<source lang="text">
database = eduetl
delimiter = ^
header = false
refresh = true
usePostgresCopyApi = true
</source>

Bei <code>DOQUERY</code> werden unter anderem verwendet:

<source lang="text">
databaseSystem = postgres
dataSource = eduetl
sqlVarDataSource = eduetl
</source>

Damit können einfache Sonderladeroutinen relativ kompakt definiert werden.

Wenn vom Standard abgewichen werden soll, wird das entsprechende Property ausdrücklich in <code>etl_step_properties</code> gesetzt.

==Pfade==

Bei Dateien sollten möglichst die vorhandenen SuperX- beziehungsweise Modulvariablen verwendet werden.

Beispiele:

<source lang="text">
$KERN_LOAD_PFAD/unl/datei.unl
$SVA_LOAD_PFAD/unl/datei.unl
$SVA_PFAD/schluesseltabellen/script.sql
</source>

Dadurch müssen keine absoluten Installationspfade in der Sonderladeroutine hinterlegt werden.

==SQL innerhalb von prop_value==

SQL-Anweisungen werden innerhalb eines FreeMarker-Strings definiert.

Enthält das SQL selbst einfache Hochkommata, müssen diese verdoppelt werden.

Statt:

<source lang="text">
select 1, 'Demo'
</source>

wird innerhalb von <code>prop_value</code> geschrieben:

<source lang="text">
select 1, ''Demo''
</source>

Beispiel:

<source lang="text">
{"etl_step":"kern_special_demo_unload",
"prop_name":"sql",
"prop_value":"select 1 as id, ''Demo'' as name"}
</source>

==Testfälle==

Die Definitionsdatei bietet zusätzlich die Möglichkeit, einfache Testfälle anzugeben.

Wenn keine Tests benötigt werden:

<source lang="text">
<#assign testfaelle = [
] />
</source>

Ein Testfall besteht aus:

<source lang="text">
testcase
assertion
sql
</source>

;testcase
:Name des Testfalls.

;assertion
:Erwarteter Wert.

;sql
:SQL-Abfrage, die einen einzelnen Vergleichswert zurückliefert.

Ein einfacher Test kann beispielsweise prüfen, ob der definierte ETL-Job nach dem Einspielen vorhanden ist:

<source lang="text">
<#assign testfaelle = [
{"testcase":"Demo-Job wurde angelegt",
"assertion":"1",
"sql":"select count(*) from etl_job where uniquename='kern_special_demo_special'"}
] />
</source>

Das Template vergleicht den erwarteten Wert mit dem Ergebnis der SQL-Abfrage.

Diese Testfälle werden beim Einspielen der Definitionsdatei ausgeführt. Sie testen damit die Installation beziehungsweise den Zustand unmittelbar nach dem Einspielen der Definition und nicht automatisch das Ergebnis einer späteren Ausführung des ETL-Jobs.

==Bereich unterhalb der Definitionen==

Unterhalb der FreeMarker-Definitionen beginnen die allgemeinen Makros der Vorlage.

Ab dem ersten

<source lang="text">
<#macro ...>
</source>

sollte die Datei nicht mehr bearbeitet werden.

Für eine eigene Sonderladeroutine reicht es aus, die FreeMarker-Definitionen am Anfang der Datei anzupassen.

==Einspielen der Sonderladeroutine==

Die fertige Definitionsdatei wird in einer geladenen SuperX-Umgebung mit <code>DOSQL</code> eingespielt.

Beispiel:

<source lang="bash">
DOSQL kern_sonderladeroutine_demo.sql
</source>

Dabei werden Job, ETL-Steps, Properties, Jobparameter und die Beziehungen zwischen den Steps erzeugt beziehungsweise aktualisiert.

Anschließend steht der Job als Sonderladeroutine zur Verfügung, wenn sein <code>uniquename</code> auf <code>_special</code> endet.

==Demo-Sonderladeroutine==

Als Vorlage steht eine bewusst klein gehaltene Demo-Sonderladeroutine zur Verfügung.

Die Demo-Datei befindet sich im Git-Repository:

<source lang="text">
BI_Maintenance
</source>

Sie kann als Ausgangspunkt für eigene Sonderladeroutinen verwendet werden. Dabei sollte nur der Definitionsbereich am Anfang der Datei angepasst werden. Der darunterliegende Makrobereich bleibt unverändert.

Die Demo zeigt einen möglichst kleinen vollständigen Ablauf.

Der erste Step entlädt einen einfachen Datensatz:

<source lang="sql">
select 1 as id, 'Demo' as name;
</source>

Das Ergebnis wird in eine UNL-Datei geschrieben.

Anschließend erzeugt ein <code>DOQUERY</code>-Step eine kleine Zieltabelle:

<source lang="sql">
create table if not exists tmp_kern_special_demo
(
id integer,
name varchar(20)
);
</source>

Der abschließende <code>LOAD</code>-Step lädt die zuvor erzeugte UNL-Datei in diese Tabelle.

Der Ablauf ist damit:

<source lang="text">
Datenbank
↓
UNLOAD
↓
UNL-Datei
↓
LOAD
↓
Zieltabelle
</source>

Die Demo zeigt damit die grundlegende Arbeitsweise einer Sonderladeroutine, ohne dass komplexes SQL vom Aufbau der ETL-Schritte ablenkt.

==Hinweise==

*Eine vorhandene Vorlage kopieren.
*Nur die FreeMarker-Definitionen am Anfang der Datei bearbeiten.
*Ab dem ersten Makro den Inhalt der Vorlage unverändert lassen.
*Der <code>uniquename</code> des ETL-Jobs muss auf <code>_special</code> enden.
*Für Datenbanken den in <code>his1_databases.properties</code> definierten Verbindungsnamen verwenden.
*Der Verbindungsname muss nicht mit dem physischen Datenbanknamen übereinstimmen.
*Die Property-Namen einschließlich Groß- und Kleinschreibung exakt übernehmen.
*Bei SQL innerhalb von <code>prop_value</code> einfache Hochkommata verdoppeln.
*Bei <code>LOAD</code> darauf achten, dass Aufbau der Datei und Aufbau der Zieltabelle zusammenpassen.
*Für kurze SQL-Befehle eignet sich <code>DOQUERY</code>, für umfangreichere vorhandene SQL-Dateien <code>DOSQL</code>.
*Bei Problemen das Jobprotokoll unter <code>WEB-INF/logs/jobs/JOBNAME.log</code> prüfen.

Moduldokumentation

2026-09-16T09:22:16Z

Andrek: /* SuperX.Kern */

=SuperX.Nummernkreise=
* [[Nummernkreise|Nummernkreise Masken]]
* [[Nummernkreise Sachgebiete und Komponenten]]

=SuperX.Kern=
* [[Moduldokumentation Kernmodul|Kernmodul]]
* [[Kern_Installation_Upgrade|Installation / Upgrade]]
* [[Kernmodul_Tomcat-Einrichtung|Tomcat-Einrichtung]]
* [[Kernmodul_LDAP-Einrichtung|LDAP-Einrichtung (obsolet?)]]
* [[Kern_Konfiguration|Konfiguration]]
* [[Kern_Oberflaeche|Anpassung der Oberfläche]]
* [[Kernmodul_Komponentenverwaltung|Komponentenverwaltung]]
* [[Kernmodul_Sonderladeroutinen|Sonderladeroutinen]]
* [[Kernmodul_Regelbetrieb|BI Regelbetrieb]]
* [[Kernmodul_Shellscripte|Shellscripte]]
* [[Kern_Bestandteile|Bestandteile]]
* [[Kern_Clientwerkzeuge|Client-Werkzeuge]]
* [https://wiki.his.de/mediawiki/index.php/Administration_-_HISinOne-BI Administrationsmasken (HISWIKI)]
* [[Kern_Benutzerverwaltung|Benutzerverwaltung]]

=SuperX-Entwicklung=
* [[SuperX-Entwicklung|Übersicht]]
* [[Masken-Tutorial]]
* [[Erweiterte Maskenprogrammierung: Freemarker Templates]]
* [[Masken- und Tabellengestaltung]]
* [[Masken für das XML-Frontend vorbereiten]] (obsolet)
* [[Masken für externe Datenbanken (operatives Berichtswesen)]]
* [[Hochschuleigene Laderoutinen]]
* [[Abfragemakros (einschl. Schleifen u. Grafiken)]]
* [https://wiki.his.de/mediawiki/index.php/SXimport_zur_Maskengestaltung_verwerden-HISinOne-BI Teile aus anderen Masken oder externen Tabellen importieren]
* [[Neue Layouts in SuperX 5.1]] (obsolet)
* [[Neue Layouts in SuperX 5.2]]
* [[Entwicklerschulung]]
* HISWIKI
** [https://wiki.his.de/mediawiki/index.php/Entwicklerdokumentation_HISinOne Leitfäden für Entwickler]
** [https://wiki.his.de/mediawiki/index.php/Leitf%C3%A4den_f%C3%BCr_Entwickler_der_HISinOne-BI Leitfäden für Entwickler (BI)]
* [[Maschinenlesbare Schnittstellen für Ergebnistabellen]]
* [[Kettle-Grundlagen]]
* [[Kettle Kurs Teil 2]]
* [[Kettle Automat. Berichtsausführung und Mailversand]]
* [[LM-Modul validieren (Abgleich mit EXA)]]
* [[Dashboards erstellen]]
* [[Entwicklerhandbuch_xcube]]
* [[Gxstage-Standalone]]
* [[SuperX REST Schnittstelle]]
* [[Berichtsdesign mit JasperReports]]

=SuperX.Campus-Management=

* [[Moduldokumentation Bewerbung_Zulassung|Bewerbungen, Zulassungen]]
** [[Leitfaden Bewerberstammdaten]]
** [[Auswertungsuebersicht_Bereich_Bewerbung_Zulassung | Auswertungsübersicht]]
** [[Anwendungshandbuch Bewerbung, Zulassung]]
** [[Konfigurationshandbuch Bewerbung, Zulassung]]
* [[Moduldokumentation Studierende_Pruefungen|Studierende, Prüfungen]]
** [[Auswertungsuebersicht_Bereich_Studierende_Pruefungen | Auswertungsübersicht]]
** [[Anwendungshandbuch Studierende]]
** [[Anwendungshandbuch Pruefungen|Anwendungshandbuch Prüfungen]]
** [[Konfigurationshandbuch Studierenden-Komponente|Konfigurationshandbuch Studierende]]
** [[Konfiguration Studierende, Pruefungen|Konfiguration Studierende, Prüfungen]]
** [[Konfiguration Studierende_Pruefungen_Stichtage|Konfiguration Studierende, Prüfungen Stichtage]]
* [[Moduldokumentation Studienerfolg|Studienerfolg]]
** [[Studienerfolg_Akkreditierungsberichte|Akkreditierungsberichte]]
** [[Studienerfolg Bachelor-Master Übergang|Bachelor-Master Übergang]]
** [[Anwendungshandbuch_Studienverlauf|Anwendungshandbuch Studienverlauf]]
** [[Konfigurationshandbuch_Studienverlauf|Konfigurationshandbuch Studienverlauf]]
* [[Moduldokumentation Leistungsmonitoring|Leistungsmonitoring]]
** [[Konfigurationshanbuch Leistungsmonitoring|Konfigurationshandbuch]]
** [[Nutzungshandbuch Leistungsmonitoring|Nutzungshandbuch]]
* [[Moduldokumentation Studiengaenge|Studiengänge]]
** [[Konfigurationshandbuch Studiengaenge|Konfigurationshandbuch]]
** [[Anwendungshandbuch_Studiengaenge|Anwendungshandbuch Studiengänge]]
* [[Moduldokumentation COSTAGE| COStage (TU Graz CampusOnline)]]
** [[Modul_COSTAGE_Administrationshandbuch|Konfigurationshandbuch]]
** [[Modul_COSTAGE_Nutzungshandbuch|Nutzungshandbuch]]
** [[COSTAGE_in_Deutschland|COStage in Deutschland]]
* [[Moduldokumentation Mehrfachstudiengaenge| Mehrfachstudiengänge]]

=SuperX.Ressourcen-Management=
* [[Moduldokumentation Personal, Stellen|Personal, Stellen]]
** [[Konfigurationshandbuch Personal und Stellen|Konfigurationshandbuch]]

** Benutzungshandbücher
*** Personal im [http://www.superx-projekt.de/doku/sva_modul/benutzer/pers/main.htm html]/[http://www.superx-projekt.de/doku/sva_modul/benutzer/pers/main.pdf pdf]-Format.
*** Stellen im [http://www.superx-projekt.de/doku/sva_modul/benutzer/stell/main.htm html]/[http://www.superx-projekt.de/doku/sva_modul/benutzer/stell/main.pdf pdf]-Format.
*** Besetzung im [http://www.superx-projekt.de/doku/sva_modul/benutzer/bes/main.htm html]/[http://www.superx-projekt.de/doku/sva_modul/benutzer/bes/main.pdf pdf]-Format.
* [[Moduldokumentation Finanzrechnung|Finanzen]]
* [[Moduldokumentation Kostenrechnung|Kostenrechnung]]
* [[Moduldokumentation Inventar|Inventar]]
* [[Moduldokumentation Bau|Flächen, Räume]]
* [[Moduldokumentation GXStage|GXStage]]
** [[Modul_GXStage_Konfigurationshandbuch|Konfigurationshandbuch]]
** [[Modul_GXStage_Nutzungshandbuch|Nutzungshandbuch]]
** [[Modul_GXStage_Nutzungshandbuch_KI|Nutzungshandbuch von KI]]
* [[Moduldokumentation HRStage|HRStage]]

=SuperX.Campus-Ressourcen-Übergreifend=
* [[Moduldokumentation Managementkennzahlen|Managementkennzahlen (MAN)]]
**[[Modul_Managementkennzahlen_Administrationshandbuch|Konfigurationshandbuch]]
**[[Modul_Managementkennzahlen_Nutzungshandbuch|Nutzungshandbuch]]
* [[Moduldokumentation Grunddaten und Kennzahlen|Landeskennzahlen (KENN/KENNX)]]
** [[Modul_KENN_Nutzungshandbuch|Nutzungshandbuch]]
* [[SuperX-Connect|SuperX-Connect (SXC)]]
** [[Modul_SuperXConnect_Administrationshandbuch|Konfigurationshandbuch]]
** [[Modul_SuperXConnect_Nutzungshandbuch|Nutzungshandbuch]]
* [[Moduldokumentation Wissensbasis|Wissensbasis (KB)]]

=SuperX.Technologie und Qualitätssicherung=
* [[Heartbeat|Moduldokumentation Heartbeat]]
* [[Moduldokumentation Laderoutinen| Moduldokumentation Laderoutinen (ETL)]]
**[[Modul_ETL_Administrationshandbuch|Konfigurationshandbuch]]
**[[Modul_ETL_Nutzungshandbuch|Nutzungshandbuch]]
* [[Moduldokumentation Qualitätssicherung |Moduldokumentation Qualitätssicherung (QA)]]
** [[Modul_Qualitätssicherung Administrationshandbuch|Konfigurationshandbuch]]
** [[Modul_Qualitätssicherung Benutzerhandbuch|Nutzungshandbuch]]
*[[Modul_Visualisierung|Moduldokumentation Visualisierung (VIZ)]]
** [[Modul_Visualisierung_Konfigurationshandbuch| Konfigurationshandbuch]]
** [[Modul_Visualisierung_Nutzungshandbuch| Nutzungshandbuch]]
*[[Modul_xCube|Moduldokumentation Kreuztabellen (Xcube)]]
** [[Modul_xCube_Konfigurationshandbuch| Konfigurationshandbuch]]
** [[Modul_xCube_Nutzungshandbuch| Nutzungshandbuch]]
**[[Entwicklerhandbuch_xcube|Entwicklerhandbuch]]
*[[Modul_Berichtsassistent|Moduldokumentation Berichtsassistent (RPTA)]]
** [[Modul_Berichtsassistent_Konfigurationshandbuch| Konfigurationshandbuch]]
** [[Modul_Berichtsassistent_Nutzungshandbuch| Nutzungshandbuch]]
** [[RPTA_TODOs|TODOs (Intern)]]
*[[Modul_Nutzungsantraege|Moduldokumentation Nutzungsanträge (USERANTRAG)]]
**[[Modul_Nutzungsantraege_Nutzungshandbuch|Nutzungshandbuch]]
*[[Modul_Portalkonfiguration|Moduldokumentation Portalkonfiguration (PORTAL)]]
** [[Modul_Portalkonfiguration_Nutzungshandbuch| Nutzungshandbuch]]

=SuperX.Bedienung=
* [[SuperX-Benutzungshandbuch_Basics|SuperX-Benutzungshandbuch: Basics]]
* [[SuperX_barrierefrei | SuperX barrierefrei?]]

Kernmodul Shellscripte

2026-09-09T14:23:02Z

Andrek: /* Propadmin */

= SuperX-spezifische Scripte: Übersicht =
Für die Administration des DataWarehouse sind Shellscripte vorbereitet, die flexible Werkzeuge zur Datenbankadministration bereitstellen. Die Shellscripte werden in den Update-Scripten aufgerufen, können aber auch zur manuellen Administration benutzt werden. Die wichtigsten Bereiche sind die Masken-Verwaltung und die Ladescripte im Umgang mit Tabellen sowie allgemeine Scripte.
Alle Scripte befinden sich unter $SUPERX_DIR/db/bin, deshalb muss dieser Pfad in der Umgebungsvariable PATH enthalten sein. Die Scripte wurden unter UNIX entwickelt (ohne Endung oder Endung .x), einige davon sind auch nach DOS portiert worden (erkennbar an der Endung .bat).
Einige Scripte lauten "sx_auto_"..., dies bedeutet, dass die Scripte ohne Sicherheitsabfrage ausgeführt werden.
Voraussetzung für den Ablauf der Scripte ist die Eintragung der korrekten Umgebungsvariablen in $SUPERX_DIR/db/bin/SQL_ENV bzw. $SUPERX_DIR\db\bin\sql_env.bat. Wenn der Client jdbc verwendet wird, muss ausserdem die korrekte [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] gesetzt sein.

=Die Umgebungssteuerung SQL_ENV =

Das Script $SUPERX_DIR/db/bin/SQL_ENV steuert die Umgebung und ist für den Betrieb der Kernmodul-Scripte unverzichtbar. Bei einem Update des SuperX-Kernmoduls wird die vorhandene SQL_ENV nicht überschrieben. Änderungen der ausgelieferten SQL_ENV.sam müssen deshalb geprüft und bei Bedarf manuell in die produktive SQL_ENV übernommen werden.

Ab Kernmodul 6.0 liegt $SUPERX_DIR innerhalb der SuperX-Webanwendung:

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

Folgende Variablen müssen geprüft und passend zur Installation gesetzt werden:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
| WEBAPP
| Wurzelverzeichnis der SuperX-Webanwendung
|-
| SUPERX_DIR
| Datenbank- und Modulbereich unter $WEBAPP/WEB-INF/conf/edustore
|-
| DATABASE
| Datenbanksystem; für SuperX ist POSTGRES einzutragen
|-
| DBNAME
| Name der SuperX-Datenbank, standardmäßig superx
|-
| SX_CLIENT
| Verwendeter Datenbankclient; möglich sind psql oder jdbc
|-
| DB_PROPERTIES
| Pfad zur [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|db.properties]], standardmäßig $WEBAPP/WEB-INF/db.properties
|-
| JAVA_HOME
| Installationspfad der Java-Runtime; für Kernmodul 6.0 wird OpenJDK 17 verwendet
|-
| JAVA_OPTS
| Java-Optionen für Kernmodul-Shellscripte wie DOSQL, DOQUERY und die Upgrade-Scripte
|-
| CATALINA_OPTS
| Java-Optionen für einen manuell installierten oder mit SuperX betriebenen Tomcat
|-
| MAILPROG
| Mailprogramm unter UNIX, beispielsweise s-nail oder mailx
|-
| LOGMAIL/ERRORMAIL
| Mailadressen für Log- und Fehlermeldungen der ETL-Scripte
|-
| LOGGING_PROPERTIES
| Logging-Konfiguration des JDBC-Clients
|-
| PGHOST
| Hostname des PostgreSQL-Servers
|-
| DBDELIMITER
| Trennzeichen für Unload-Dateien, standardmäßig ^
|-
| JDBC_CLASSPATH
| Classpath der JDBC-Treiber, Klassen und benötigten Jakarta-Bibliotheken
|-
| XML_CLASSPATH
| Classpath der XML-Werkzeuge
|-
| FM_DEBUG
| Wenn FM_DEBUG=true gesetzt wird, bleiben die von DOSQL erzeugten temporären SQL-Dateien zur Fehlersuche erhalten
|}

==Java-Optionen für Kernmodul 6.0 ==

Die Java-Optionen werden an dieser Stelle zentral dokumentiert. Andere Artikel sollen auf diesen Abschnitt verweisen, damit die Konfiguration nicht mehrfach gepflegt werden muss.

Tragen Sie folgenden vollständigen Block in die SQL_ENV ein. Bei einem Tomcat aus den Ubuntu- oder Debian-Paketen wird derselbe Block in /etc/default/tomcat10 verwendet. Passen Sie die Speicherwerte an die Größe des Servers an:

<source lang="bash">
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
JAVA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME JAVA_OPTS
</source>

Wenn der eigene Tomcat CATALINA_OPTS verwendet, tragen Sie stattdessen folgenden vollständigen Block in dessen Startumgebung ein:

<source lang="bash">
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
CATALINA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME CATALINA_OPTS
</source>

Zusätzliche Optionen für JMX, eigene Truststores oder besondere LDAP-Konfigurationen werden nur bei Bedarf ergänzt. Ungeschützte JMX-Ports und die Deaktivierung von Sicherheitsprüfungen gehören nicht in die allgemeine Standardkonfiguration.

==JDBC-Classpath für Tomcat 10 ==

Tomcat 10 verwendet die Jakarta-Servlet-API. Der JDBC_CLASSPATH muss deshalb die Jakarta-Bibliothek und $WEBAPP/WEB-INF/classes enthalten:

<source lang="bash">
JDBC_CLASSPATH="$WEBAPP/WEB-INF/lib_ext/jakarta.servlet-api-6.0.0.jar:$WEBAPP/WEB-INF/classes"
for i in $LIB_PATH/*.jar; do JDBC_CLASSPATH="$JDBC_CLASSPATH:$i"; done
XML_CLASSPATH=$JDBC_CLASSPATH
export JDBC_CLASSPATH XML_CLASSPATH
</source>

Ein alter Classpath mit servlet-api.jar kann zu java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServlet führen.

Die SQL_ENV sollte in jeder Shell geladen werden, in der Kernmodul-Scripte ausgeführt werden:

<source lang="bash">
. $SUPERX_DIR/db/bin/SQL_ENV
</source>

Der Aufruf kann beispielsweise in ~/.bashrc oder ~/.profile eingetragen werden.

==Nutzung der SQL_ENV unter HISinOne-BI ==

Die SuperX-Shellscripte lassen sich auch in HISinOne-BI unter Linux nutzen. Eine Beispielkonfiguration befindet sich unter $WEBAPP/WEB-INF/conf/edustore/db/bin/SQL_ENV_his1.sam. Setzen Sie auch dort WEBAPP, SUPERX_DIR, JAVA_HOME, DB_PROPERTIES und den Jakarta-Classpath entsprechend der tatsächlichen Installation.

Normalerweise wird für HISinOne-BI der JDBC-Client verwendet:

<source lang="bash">
SX_CLIENT=jdbc
export SX_CLIENT
</source>

{{Hinweis|Die Datei muss nicht SQL_ENV heißen. Für eine spezielle Konfiguration kann ein ergänzender Name wie SQL_ENV_FHDO verwendet werden.}}

= Datenbank- und SQL-Scripte =
== PropAdmin ==

Der PropAdmin ist ein kleines Werkzeug, um den Zugriff auf JDBC-Datenbanken zu testen und die [[#dbProperties|''Verbindungsparameter'']] in einer Properties-Datei zu speichern.

Eine Musterdatei für PostgreSQL liegt unter

<code>$WEBAPP/WEB-INF/db-postgres.properties</code>

Für den Aufruf unter Linux wird die zu bearbeitende Properties-Datei über die Umgebungsvariable <code>PROPFILE</code> festgelegt.

=== Aufruf unter Linux ===

Wechseln Sie zunächst in das <code>WEB-INF</code>-Verzeichnis der SuperX-Webanwendung:

<syntaxhighlight lang="bash">
cd $WEBAPP/WEB-INF
</syntaxhighlight>

Anschließend setzen Sie die zu bearbeitende Properties-Datei:

<syntaxhighlight lang="bash">
export PROPFILE=db_test.properties
</syntaxhighlight>

Wenn <code>PROPFILE</code> nicht gesetzt ist, verwendet <code>propadmin.x</code> die Umgebungsvariable <code>DB_PROPERTIES</code>.

Danach wird der PropAdmin aufgerufen:

<syntaxhighlight lang="bash">
./conf/edustore/db/bin/propadmin.x
</syntaxhighlight>

Der Dateipfad zur Properties-Datei wird dabei '''nicht''' als Parameter an <code>propadmin.x</code> übergeben, sondern über <code>PROPFILE</code> bzw. alternativ <code>DB_PROPERTIES</code> festgelegt.

Beim Aufruf können die Verbindungsparameter wie

* <code>driverName</code>
* <code>connectionURL</code>
* <code>connectionName</code>

bestätigt oder geändert werden. Anschließend kann das Passwort eingegeben und die Datenbankverbindung getestet werden.

Der benötigte <code>JDBC_CLASSPATH</code> ist normalerweise bereits über die SuperX-SQL-Umgebung gesetzt. Falls dies nicht der Fall ist oder beim Aufruf Klassen wie der JDBC-Treiber nicht gefunden werden, kann er beispielsweise folgendermaßen gesetzt werden:

<syntaxhighlight lang="bash">
export JDBC_CLASSPATH="$WEBAPP/WEB-INF/classes:$WEBAPP/WEB-INF/lib/*"
</syntaxhighlight>

=== Passwort direkt mit CryptUtils verschlüsseln ===

Soll lediglich ein Passwort im von SuperX verwendeten Format <code>sx_des...</code> erzeugt werden, ist dafür kein vollständiger PropAdmin-Aufruf notwendig. Das Passwort kann direkt über <code>de.memtext.util.CryptUtils</code> verschlüsselt werden.

Je nach Umgebung unterscheidet sich der benötigte Classpath.

==== HISinOne ====

In einer HISinOne-Umgebung wechseln Sie in das Verzeichnis

<code>$WEBAPP/WEB-INF/classes</code>

<syntaxhighlight lang="bash">
cd $WEBAPP/WEB-INF/classes
</syntaxhighlight>

Da sich die kompilierte Klasse <code>de.memtext.util.CryptUtils</code> unterhalb dieses Verzeichnisses befindet, kann als Classpath einfach <code>.</code> verwendet werden.

==== SuperX ====

In einer SuperX-Umgebung wechseln Sie dagegen in das Verzeichnis

<code>$WEBAPP/WEB-INF/lib</code>

<syntaxhighlight lang="bash">
cd $WEBAPP/WEB-INF/lib
</syntaxhighlight>

Als Classpath wird die SuperX-JAR der installierten Version angegeben, zum Beispiel:

<syntaxhighlight lang="bash">
superx6.0.jar
</syntaxhighlight>

==== Passwort direkt im Befehl angeben ====

Für HISinOne:

<syntaxhighlight lang="bash">
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES("anfang12"));' '/exit' | jshell -q --class-path .
</syntaxhighlight>

Für SuperX, beispielsweise mit Version 6.0:

<syntaxhighlight lang="bash">
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES("anfang12"));' '/exit' | jshell -q --class-path superx6.0.jar
</syntaxhighlight>

Die Ausgabe enthält das verschlüsselte Passwort, zum Beispiel:

<pre>
sx_des#-107#-62#90#114#112#-9#-73#86#116#120#-97#-28#-54#-55#11#8
</pre>

Der komplette Wert einschließlich <code>sx_des</code> kann anschließend beispielsweise als

<pre>
connectionPassword=sx_des#...
</pre>

in eine Properties-Datei eingetragen werden.

'''Achtung:''' Bei dieser Variante steht das Klartextpasswort direkt im Shell-Befehl und kann dadurch in der Shell-History gespeichert werden.

==== Passwort verdeckt einlesen ====

Um zu vermeiden, dass das Klartextpasswort im Befehl bzw. in der Shell-History erscheint, kann es zunächst verdeckt eingelesen werden:

Für HISinOne:

<syntaxhighlight lang="bash">
read -rsp 'Passwort: ' PW; echo
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES(System.getenv("PW")));' '/exit' \
| PW="$PW" jshell -q --class-path .
unset PW
</syntaxhighlight>

Für SuperX, beispielsweise mit Version 6.0:

<syntaxhighlight lang="bash">
read -rsp 'Passwort: ' PW; echo
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES(System.getenv("PW")));' '/exit' \
| PW="$PW" jshell -q --class-path superx6.0.jar
unset PW
</syntaxhighlight>

Das Passwort wird bei der Eingabe nicht auf dem Bildschirm angezeigt. In der Shell-History wird lediglich der Aufruf von <code>read</code> gespeichert, nicht das eingegebene Passwort.

Auch hier wird als Ergebnis das vollständig verschlüsselte Passwort einschließlich des Präfixes <code>sx_des</code> ausgegeben.

=== Zeichencodierung ===

Wenn die Default-Dateiencodierung der aktiven Locale nicht ausreicht, kann eine entsprechende Fehlermeldung ausgegeben werden. Unter Windows / DOS ist die Vorbelegung Cp1252 bei deutscher Codepage in der Regel ausreichend; unter Unix wird die deutsche [[Kern_Installation_Upgrade#Zeichencodierung|Locale]] benötigt.

==DOSQL ==
Zum Absetzen beliebiger SQL-Kommandos werden die Befehle DOSQL und DOQUERY genutzt.
DOSQL kann SQL-Anweisung(en) in der der Datei (als Parameter) in der SuperX-Datenbank ausfuehren.
{| class="wikitable"
|-
| Syntax
| DOSQL "Dateiname mit sql-Anweisung(en)" header (true,false)(optional) Ausgabedatei(optional)
|-
| Beispiel
| DOSQL "/home/superx/db/isql/test.sql" false "^" output.txt
|}
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden.
Wenn
FM_DEBUG = true
export FM_DEBUG
gesetzt wird, werden bei Freemarker Scripten von DOSQL die *.tmp.sql-Dateien nicht gelöscht.

==DOQUERY ==
Shellvariablen setzen und eingegebene SQL-Anweisung (als Parameter) in der SuperX-Datenbank ausfuehren.
{| class="wikitable"
|-
| Syntax
| DOQUERY "sql-Anweisung" header (true,false)(optional) Delimiter(optional) Ausgabedatei(optional)
|-
| Beispiel
| DOQUERY "select name from userinfo" false "^" output.txt
|}
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden.
=XML-Scripte=
==sx_transform.x ==
Transformiert eine xml-Datei mit einer übergebenen XSL-Datei und gibt das Ergebnis in einen Ausgabekanal aus (stdout oder Datei). Dabei wird der in SuperX integrierte XML-Parser Xerces und der XSL-Prozessor Saxon benutzt.
{| class="wikitable"
|-
| Syntax
| sx_transform.x -IN:xml-Datei -XSL:xsl-Datei -OUT:Ausgabedatei -method:Ausgabeformat (text, xml,html,rtf,pdf) (optional) -params:Parameter(optional)
|-
| Beispiel
| sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html
|}
Als Parameter "method" kann ein spezielles Ausgabeformat gewählt werden, z.B. text (siehe Xalan-Doku). Bei rtf wird der RTF-Construktor Jfor aufgerufen, bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert. Wir gehen also nicht davon aus, dass .fo-Dateien die Eingabequelle darstellen.

Stylesheet Parameter werden mit "," getrennt optional angefügt, z.B.

sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html "-params:Jahr=2020,Monat=12"

==saxon_transform.x==
Wie sx_transform.x transformiert das Script XML via XSLT, hier werden allerdings Saxon-spezifische Parameter ermöglicht.
{| class="wikitable"
|-
| Syntax
| saxon_transform.x xml-Datei xsl-Datei Ausgabeformat (text, xml,html) (optional) Ausgabedatei (optional) Parameter (optional)
|-
| Beispiel
| sx_transform.x myxml.xml myxsl.xsl output.htm html
|}
Bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert.

Wenn ein XSL-Script mehrere Ausgabedateien erzeugen soll, kann dieses Script ggü. sx_transform.x Vorteile haben.
==show_fop_fontlist.x==
Zeigt die installierten Fonts für PDF Erzeugung mit XSL-FO an.
Das Script hat keine Argumente.
==sx_validate.x==
sx_validate.x validiert eine XML-Datei
*ob sie wohlgeform ist
*ob sie zu einem optional übergebenen Schema (XSD-Datei) valide ist.
sx_validate.x XML-Datei SCHEMA-Datei (optional)
==sx_xmlfileappender.x==
Das Script ''sx_xmlfileappender.x'' faßt mehrere XML-Dateien in einem übergebenen Pfad zu eine rDatei mit einem neuen root-Knoten "artificalroot" zusammen.

Aufruf:
sx_xmlfileappender.x Path file(regex oder Dateiname mehrere mit , getrennt) Outputfile

= Codierung in ISO und UTF-8=
Ältere Systeme arbeiten in der Regel mit der Zeichencodierung ISO-8859-1 bis ISO-8859-9. Dieser Zeichensatz wird auch LATIN-1 genannt. Die UNIX-Locale de_DE@euro entspricht z.B. ISO-8859-9 und enthält das EUR-Symbol.

Aktuelle SuperX-Installationen arbeiten in der Regel mit der UTF-8 Codierung, dies wird bei der [[Kern_Installation_Upgrade#Zeichencodierung|Installation]] gesetzt.

Mit dem Wechsel von ISO-Codierung zu UTF8 bleibt oft der Bedarf bestehen, Dateien hin- und herzucodieren. Sei es, weil beim Entladen aus einer entfernten Datenbank noch das ISO-System genutzt wird, oder bei der Migration eines Systems. Nach unserer Erfahrung sollten Umlaute in Dateinamen unbedingt vermieden werden.
SuperX bietet unter UNIX Shellscripte zur Erfassung und Änderung der Zeichencodierung (Verzeichnis $SUPERX_DIR/db/bin). Im Wesentlichen werden dabei die Unix-Kommandos file und recode genutzt, die Shellscripte machen den Umgang mit umfangreichen Dateilisten komfortabler. Bei der Verarbeitung von Dateilisten sollte man die Scripte sehr vorsichtig einsetzen, es finden keine Sicherheitsüberprüfungen statt.
{{Achtung| Die Scripte wurden bisher nur unter Linux mit bash getestet, andere UNIXe wie BSD verhalten sich ggf. anders als erwartet. Daher bitte mit Vorsicht benutzen.}}

==sx_show_encoding.x ==
Das Script zeigt die Encodierung einer Datei an.
{| class="wikitable"
|-
| Syntax
| sx_show_encoding.x <Datei>
|-
| Beispiel
| sx_show_encoding.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| /home/superx/webserver/tomcat/webapps/superx/WEB-INF/web.xml: XML
ISO
|}
Das Script nutzt verschiedene UNIX-Tools, je nach System kann die Ausgabe variieren. Bei XML-Dateien wird auch der Dateiinhalt (XML-Header) ausgewertet.
==sx_recode_iso2utf.x ==
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_iso2utf.x <Datei>
|-
| Beispiel
| sx_recode_iso2utf.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| --keine--
|}
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="ISO-8859-1"?>
der Header
<?xml version="1.0" encoding="UTF-8"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
==sx_recode_utf2iso.x ==
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_utf2iso.x <Datei>
|-
| Beispiel
| sx_recode_utf2iso.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| --keine--
|}
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="UTF-8"?>
der Header
<?xml version="1.0" encoding="ISO-8859-1"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
==sx_list_isofiles.x ==
Das Script listet alle ISO-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
{| class="wikitable"
|-
| Syntax
| sx_list_isofiles.x <Pfad>
|-
| Beispiel
| sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF
|-
| Ausgabe
| webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt
[...]
webserver/tomcat/webapps/superx/WEB-INF/db.properties
|}
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script [[#sxrecodeisofilesx|''sx_recode_isofiles.x'']] als Eingabedatei genutzt werden.
sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >iso.txt
==sx_recode_isofiles.x ==
Das Script konvertiert alle Dateien in der übergebenen Dateiliste von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_isofiles.x <Datei>
|-
| Beispiel
| sx_list_isofiles.x iso.txt
|-
| Ausgabe
| --Keine--
|}
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes [[#sxlistisofilesx|''''sx_list_isofiles.x'''']].
==sx_list_utf8files.x ==
Das Script listet alle UTF-8-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
{| class="wikitable"
|-
| Syntax
| sx_list_utf8files.x <Pfad>
|-
| Beispiel
| sx_list_utf8files.x webserver/tomcat/webapps/superx/WEB-INF
|-
| Ausgabe
| webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt
[...]
webserver/tomcat/webapps/superx/WEB-INF/db.properties
|}
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script [[#sxrecodeutffilesx|''sx_recode_utf8files.x'']] als Eingabedatei genutzt werden.
sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >utf.txt
==sx_recode_utf8files.x ==
Das Script konvertiert alle UTF-8 Dateien in der übergebenen Dateiliste von UTF-8 nach ISO:
{| class="wikitable"
|-
| Syntax
| sx_recode_utf8files.x <Datei>
|-
| Beispiel
| sx_recode_utf8files.x utf.txt
|-
| Ausgabe
| --Keine--
|}
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes [[Kernmodul_Shellscripte#sx_list_utf8files.x|sx_list_utf8files.x]].

=Umgang mit Tabellen =
In SuperX werden ständig Tabellen erstellt / geladen / entladen. Zu diesem Zweck wurden Shellscripte entwickelt.
==sx_unload_table.x ==
Entlädt die Inhalte der Tabelle nach <<Dateiname>>(optional) oder <<name>>.unl
{| class="wikitable"
|-
| Syntax
| sx_unload_table.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_unload_table.x userinfo
|}

==sx_upload_table.x ==
Löscht die Inhalte der Tabelle <<name>>, und lädt die Inhalte einer Datei in die Tabelle mit [[#sxuploadrecords|''sx_upload_records'']]. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
{| class="wikitable"
|-
| Syntax
| sx_upload_table.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_upload_table.x userinfo
|}

==sx_upload_records.x ==
Lädt die Inhalte einer Datei in die Tabelle, ohne vorherige Inhalte zu löschen. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
{| class="wikitable"
|-
| Syntax
| sx_upload_records.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_upload_records.x userinfo
|}
Bei Postgres als DB-System wird eine Java-Klasse (de.superx.bin.UnlFileConverter) aufgerufen, die die Unload-Datei entsprechend einer Spezifikation aufbereitet (siehe $SUPERX_DIR/db/conf/unldescr*).
Wenn der jdbc-Client benutzt wird, können umfangreiche Parameter übergeben werden (Import mit Spaltenüberschriften, Ausgabe von Fehlerprotokollen). Vergleichen Sie die Kommentare im Script.
==sx_schema.x ==
Entlädt das Schema einer Tabelle in einem vorgegebenen Format.
{| class="wikitable"
|-
| Syntax
| sx_schema.x Tabelle format (pg|ids|ansi|xml|HIS)) (optional) Ausgabedatei (optional)
|-
| Beispiel
| sx_schema.x userinfo ids myschema.sql
|-
| Die Formate
| Die Formate sind SQL für PostgreSQL oder ANSI sowie XML beziehungsweise ein XML-Format in Anlehnung an die Datenbank-DTD der HIS.
|}

= Modulverwaltung =
Die Verwaltung der Module, einschließlich Installation, Aktualisierung, Sicherung und Logdateien, erfolgt über zentrale Shellscripte in $SUPERX_DIR/db/bin. Die Shellscripte bilden die operativen Hüllen um die eigentlichen SQL-Scripte. Diese werden zum Teil manuell und zum Teil automatisch aus einer zentralen Steuerdatei erzeugt:
$SUPERX_DIR/db/module/<<Modulname>>/conf/<<Modulname>>.xml
Für PostgreSQL werden daraus die benötigten Installations- und Aktualisierungsscripte erzeugt.

== module_scripts_create.x ==
Das Script erzeugt die Installationsdateien für ein Modul nach dem Schema 
<<Modulname>>_<<Scriptaktion>>_<<Kürzel für Datenbanksystem>>.sql
Beispielsweise wird für das BAU-Modul aus der Datei $BAU_PFAD/conf/bau.xml das Script bau_load_pg.sql erzeugt, das die Rohdaten unter PostgreSQL lädt.
{| class="wikitable"
|-
| Syntax
| module_scripts_create.x -Modulkürzel- -Modulpfad- -Datenbanksystem-
|-
| Beispiel
| module_scripts_create.x bau $BAU_PFAD POSTGRES
|}
Im Grunde handelt es sich um XML-Transformationen. Die Stylesheets für dieses Script befinden sich im Verzeichnis $SUPERX_DIR/db/conf, und die XML-Datei für das Module in $SUPERX_DIR/db/module/-Modulname-/conf. Wenn die Datei nicht gefunden wird, bricht das Script ab.

== module_install.x ==
Installiert ein Modul -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.

{| class="wikitable"
|-
| Syntax
| module_install.x -Modulkürzel- -Modulpfad-
|-
| Beispiel
| module_install.x bau $BAU_PFAD
|}

== module_drop.x ==
Löscht die Komponenten eines Moduls -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.

{| class="wikitable"
|-
| Syntax
| module_drop.x -Modulkürzel- -Modulpfad-
|-
| Beispiel
| module_drop.x bau $BAU_PFAD
|}

== Entladen ==
Das Entladescript lautet $SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.x. Die Entladeparameter werden in folgender Datei festgelegt: 
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_ENV
Entladeroutine bei mandantenfähigen Installationen:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_ENV
Dokumentation zu den jew. Parametern finden Sie in den jeweiligen Administrationshandbüchern der Module. Meist kann man Start-Semester oder -Jahre für das Entladen festlegen. Immer muß man auch das Datenbank-Vorsystem festlegen (Hostname, Kennung etc) sowie, bei HIS-Systemen, die Versionsnummer.
== module_etl.x ==
Aktualisiert ein Modul -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.
{| class="wikitable"
|-
| Syntax
| module_etl.x -Modulname- -Modulpfad-
|-
| Beispiel
| module_etl.x bau $BAU_PFAD
|}
Die folgende Abbildung zeigt, wie die Komponenten zusammenhängen (klicken Sie auf die Grafik, um sie zu vergrößern):

Zunächst werden die Rohdaten geladen, die Daten vorbereitet, transformiert, und nachbereitet. Danach werden die Hilfstabellen erzeugt und, bei erfolgreichem durchlaufen, das Standdatum aktualisiert.

[[Bild:etl.png|417x313px]]

Bei Fehlern im ETL-Prozeß wird die Sicherung wiederhergestellt, und eine Mail an die Administrator_in verschickt. Außerdem werden die übernommenen Daten überprüft; wenn z.B. Schlüssel fehlen oder Rohdaten falsch zu sein scheinen, wird dies als Attachment an die Log- oder Fehlermail angehängt.
In der Praxis wird dieses Script nicht direkt von Cronjobs ausgeführt, sondern von einem Shellscript, das vorher die Umgebung einrichtet. Das folgende Beispiel zeigt ein Update-Script für das BAU-Modul:
bau_update.x
<source lang="bash">
#!/bin/sh
. /home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore/db/bin/SQL_ENV
ERRORMAIL="bau-admin@hochschule.de"
export ERRORMAIL
LOGMAIL=$ERRORMAIL
export LOGMAIL
module_etl.x bau $BAU_PFAD >$BAU_ERRORDAT 2>&1
</source>
Wie Sie sehen ist es möglich, für jedes Modul unterschiedliche Mailadressen zuzuweisen. Die Mailadressen werden systemweit in der [Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] eingetragen.
Im allgemeinen ETL-Prozeß wird standardmäßig auch die Tabelle protokoll in einem festzulegendem Rhythmus (Konstante Löschung Protokoll (Tage)) gelöscht. Beim Vorgabewert 90 werden bei jeder ETL-Routine Einträge, die älter als 90 Tage sind, gelöscht.

=== Hochschulspezifische Transformationen im ETL-Prozess ===

Zusätzlich lassen sich im ETL-Prozeß hochschulspezifische Scripte ausführen (und überwachen). Dazu müssen Dateien mit einem gewissen Namensschema im Stammverzeichnis des Moduls vorhanden sein. Es gibt einen vereinfachten und einen erweiterten Modus für hochschulspezifische Transformationen.
*Einfacher Modus
**Wenn im Modulpfad die Datei "preparation.sql" existiert, wird sie nach dem LOAD-Schritt ausgeführt.
**Wenn im Modulpfad die Datei "finalize.sql" existiert, wird sie nach dem TRANS-Schritt ausgeführt.
* Erweiterter Modus / mandantenspezifische Scripte
**Wenn im Modulpfad Dateien nach dem Schema <<Modulname>>_<<ETL-Schritt>>_<<Mandatennr.>>.sql exisitieren, werden diese jeweils nach dem "normalen" ETL-Schritt ausgeführt.

Wenn also z.B. die Datei
$COB_PFAD/cob_trans_70.sql
existiert und in der SQL_ENV die Umgebungsvariable $MANDANTID auf "70" steht, dann wird das Script nach dem normalen Trans-Schritt ausgeführt und nach
L_cob_trans_mandant_70.log
geloggt.

Der erweiterte Modus erlaubt die beliebige Anpassung eines Modus an eigene Bedürfnisse, z.B. Schlüsselumsetzung o.ä. Gleichzeitig erlaubt er einen echten mandentenfähigen Betrieb der ETL-Scripte.

===Logging der Shellscripte ===
Hinweis: bei mandantenfähigen Installationen steht vor der Endung .log immer die MandantID.

==== Installation / Upgrade ====
Fürs Kernmodul lauten die Dateien bei der Installation:
$SUPERX_DIR/db/install/L_*.log
Beim Upgrade:
$SUPERX_DIR/db/install/upgrade/upgrade.log
Für alle anderen Komponenten:
$SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Installationsschritt>>.log
==== Laderoutinen ====
Für alle Module sind die Dateien wie folgt benannt:
Entladeroutine:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.err
Entladeroutine bei mandantenfähigen Installationen:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_unload.err

Laderoutine:
$SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Ladeschritt>>.log
wobei <<Ladeschritt>> wie folgt aufgebaut ist:
# Unload (Entladen aus Vorsystem)
# Load (CSV-Upload)
# Transformation (Schlüsselharmonisierung, Prüfroutinen)
# Aggregation (Aufbau der Hilfstabellen)
# System (Ladedatum aktualisieren, Datenbank-Wartung)
Wenn die Laderoutine erfolgreich ist, werden alle Schritte hintereinander ausgeführt und geloggt. Wenn nicht, dann wird der jew. Schritt zuende geführt, und dann die Laderoutine gestoppt. Wenn also z.B. beim LOAD ein Fehler auftritt, dann wird der Schritt "Transformation" gar nicht erst begonnen. So ist sichergestellt daß die Auswertungen trotz Fehler laufen.

=== Debugging von Freemarker Scripten ===
Da die Laderoutinen oft mit Freemarker Scripten arbeiten, werden diverse SQL-Scripte nur zur Laufzeit generiert und ausgeführt, und danach wieder gelöscht. Um die Laderoutinen transparenter "beobachten" zu können, können Sie die die Löschung der Scripte mit dem Parameter
FM_DEBUG="true"
export FM_DEBUG
Wenn FM_DEBUG = true gesetzt wird, werden bei Freemarker Scripten von [[Kernmodul_Shellscripte#DOSQL|DOSQL]] die *.tmp.sql-Dateien nicht gelöscht. Sie können den Parameter in der aktuellen Shell setzen, oder permanent in der [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]].

==Kettle-Jobs starten==
Da Kettle in der Webanwendung integriert ist, können Sie Kettle Jobs auch ohne die PDI-Standalone-Installation per Kommandozeile ausführen. Wenn die [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] eingerichtet und geladen ist, geben Sie z.B. einfach ein:

sx_kitchen.x -file "sospos_res1.kjb" -norep
Die Parameter werden direkt an die Java Anwendung "kitchen" weitergereicht, d.h. weitere Dokumentation finden Sie in unserem [[Kettle_Kurs_Teil_2#Kitchen|Kettle-Kurs]].

=Installation und Wartung=
==Patch einspielen==
Für SuperX können spezielle Patch-Dateien per Kommandozeile installiert werden. Vorbedingung ist, dass die bash und das Paket unzip installiert sind.
patch_apply.x
Das Script entpackt eine übergebene Patch-Datei (zip-File), und installiert die Dateien und DB-Operationen für die jeweils installierten und zum Patch passenden Module. Sie starten es direkt aus dem Patchordner, in dem der zu installierende Patch liegt:
patch_apply.x -PatchFile-
Ein Beispiel:
patch_apply.x patch_2011-06-01_superx_iso.zip
Dabei wird in dem Verzeichnis der Patch entpackt und ausgeführt. Je nach Patch muss auch ein Tomcat Neustart erfolgen, ein entsprechender Hinweis befindet sich in der Patch-Dokumentation.
Wenn ein Patch auch Dateien unterhalb von webapps/superx enthält, müssen Sie im Falle von Tomcat Clusterbetrieb den Patch auf alle Tomcat Hosts übertragen, entweder direkt oder mit git / rsync.
Weitere Hinweise zum Script finden Sie im [[Kern_Installation_Upgrade#Patch_einspielen|Installationshandbuch]].
{{Hinweis|Bei HISinOne-BI funktioniert das patch-apply Script nicht, der Patch mit dem Kürzel "webapps" im Dateinamen wird einfach in webapps/superx entpackt, und in der Regel sollten die jew. Module geupgradet werden. Weitere Hinweise finden Sie in der jew. Patch-Readme.}}
==JasperReports kompilieren==
Wenn Sie mit Unterberichten arbeiten, müssen Sie kompilierte .jasper-Dateien einbinden und ausliefern. Da dieser Dateityp normalerweise (und richtigerweise) im ".gitignore" ist, d.h. nicht über git ausgeliefert werden kann, können Sie die Dateien auch direkt auf dem Applikationsserver mit der exakt passenden JR-Version erzeugen. Typischerweise führen Sie das Script im Ordner WEB-INF/reports aus. Der Aufruf:
cd $WEBAPP/WEB-INF/reports
java $JAVA_OPTS -cp "$JDBC_CLASSPATH" de.superx.bin.SxJasperCompiler <JRXML-Datei>
Der Workflow ist wie folgt:
* Die Quelldatei.jrxml ist die XML-Beschreibungsdatei des Berichts
* Der compile erzeugt aus der Quelldatei.jrxml eine Datei Quelldatei.jasper im gleichen Verzeichnis
* Die Quelldatei.jasper ist kompilierte Beschreibungsdatei für den Bericht, und wird in Unterberichten und Booklets genutzt. Weitere Details siehe unser [https://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/f_AufbaudesHauptberichts.htm JR-Handbuch].
==LDAP User deaktivieren==
Ausschließlich für SuperX-Standalone-Anwender können wir im System eine Gültigkeit von UserAccounts und automatisiertes Sperren von LDAP-Usern mit Sperr-Merkmal einbauen.
Die Tabelle userinfo und das entsprechende Formular zum Userbearbeiten hat die Merkmale Beginn Gültigkeit (gueltig_von) und Ende Gültigkeit (gueltig_bis), so dass SuperX-Standalone Hochschulen z.B. für befristete Mitarbeiter_innen in der Userverwaltung direkt eintragen können, dass ein Mitarbeiter sich z.B. nach dem 31.12.2024 nicht mehr anmelden können soll.
Wenn die Hochschule eine Passwortkontrolle via LDAP macht, kann diese per Script User mit einem entsprechenden Merkmal wie userLocked=true automatisiert zu sperren.
Hierfür setzt das Script den Eintrag userinfo.maxVersuch (also die maximal erlaubten Anmeldeversuche) auf 0 gesetzt, als "Ende Gültigkeit" wird das Vortagsdatum eingetragen sowie die Spalte ''password_sha'' (verschlüsseltes SuperX-Passwort) geleert.

Aufruf:
sx_ldap_lockout.x Pfad/zu/db.properties pfad/zu/superx_standalone_ldap.properties
Das Script kann nächtlich ausgeführt werden.

= Masken-Verwaltung =
Die Masken-Verwaltung ist detailliert im [[Masken-Tutorial|Entwicklerhandbuch SuperX]] beschrieben. Hier nur ein paar Hinweise zur Verwaltung der Masken. Zum Erzeugen und Verändern von Masken gibt es unter UNIX eine Kommandoschnittstelle, die auf dem Gebrauch folgender Skripte beruht. Die Skripte stehen unter dem Verzeichnis
$SUPERX_DIR/db/bin
und erzeugen oder verwenden Dateien in dem gegenwärtigen Arbeitsverzeichnis. Nach dem Einspielen der Datenbank sollten Sie darauf achten, den Dateien Ausführungsberechtigung (chmod 750 *) zu geben.

==Eine Maske suchen ==
Wenn Sie eine Maske suchen, sollten die die Felder tid oder name in der Tabelle maskeninfo durchsuchen. Das folgende Script macht dies automatisch:
sx_search_mask
{| class="wikitable"
|-
| Aufruf:
| sx_search_mask <String>
|-
| Aktion:
| sx_search_mask sucht die Masken, deren Name <String> enthält
|-
| Ausgabe: .
| tid, name der gefundenen Masken
|}

==Eine Maske sichern und entladen ==
Um eine Maske zu sichern, müssen Sie die entsprechenden Einträge in den Tabellen
# felderinfo,
# masken_felder_bez,
# maskeninfo,
# sachgeb_maske_bez,
# maske_system_bez
selektieren und sichern. Für dies gibt es das Script sx_select_mask.
sx_select_mask
{| class="wikitable"
|-
| Aufruf:
| sx_select_mask <TID>
|-
| Aktion:
| sx_select_mask entlädt alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez, maske_system_bez zur Maske mit tid = <TID>.
|-
| Ausgabe:
| Fünf Dateien:
# <TID>_felderinfo.unl,
# <TID>_masken_felder_bez.unl,
# <TID>_maskeninfo.unl,
# <TID>_sachgeb_maske_bez.unl,
# <TID>_maske_system_bez.unl

|}

=====Eine Maske neu einfügen =====
Um eine Maske neu einzufügen, müssen Sie die entsprechenden Einträge in den Tabellen
# felderinfo,
# masken_felder_bez,
# maskeninfo,
# sachgeb_maske_bez,
# maske_system_bez
einfügen. Dafür gibt es das Script sx_insert_mask.

sx_insert_mask
{| class="wikitable"
|-
| Aufruf:
| sx_insert_mask <TID> [<neue TID>] [j]
|-
| Aktion:
| sx_insert_mask lädt den Inhalt der fünf Dateien
# <TID>_felderinfo.unl,
# <TID>_masken_felder_bez.unl,
# <TID>_maskeninfo.unl,
# <TID>_sachgeb_maske_bez.unl,
# <TID>_maske_system_bez.unl
in die jeweiligen Tabellen der SuperX-Datenbank. Mit "j" wird die Sicherheitsabfrage umgangen.

|}

Falls <neue TID> nicht angegeben wird, werden die Metadaten wieder mit der alten TID in die Datenbank eingespielt (=Update).
Falls <neue TID> angegeben wird, werden die Metadaten mit der neuen TID in die Datenbank eingespielt (=Insert). Dabei werden alle TIDs in den abhängigen Tabellen angepasst. So können Masken sehr einfach kopiert werden. Eine neue TID bekommt man durch die Wahl der nächsten Zehnerzahl, die größer als die größte vorkommende Nummer ist. Die größte vorkommende Nummer erhält man durch Ausführung des folgenden SQL-Ausdrucks mit Hilfe des Kommandos DBACCESS:
select max(tid) from maskeninfo;

{| class="wikitable"
|-
| !
| Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis xxxx0000 bis xxxx9990 liegen, wobei xxxx der von der HIS verwandten Hochschulnummer entspricht. Die Zehnerschritte ergeben sich daraus, dass die dazwischen liegenden Nummern für die Maskenfelder (Tabelle felderinfo) reserviert sind<ref><blockquote> Aus historischen Gründen liegen die Nummern aus Karlsruhe im Bereich 0-9990, aus Duisburg im Bereich 10000-19990.
</blockquote></ref>.
|}

Wie im Abschnitt [[Kern_Benutzerverwaltung|Userverwaltung]] beschrieben, kann die neue Maske Benutzern oder Gruppen zugänglich gemacht werden.

== Eine Maske löschen ==
Um eine Maske zu löschen, müssen Sie die Einträge in den oben genannten Tabellen entfernen. Dafür gibt es das Script sx_delete_mask
sx_delete_mask
{| class="wikitable"
|-
| Aufruf:
| sx_delete_mask <TID>
|-
| Aktion:
| sx_delete_mask löscht alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez und maske_system_bez zur Maske mit tid = <TID>.
|}

==Änderungen an einer Maske vornehmen ==
1. Selektieren der Metadaten der betreffenden Maske: sx_select_mask <TID>
2. Editieren der fünf Metadaten-Dateien ,,<TID>_..."
3. Abspeichern der neuen Metadaten: sx_insert_mask <TID>
==Masken per Kommandozeile==
In diversen Szenarien kann es sinnvoll sein, Masken nicht nur im Browser über die Webanwendung auszuführen, sondern über Kommandozeile, also ohne laufenden Tomcat:
* Für Entwicklungszwecke kann es praktisch sein, wenn man keinen laufenden Tomcat braucht, und Masken z.B. in Eclipse ausführt und debuggen kann
* Große Ergebnisdateien lassen sich leichter erzeugen, weil man von der Webanwendung unabhängig ist und z.B. dem Kommandozeilenaufruf mehr Arbeitsspeicher zuteilt.
* Für die Verteilung von Downloads kann es sinnvoll sein, Berichtsergebnisse in Dateiform zu generieren und im [[Kern_Konfiguration#Downloads_einrichten_und_verteilen|Download-Bereich]] zu verlinken.

Masken können bei eingerichteter Kommandozeilenumgebung direkt ausgeführt werden:

* Unter SuperX: [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]]
* Unter HISinOne-BI: [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|Nutzung der SQL_ENV unter HISinOne-BI]], oder Einrichtung einer HISinOne-Umgebung unter Eclipse: https://wiki.his.de/mediawiki/index.php/Einrichtung_einer_HISinOne-Arbeitsumgebung

Damit der Aufruf unter Kernmodul 6.0 funktioniert, muss der zentral unter [[#JDBC-Classpath_für_Tomcat_10|JDBC-Classpath für Tomcat 10]] dokumentierte Jakarta-Classpath geladen sein.

Der Kommandozeilenaufruf sieht unter Linux wie folgt aus:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:Maskennummer -out:Ausgabedatei -user:Benutzerkennung "-params:Parameter..." -logger:$SUPERX_DIR/db/conf/logging.properties

Hier ein Beispiel für den Aufruf der Maske "Studierende und Studienanfänger (Zeitreihe)" (tid=16000) als Admin-User und deren Ausgabe in die Datei "test.htm":

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.htm -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel läßt sich fortführen für andere Ausgabeformate, hier z.B. für PDF:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.pdf -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_fo_pdf.xsl&contenttype=application/pdf" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel zeigt daß über das Params-Argument beliebige Ausgabeformate übergeben werden können, z.B. auch Excel (xlsx):

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.xlsx -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_xls.xsl&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -logger:$SUPERX_DIR/db/conf/logging.properties

oder als CSV Export:
java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.csv -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&contenttype=text/csv" -logger:$SUPERX_DIR/db/conf/logging.properties

Über den "Deep-Link"-Button lassen sich beliebige Parameter-Zeichenketten erzeugen und nutzen. Auch Aufrufe von JasperReports sind damit möglich, z.B. ein Studierendenbericht als Excel-Report:

java -cp $JDBC_CLASSPATH $JAVA_OPTS -Xmx2048m de.superx.bin.ExecuteMask -tid:160440 -out:$OUTFILE "-params:maxoffset=1000000&stylesheet=tabelle_160440_semester_geschlecht.jrxml&tablestylesheet=tabelle_160440_semester_geschlecht.jrxml&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -user:superx -logger:$SUPERX_DIR/db/conf/logging.properties

Bei Datenblattberichten sollte auch der Parameter tablestylesheet übergeben werden.

Unter Eclipse sieht der Aufruf für das erste Beispiel (Ausgabe nach html) so aus:

[[Bild:execute_mask_eclipse1.png|680px]]

Und hier die Parameter:

[[Bild:execute_mask_eclipse2.png|680px]]

Das Beispiel lässt sich leicht auf andere Plattformen (DOS, Netbeans) übertragen.

Sie können auch Parameter bewußt leer übergeben, indem Sie den Parameter ohne Wert übergeben, hier z.B. den Parameter „Sprache“:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:70170 -out:test.htm -user:admin "-params:Stichwort=REPORT&Sprache=" -logger:$SUPERX_DIR/db/conf/logging.properties

==Ausführen von JasperReports ==
Neben der Ausführung im Browser gibt es eine "Kommandozeilenversion" des Aufrufs: sx_jasper.x

{| class="wikitable"
|-
| Aufruf:
| sx_jasper.x -JRXML:<JRXML-Datei> -XML:<Datei mit XML-Datenquelle> -db_properties:Pfad_zur_db.properties -IGNORE_PAGINATION:<true oder false> und optional -JASPER:<Jasper-Datei> -JRPRINT:<Jrprint-Datei> -OUT:<Ausgabedatei>
|-
| Aktion:
| sx_jasper.x führt einen JasperReports-Task aus. Die Datenquelle kann entweder xml sein (Parameter -XML), oder eine Datenbankverbindung in der Datei db.properties. Das Ergebnis wird in eine Datei <Ausgabedatei> ausgegeben.
Wenn keine Ausgabedatei angegeben wird, wird der jrxml-Dateiname verwendet, und eine PDF-Ausgabe erzeugt.
|}
Sie können es mit einer Maskenausführung kombinieren, oder zum Entwickeln. Bei der Maskenausführung können Sie aber im Script [[Kernmodul_Shellscripte#Masken_per_Kommandozeile|ExecuteMask]] direkt JasperReports aufrufen.

= Mailversand =
Für den Mailversand empfehlen wir die Unix Anwendung s-nail. Installation unter Ubuntu mit
apt-get install -y s-nail
Unter RedHat
yum install s-nail
== Einrichtung .mailrc ==
Das s-nail in Ubuntu 22.04 (Version 14.9.23) bietet die Möglichkeit, in der Shell mails für verschiedene Accounts zu verschicken. Zur Konfiguration wird die Datei $HOME/.mailrc genutzt.

alt:
set smtp="smtp://smtp.variomedia.de:587"
set from="mail@memtext.de"
set smtp-auth=login
set smtp-auth-user="noreply@superx-projekt.de"
set smtp-auth-password=securepw1234

neu:
<source lang="sh">
set v15-compat
account test {
set from="Memtext <mail@memtext.de>"
set mta=smtp://noreply%40superx-projekt.de:securepw1234@smtp.variomedia.de:587
set smtp-use-starttls
}
</source>

{{Achtung|Sollte nur für den Benutzer lesbar sein. Es ist nicht sicher, das Passwort direkt in der Konfigurationsdatei zu speichern. Eine sicherere Variante wäre, pass oder gnome-keyring zu nutzen.}}

== Mail verschicken über die bash ==
Zum Verschicken einer Testmail schreiben Sie z.B.
<source lang="bash">
echo "test" | s-nail --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de
</source>
Das CLI von s-nail verhält sich etwas UNIX-untypisch: Beachten Sie dass mehrere Mailadressat_innen mit Leerzeichen getrennt hinten angefügt werden - ohne Anführungszeichen um alle Mailadressen.

Mit dem zusätzlichen Parameter -v können detaillierte Debug-Informationen ausgegeben werden:
<source lang="bash">
echo "test" | s-nail -v --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de
</source>
Damit lässt sich dann prüfen, ob der Versand verschlüsselt (mit set smtp-use-starttls) oder unverschlüsselt stattgefunden hat.
Unverschlüsselt sähe dann z.B. so aus:
<source lang="bash">
echo "Testmail" | s-nail -v --account=test-ohne-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.
</source>

Und verschlüsselt so:
<source lang="bash">
echo "Testmail" | s-nail -v --account=test-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.
s-nail: Certificate depth 2
s-nail: subject = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: notBefore = Feb 1 00:00:00 2010 GMT
s-nail: notAfter = Jan 18 23:59:59 2038 GMT
s-nail: issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: Certificate depth 1
s-nail: subject = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail: notBefore = Nov 2 00:00:00 2018 GMT
s-nail: notAfter = Dec 31 23:59:59 2030 GMT
s-nail: issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: Certificate depth 0
s-nail: subject = /C=DE/ST=Brandenburg/O=Memtext AG/CN=*.superx-projekt.de
s-nail: notBefore = Feb 8 00:00:00 2024 GMT
s-nail: notAfter = Mar 10 23:59:59 2025 GMT
s-nail: issuer = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail: Comparing subject_alt_name: need<smtp.superx-projekt.de> is<*.superx-projekt.de>
s-nail: TLS certificate ok
s-nail: TLS BLAKE2s256 fingerprint: 7A:0A:D3...
s-nail: TLS connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
</source>

== SQL_ENV mit s-nail ==
In der [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] für die neue Konfig-Syntax am besten die Variable MAILPROG mit z.B.
MAILPROG="s-nail --account=test"
angeben.
=Shellscripte in der HISinOne-BI=
Die Shellscripte von superX sind auch in der HISinOne-BI nutzbar, sofern Linux als Betriebssystem genutzt wird. Vorbedingung ist
* die Einrichtung der [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|SQL_ENV]]
* Machen Sie alle Shellscripte im Ordner .../webapps/superx/WEB-INF/conf/edustore/db/bin ausführbar
chmod +x .../webapps/superx/WEB-INF/conf/edustore/db/bin/*
* Nützlich ist auch die Installation von psql, also mindestens das Paket postgresql-client
Im folgenden Beispiel wird ein HISinOne-BI-spezifisches Modul eingerichtet.

==Shellscripte zur Verwaltung von RES==
Das Forschungsmodul RES der HIS e.G. ist ein Beispiel für ein Nicht-SuperX-Modul, das aber auch mit Shellscripten verwaltet werden kann. Hier das Vorgehen:
*Entpacken Sie die ZIP-Datei H1-CS-CM-RM_<<Version>>.zip in einem Ordner Ihrer Wahl.
*Setzen Sie in der [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|SQL_ENV]] die Pfade und Variablen:
RES_PFAD=.../webapps/superx/WEB-INF/conf/edustore/db/module/res; export RES_PFAD
RES_ERRORDAT=$RES_PFAD/res_load.err; export RES_ERRORDAT
RES_LOAD_PFAD=$RES_PFAD/rohdaten; export RES_LOAD_PFAD
RES_ERRORMAIL=$ERRORMAIL; export RES_ERRORMAIL
RES_LOGMAIL=$LOGMAIL; export RES_LOGMAIL
* Machen Sie die Shellscripte in $RES_PFAD und $RES_LOAD_PFAD ausführbar:
chmod +x $RES_PFAD/*.x
chmod +x $RES_PFAD/rohdaten/*.x
chmod +x $RES_PFAD/upgrade/*.x

Danach können Sie das Modul installieren mit
cd $RES_PFAD
module_install.x res .

Dann entladen Sie aus H1, indem Sie in $RES_LOAD_PFAD die Datei RES_ENV analog einrichten wie Sie z.B. die ZUL_ENV oder SOS_ENV eingerichtet haben

cd $RES_LOAD_PFAD
res_unload.x

Dann starten Sie den Update:

cd $RES_PFAD
module_etl.x res .

Es kann Probleme geben, wenn das Kernmodul nicht zu der ZIP Datei von HIS paßt. Fehler bzgl. "dim_bp_apnr"... können Sie ignorieren.

Eine Datenbank-Dokumentation befindet sich hier:
.../webapps/superx/WEB-INF/conf/edustore/db/module/res/conf/res.html

Kern Benutzerverwaltung

2026-08-31T06:58:21Z

Andrek: Gastzugang

= Einzelne Benutzer verwalten =

Wenn Sie im Bereich Administration den Bereich ''Benutzer verwalten'' wählen, sehen Sie folgende Oberfläche:

{{ImagePara |imgsrc=menue_admin_user.png|width=600px|caption=Themenbaum-Menü zur Userverwaltung}}

Die jeweiligen Masken sind im Folgenden beschrieben.

==Neuer Benutzer ==

Wenn Sie eine neue Benutzerkennung einrichten wollen, klicken Sie auf ''User einrichten''. Anschließend werden Sie nach Angaben zur Kennung für den neuen Benutzer gefragt:

{{ImagePara |imgsrc=user_edit.png|width=600px|caption=Maske User einrichten}}

Die User-tid wird automatisch hochgezählt. Die Benutzerkennung ist der Login-Text, und eine Gruppe kann ausgewählt werden. Der Name der Person muss angegeben werden. Wenn Sie das Feld "Inst-Rechte" leer lassen, hat die Kennung Rechte auf alle Institutionen.

Die Gültigkeit der Kennung sowie der Zugehörigkeit zu einer Institution kann ebenfalls eingeschränkt werden. Das Klappmenü "nur Lehre" wird bei den Organigramm-Rechten ausgewertet (obsolet mit 3.0).

Klicken Sie zum Abschluss auf "Abschicken". Der Benutzer wird dann mit dem verschlüsselten Passwort angelegt.

==Benutzer löschen ==
Wenn Sie einen Benutzer löschen wollen, wählen Sie im Themenbaum die Abfrage "User löschen" und dort die Kennung in dem Klappmenü.

{{ImagePara |imgsrc=user_loeschen.png|width=400px|caption=Maske User entfernen}}

Bestätigen Sie Ihre Auswahl einmal, indem Sie die Kennung eintippen.

== Benutzer bearbeiten ==

Im Formular '''User suchen''' erhalten Sie je nach Einschränkung eine Liste mit Benutzern.

{{ImagePara |imgsrc=user_suchen_maske.png|width=800px|caption=Maske User suchen}}

Wir schränken z.B. ein auf die Gruppe Administratoren.

{{ImagePara |imgsrc=user_suchen_tabelle.png|width=800px|caption=Ergebnis Maske User suchen}}

Es erscheinen zwei User, die voreingestellten Administratoren. Sie können sich Details zur Person ansehen, oder die Person bearbeiten.

{{ImagePara |imgsrc=user_bearbeiten1.png|width=800px|caption=Maske User bearbeiten}}

In der Bearbeitungsmaske können Sie Kennung und Namen ändern, sowie das [[Kern_Benutzerverwaltung#Passwort_vergessen_oder_Account_gesperrt|Passwort ändern]]. Danach müssen Sie oben rechts auf die Diskette zum Speichern klicken.
Sie können die Gruppenzugehörigkeit zuordnen, und sie können dem User Rechte auf einzelne Sachgebiete, Masken, Institutionen, Sichten und ganze Sichtarten geben.

{{Hinweis|Bei Institutionen gibt es eine spezielle Institutionsnr. 0, die Rechte auf alle Institutionen beinhaltet. Ebenso gibt die Gruppe Administration Recht auf alle Masken.}}

Bei den Gruppen, Sachgebiete, Masken, Institutionen, Sichten und Sichtarten handelt es sich um Unterformulare, d.h. Sie brauchen Änderungen hier nicht mit dem Diskettensymbol oben rechts zu speichern.

==Passwort vergessen oder Account gesperrt==
Wenn Benutzer_innen sich nicht mehr anmelden können, kann das zwei Ursachen haben:
* Es gab zu viele fehlerhafte Login-Versuche, dann ist kein Login mehr möglich, weil der Account gesperrt wird.
* Benutzer_innen haben ihr Passwort vergessen

Sie können als Administrator_in den Account wieder öffnen und/oder das Passwort zurücksetzen.
* Account öffnen:
{{ImagePara |imgsrc=user_pw_aendern2.png|width=800px|caption=Maske User bearbeiten entsperren}}
Setzen Sie das Feld "Akt_versuch" auf einen Werte kleiner als "Max_versuch".
* Passwort ändern:

{{ImagePara |imgsrc=user_pw_aendern1.png|width=800px|caption=Maske User bearbeiten Passwort}}

Gehen Sie zunächst auf den Button "ändern".

{{ImagePara |imgsrc=user_pw_aendern3.png|width=800px|caption=Maske User bearbeiten Passwort 2}}
Danach geben sie das neue Passwort rechts daneben im Passwort Feld ein, und klicken danach auf "Verschlüsseln". Es wird dann im linken Feld ersetzt. Danach klicken Sie rechts oben auf "Speichern".

==Zum Häkchen Administration ==

Das Häkchen Administrator/in hat keinen Effekt auf die sichtbaren Sachgebiete und Masken im Themenbaum. Es bewirkt folgendes:

* Lese- und Schreibzugriff für alle DBFORMS
* Leserecht für alle Sichten
* Ausführungsrecht für Administrationsmasken im Kernmodul, z.B. User löschen
* Recht, im Webanwendung Manager den Cache zu leeren und die SQL-Protokollierung anzuzeigen
* Recht, JasperReports-Templates zu generieren

Für die Gruppen Administratoren und Bearbeiter musste bei Einsatz des SuperX-Kernmoduls 3.0 immer das Häkchen bei "Administration" gesetzt werden, denn nur diese Personen durften im Kernmodul 3.0 die DBForms überhaupt nutzen. Im Kernmodul 3.5 oder höher ist dies nicht mehr notwendig, da reicht es aus wenn die User der Gruppe "Administratoren" (Name darf nicht geändert werden) angehören, bzw. im GANG-Modul den Gruppen '''GANG Bearbeiter''' oder '''GANG Administratoren'''.

=Gruppen verwalten =

Im Bereich ''Gruppenverwaltung ''erhält man die Möglichkeit, Gruppen zu löschen, neue Gruppen anzulegen und Stammdaten zu ändern.

==Neue Gruppe anlegen ==

Wenn man eine neue Gruppe einrichten will, wählt man im Menü Administration->Benutzer->Gruppe einrichten.

{{ImagePara |imgsrc=gruppe_einrichten.png|width=800px|caption=Maske Gruppe einrichten }}

Sie können eine Nummer vergeben, den Namen festlegen (darf nicht bereits existieren), die zugehörigen Mitglieder auswählen, und Rechte für Sachgebiete und Masken vergeben.

Mit '''Abschicken''' werden die Tabellen gefüllt.

==Gruppe bearbeiten ==

Im Formular ''''''Gruppe suchen'''''' erhalten Sie je nach Einschränkung eine Liste mit Gruppen.

{{ImagePara |imgsrc=gruppe_suchen.png|width=600px|caption=Maske Gruppe suchen}}
Wir schränken z.B. ein auf die Gruppe(n) des Users '''superx'''.

{{ImagePara |imgsrc=gruppe_suchen_tabelle.png|width=600px|caption=Tabelle Gruppe suchen}}

Es erscheint ein Eintrag mit der Gruppe Administratoren, die zwei User enthält. Sie können die Gruppe mit dem Stift-Icon bearbeiten.

{{ImagePara |imgsrc=gruppe_bearbeiten1.png|width=600px|caption=Gruppe bearbeiten}}

In der Bearbeitungsmaske können Sie den Namen der Gruppe ändern. Danach müssen Sie unten "Speichern" anklicken.

Sie können die Gruppenzugehörigkeit zuordnen, und sie können der Gruppe Rechte auf einzelne Masken, Sichten und Sichtarten geben.

Außerdem können Sie der Gruppe weitere User zufügen / enfernen.

{{Hinweis|Bei den Gruppen, Masken, Sichten, Sichtarten und Usern handelt es sich um Unterformulare, d.h. Sie brauchen Änderungen hier nicht mit dem Diskettensymbol oben rechts zu speichern.}}

==Gruppe löschen ==

Im XML-Frontend im Menü Administration -> Benutzer -> Gruppe löschen können Sie eine Gruppe löschen und die jeweiligen Rechte für Sachgebiete und Masken entfernen. Auch die Zuordnungen von Usern zur Gruppe (nicht aber die User selbst) werden gelöscht.

{| class="wikitable"
|-
!
!
|-
| Sie müssen lediglich den Namen der Gruppe auswählen und einmal zur Sicherheit bestätigen, indem Sie den Namen eintippen. 
Mit '''Abschicken''' werden die Einträge entfernt.
| [[Bild:gruppe_loeschen.png|400x240px]]
|}

=Maskenrechte vergeben =

Einzelne Berichte/Masken Benutzern oder Gruppen zuzuordnen verschafft mehr Kontrolle als die Berichte über Sachgebietsrechte zu vergeben. Dabei muss aber beachtet werden, dass eventuelle Rechte auf Sichten extra vergeben werden müssen und ist damit auch etwas aufwendiger.

Wenn Sie einen Bericht frei geben, rufen Sie diesen als Administrator ein mal auf. Die Auswahlfelder, welche als Buttons angezeigt werden können Sichten sein. Z.B. in dem Bericht „Alter der Studierenden“ die Buttons Studiengang, Fächer und Abschluss.

[[Bild:sichten_alter_der_studierenden_01.png|604x423px]]

Wenn Sie auf einen Button wie Studiengang klicken, sehen Sie in der Box oben, dass Sie die Sicht ändern können. Dies ist daher ein Button der Rechte auf eine Sicht benötigt. Das gleiche auch bei dem Button Fächer.

[[Bild:sichten_alter_der_studierenden_03.png|549x389px]]

Bei dem Button Abschluss fehlt die Auswahl der Sicht. Dies ist nur eine Liste und keine Sicht.

[[Bild:sichten_alter_der_studierenden_04.png|604x437px]]

Sie müssen also für die Buttons Studiengang und Fächer dem Benutzer, dem Sie explizit diese Maske zuordnen rechte auf die verwendeten Sichten geben. Wenn Sie unter Administration → Masken → Felder → Feld suchen bei „Feld der Maske“ „Alter der Studierenden“ raus suchen und abschicken, Sehen Sie die Felder der Maske „Alter der Studierenden“.

[[Bild:sichten_alter_der_studierenden_05.png|531x317px]]

[[Bild:sichten_alter_der_studierenden_06.png|604x165px]]

[[Bild:sichten_alter_der_studierenden_07.png|302x684px]]

Klicken Sie hier jeweils für Studiengang und Fächer auf Bearbeiten. In dem neuen Fenster sehen Sie unter „Relation“ den verwendeten SQL und auch die Sichtarten.

[[Bild:sichten_alter_der_studierenden_08.png|604x385px]]

[[Bild:sichten_alter_der_studierenden_09.png|604x383px]]

Sie müssen dem Benutzer auf mindestens eine Sicht oder besser noch auf die ganze Sichtart das Recht vergeben.

= Sichten und Sichtarten zuordnen =

Wie unter Maskenrechte vergeben beschrieben, können Sie die benötigten Sichtarten für Masken herausfinden. Sie können nun einfach die Sichtart in dem entsprechenden Berechtigungsfeld raus suchen und dazu das Recht vergeben. Sie können aber auch nur das Recht auf eine spezielle Sicht dieser Sichtart vergeben. Um heraus zu finden welche Sichten sich hinter einer Sichtart verstecken gehen Sie auf Administration → Masken → Sicht suchen. Dort wählen Sie die Sichtart aus und klicken auf Abschicken.

[[Bild:sichten_suchen_01.png|604x215px]]

Die Ergebnistabelle zeigt alle Sichten der angegebenen Sichtart an.

[[Bild:sichten_suchen_02.png|604x399px]]

Sie können daraus nun auch speziell eine Sicht aussuchen und in der Rechtevergabe das Rechte auf eine einzelne Sichten vergeben. Dazu merken Sie sich einfach die Nummer. Das hat dann den Effekt, dass in manchen Berichten im Ergebnis nach dem Baum dieser Sicht aufgebaut wird.

= Benutzer Info =

Unter der Benutzer Info befinden sich Berichte, die ausführliche Informationen für die Benutzer und Gruppenverwaltung ausgeben.

== Bericht: Benutzer – Abfragen ==

In diesem Bericht erfahren Sie auf welche Berichte bestimmte Benutzer zugreifen dürfen. Es werden auch Berichte angezeigt, welche über Gruppen- oder Sachgebietsrechte erteilt worden sind.

[[Bild:bericht_benutzer_abfragen_maske.png|680x236px]]

In dem Bericht können Sie ein oder mehrere Benutzer wählen und bei bedarf die Ausgabe auf eine Gruppe und/oder ein Sachgebiet begrenzen.

[[Bild:bericht_benutzer_abfragen_tabelle.png|680x319px]]

So würde dann z.B. das Ergebnis aussehen. Dem testuser aus diesem Beispiel wurde ein Bericht direkt zugeordnet und hat Rechte auf 6 weitere über das Sachgebiet Masken-Verwaltung. Wie Sie sehen erfahren Sie hier die Berechtigungen der Benutzer auf Berichte recht einfach und Übersichtlich.

== Bericht: Benutzer – Institutionen ==

In diesem Bericht erfahren Sie welche Institutionsrechte die Benutzer haben.

[[Bild:bericht_benutzer_institution_maske.png|680x185px]]

In dem Bericht gibt es nur die Auswahl des Benutzers.

[[Bild:bericht_benutzer_institution_tabelle.png|680x143px]]

Als Ergebnis erhalten Sie alle Institutionen auf die der Benutzer Rechte besitzt.

== Bericht: Benutzer - Sichten ==

In diesem Bericht erfahren Sie auf welche Sichten die Benutzer Rechte haben.

[[Bild:bericht_benutzer_sichten_maske.png|680x243px]]

In dem Bericht können Sie ein oder mehrere Benutzer wählen und bei bedarf die Ausgabe auf eine Gruppe und/oder ein Sachgebiet begrenzen.

[[Bild:bericht_benutzer_sichten_tabelle.png|680x233px]]

Als Ergebnis erhalten Sie alle Sichten auf die der Benutzer Rechte besitzt.

== Bericht: Gruppen – Benutzer ==

In diesem Bericht können Sie in Erfahrung bringen, in welchen Gruppen ein Benutzer ist oder welche Benutzer in einer Gruppe ist. In dem folgenden Beispiel wurde eine Gruppe gewählt und es wird nach den zugeordneten Benutzern gesucht.

[[Bild:bericht_gruppen_benutzer_maske.png|680x222px]]

Als Ergebnis erhalten Sie dann die Zuordnung Gruppe – Benutzer.

[[Bild:bericht_gruppen_benutzer_tabelle.png|680x166px]]

== Bericht: Gruppen – Sachgebiete ==

In diesem Bericht werden die Sachgebiete aufgelistet, dessen Rechte einer Gruppe zugeordnet wurden.

[[Bild:bericht_gruppen_sachgebiete_maske.png|680x190px]]

Als Ausgabe erhalten Sie eine Tabelle mit Gruppe – Sachgebiet.

[[Bild:bericht_gruppen_sachgebiete_tabelle.png|680x140px]]

= Rechte für Downloads=
Diese Funktion ist im [[Kern_Konfiguration#User-_und_Gruppenrechte_auf_Downloads|Konfigurationsleitfaden Downloads]] beschrieben.
=Rechte für DBFORMS =

Die DBFORMS dienen der Dateneingabe in SuperX, z.B. für die Konfiguration. Alle DBFORMS lassen sich direkt aus einer Maske aufrufen und sind daher nur für die Personen sichtbar, die auch das jeweilige Maskenrecht haben.

Wenn die User das Recht auf das Sachgebiet des jeweiligen DBFORMS haben (Tabelle sachgeb_dbform_bez), bekommen sie Leserecht, sofern das DBFORM "stand-alone" arbeitet, d.h. nicht mit Pflichtparameter aus einer Maske aufgerufen wird, sondern direkt über die Maske "Tabelle suchen".

Wenn die User einer Gruppe zugeordnet sind, die Rechte auf Sachgebiete mit dem Namen "Administration*" oder "Bearbeitung*" haben, bzw. wenn sie als Einzeluser Recht auf ein solches Sachgebiet haben, bzw. wenn sie das [[Kern_Benutzerverwaltung#Zum_H.C3.A4kchen_Administration|Admin-Häkchen]] haben, bekommen sie auch Schreibrecht (Daten einfügen, löschen, neu erzeugen). Beim Modul GANG sind das z.B. die Sachgebiete "Administration GANG" und "Bearbeitung GANG".
= Gastzugang einrichten =
Ab Kernmodul 5.0 / HisInOne 2022.06 ist es möglich Gastzugänge einzurichten, um Berichte anzuzeigen, für die man sich nicht authentifizieren muss,z.B. Studierendenzahlen, wenn dies vom Datenschutz genehmigt wurde.
{{Hinweis|Bei Nutzung in HISinOne-BI ist die Menüführung etwas anders, siehe [https://wiki.his.de/mediawiki/index.php/BI-Gastzugang_einrichten Leitfaden].}}

Zum Einrichten einer Gastkennung gehen Sie auf Administration | Gastzugang einrichten.
Als Gastkennung wird "gast" vorgeschlagen. Es kann aber auch mit mehreren Gastkennungen gearbeitet werden, z.B. gast1, gast2, gast3 für verschiedene Zwecke. Wichtig ist nur, dass die Kennung mit "gast" anfängt.

Geben Sie auf der Auswahlmaske der Gastkennung Instititions-Rechte, Rechte auf Masken und dafür benötigte Sichtarten.

{{Achtung|Eine Gastkennung verhält sich bzgl. Rechten wie eine "normale" Kennung, es entfällt aber die Passworteingabe. Bitte daher mit Vorsicht verwenden. Außerdem sollten Sie bei der Nutzung von mehreren Gastkennungen, die jeweils im gleichen Browser mit unterschiedlichen Deeplinks genutzt werden, über User- und Gruppenrechte einstellen, dass jeweils beide Menüpunkte berechtigt sind. }}

Im folgenden Beispiel lege wir eine Kennung "gast1" an, mit Rechten auf eine Studierenden-Zeitreihe aus rein fachlicher (d.h. keine Fakultäten/ Fachbereiche) Sicht.

[[Bild:gastzugang_maske1.png|400px]]

Nach dem Abschicken sehen Sie ein Ergebnis der Neuanlage:

[[Bild:gastzugang_tabelle1.png|400px]]

Das resultierende Bearbeitungsformular ist das normale Formular:

[[Bild:gastzugang_tabelle2.png|500px]]

Hier können Sie weitere Rechte wie [[Kern_Benutzerverwaltung#Benutzer_bearbeiten|gewohnt]] anpassen. Wenn Sie Gastuser manuell bearbeiten, muss das verschlüsselte Passwort "notsecret" sein.

== Manuelle Einrichtung / ältere Installationen ==

Bei älteren Installationen kann ein Gastzugang auch über die normale Benutzerverwaltung eingerichtet werden. Tragen Sie dafür für eine beliebige Userkennung (z.B. public, gast, anonym o.ä) das Passwort „notsecret“ (ohne Anführungszeichen) ein. Das Passwort wird verschlüsselt in der Datenbanktabelle „userinfo.passwd_sha“ abgelegt.

Sie können dann Links wie z.B.

[http://localhost:8080/superx/servlet/SuperXmlMaske?tid=71190&navi=true&kennung=public http://localhost:8080/superx/servlet/SuperXmlTabelle?tid=71190&navi=true&kennung=public]

erstellen, die Authentifizierung erfolgt mit dem internen Passwort „notsecret“.

Falls Sie sonst standardmäßig LDAP für die Anmeldung verwenden, können Sie ab kern4.9.1 den Parameter login=superx ergänzen, dann erfolgt die Anmeldung nicht über LDAP, sondern eben mit „notsecret“ gegen die SuperX-Datenbanktabelle userinfo. Beispiel:

[http://localhost:8080/superx/servlet/SuperXmlMaske?tid=71190&navi=true&kennung=public&login=superx http://localhost:8080/superx/servlet/SuperXmlTabelle?tid=71190&navi=true&kennung=public&login=superx]

Der Aufruf des normalen Themenbaums für Gastuser ist auch möglich mit,z.B.

http://localhost:8080/superx/servlet/SuperXmlAnmeldung?kennung=public

== Gastzugang verwenden ==

Es gibt drei Möglichkeiten, die Gastkennung zu nutzen, passen Sie die Beispiellinks an Ihre Server an:
* Themenbaum anzeigen http://localhost:8080/superx/servlet/SuperXmlAnmeldung?kennung=gast1

[[Bild:gastzugang_menue2.png|500px]]

* Eine Berichtsmaske anzeigen http://localhost:8080/superx/servlet/SuperXmlMaske?tid=16340&kennung=gast1

[[Bild:gastzugang_menue4.png|500px]]

* Eine Ergebnistabelle anzeigen http://localhost:8080/superx/servlet/SuperXmlTabelle?tid=16340&kennung=gast1

[[Bild:gastzugang_menue5.png|500px]]

Mit den Möglichkeiten der Lesezeichen- bzw. DeepLinks-Erzeugung können Sie weitere Parameter hinzufügen. Wichtig ist der Parameter kennung=gast bzw. bei mehreren Gastkennungen z.B. kennung=gast3.

{{Hinweis|Noch ein Fallstrick beim Testen: Sie sollten beim Testen der Gastkennung einen anderen Browser als Ihren normalen, bzw. in einem privaten Fenster testen, denn sonst bekommen Sie selbst beim Aufruf der Gastseite die Gastkennung, wo aber kein Logout möglich ist. Alternativ leeren Sie die Cookies zum Server.}}

Proxmox

2026-08-21T06:52:32Z

Andrek: /* Download und Installation */

=Download und Installation=
==Installation aus ISO-Image==
https://www.proxmox.com/de/proxmox-ve/erste-schritte
ISO auf USB-Stick:
dd bs=1M conv=fdatasync if=./proxmox-ve_7.2-1.iso of=/dev/sda

Dann Installation mit ext4, swap 4-8 GB RAM

Bei FQDN muss man "jolly.fritz.box" angeben

Repositories: In der Server Ansicht auf "Repositories" gehen, dort dann ein neues Hinzufügen von dem Typ "No-Repositories".
Damit bekommt man immerhin Updates.

=CT-Image nutzen=
Man kann unter Datacenter -> Local verschiedene Container-Images herunterladen:

[[Bild:proxmox_template.png|400px]]

Diese kann man dann installieren. Gemeinhin sind diese performanter als VM-Images.

=VM-Image hochladen=
Zum Hochladen eines ISO Image in die Storage Ansicht wechseln, und bei "local" auf "ISO-Images" gehen. dort kann man dann eine ISO Datei hochladen.
Erst habe ich probiert, die ISO-Images direkt zu kopieren nach /var/lib/vz/images, aber das erschien dann nicht.

root shell:

pveam update
pveam available | grep ubuntu
pveam download local ubuntu-24.04-standard_24.04-2_amd64.tar.z

=Betriebssystem=
Deutsche Locale installieren:
-in /etc/locale.gen die Zeile de_DE.utf8 ent-kommentieren
-locale-gen de_DE.utf8
==IP Nummer des Proxmox Host==
Um Ändern der IP des PROXMOX-Hosts muss man sich auf der Debian-Konsole aals root anmelden, und dann:
* in /etc/network/interfaces die neue IP und Gateway eintragen
* /in /etc/hosts die neue IP eintragen
* Debian 11:
** in /etc/resolv.conf den
nameserver 192.168.0.1
** eintragen
* Debian 12:
* In /etc/systemd/resolved.conf
[Resolve]
DNS=192.168.0.1

Danach reboot.
=VM Erstellen=
==LX container==
Wichtig: die statische IP muss das Format z.B. 192.168.0.220/24 haben

==VM restore==
Beispiel Andres Wekan:

qmrestore vzdump-qemu-109-2025_04_17-15_28_56.vma.zst --force=true 108

Container:
Beispiel restore auf local-lmv mit 16 GB Festplatte:

pct restore 101 ./vzdump-lxc-101-2025_09_07-16_40_19.tar.zst --rootfs local-lvm:16

=System-Konfiguration=
==SSH-USer einrichten==

useradd -g users --create-home -d /home/superx -s /bin/bash superx

==Subscription ändern==
Nach dem Anmelden kommt eine Warnung, dass man keinen Wartungsvertrag hat. Man kann das entfernen, indem man im Knoten auf Updates -> Repositories geht und dort die Repos
-ceph
-pve-enterprise
deaktiviert.
Danach geht man auf "Add", und fügt das Repository "No-subscription" hinzu.
Danach geht man im Menü auf Updates -> Refresh und dann -> Upgrade.

==CT Klonen==
Man wählt das Template sxdemo, und erzeugt einen Klon.
Wichtig: man muss direkt im Netzwerk auf "disconnected"=true stellen, und dann eine neue Netzwerk-IP vergeben, und wieder auf "disconnected"=false
Die vorhandene Festplatte mit 30 GB kann man nicht ändern, man kann aber eine weitere Partition in /mnt anlegen, in beliebiger Größe.

==Lokales Netz abschotten==
Noch nicht getestet: IP des Containers ist privates Netz

If it is desirable for the container to be publicly accessible, there are a few ways to go about it. One is to use iptables to forward host ports to the container, for instance

iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 587 -j DNAT --to-destination 10.0.3.100:587

=Kommandozeilentools=
==Environment==
Das Perl-Script qm benötigt die Locale

dpkg-reconfigure locales
->Installation de_DE.utf8
-> locale-gen de_DE.utf8

==Container verwalten==

pct list
zeigt die installierten Container an

Container stoppen:
pct shutdown <vmid>

Status:
pct status <vmid>

Start:
pct start <vmid>

==VMs verwalten==
Status einer VM:

qm status <<VM-ID>>

===VM Backup===
Beispiel:
vzdump 104 --mode stop --prune-backups 'keep-last=3' --compress gzip --dumpdir /var/backups/proxmox_vms

===VM root-Passwort resetten===
Zuerst bootet man von einer Rettungs-ISO, z.B: gparted
-Dann mountet man die root Partition , mit
fdisk -l
sieht man die Partitionen. Achtung: Proxmox nutzt LVM, man kann also niocht direkt "/dev/sd*" mounten, sondern man muss die Partition darunter
mount /dev/mapper/ubuntu--vg* /mnt

Dann :

mount --bind /dev /mnt/dev
mount --bind /dev/pts /mnt/dev/pts
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
chroot /mnt

Dort kann man dann
passwd
aufrufen und ein neues PW vergeben. Dann mit exit den chroot verlassen

Danach muss man in der umgekehrten Reihenfolge unmounten:
umount /mnt/sys
umount /mnt/proc
umount /mnt/dev/pts
umount /mnt/dev

und dann rebooten

=Siehe auch=
https://decatec.de/home-server/proxmox-ve-installation-und-grundkonfiguration/

Kernmodul Shellscripte

2026-08-14T09:30:57Z

Andrek:

= SuperX-spezifische Scripte: Übersicht =
Für die Administration des DataWarehouse sind Shellscripte vorbereitet, die flexible Werkzeuge zur Datenbankadministration bereitstellen. Die Shellscripte werden in den Update-Scripten aufgerufen, können aber auch zur manuellen Administration benutzt werden. Die wichtigsten Bereiche sind die Masken-Verwaltung und die Ladescripte im Umgang mit Tabellen sowie allgemeine Scripte.
Alle Scripte befinden sich unter $SUPERX_DIR/db/bin, deshalb muss dieser Pfad in der Umgebungsvariable PATH enthalten sein. Die Scripte wurden unter UNIX entwickelt (ohne Endung oder Endung .x), einige davon sind auch nach DOS portiert worden (erkennbar an der Endung .bat).
Einige Scripte lauten "sx_auto_"..., dies bedeutet, dass die Scripte ohne Sicherheitsabfrage ausgeführt werden.
Voraussetzung für den Ablauf der Scripte ist die Eintragung der korrekten Umgebungsvariablen in $SUPERX_DIR/db/bin/SQL_ENV bzw. $SUPERX_DIR\db\bin\sql_env.bat. Wenn der Client jdbc verwendet wird, muss ausserdem die korrekte [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] gesetzt sein.

=Die Umgebungssteuerung SQL_ENV =

Das Script $SUPERX_DIR/db/bin/SQL_ENV steuert die Umgebung und ist für den Betrieb der Kernmodul-Scripte unverzichtbar. Bei einem Update des SuperX-Kernmoduls wird die vorhandene SQL_ENV nicht überschrieben. Änderungen der ausgelieferten SQL_ENV.sam müssen deshalb geprüft und bei Bedarf manuell in die produktive SQL_ENV übernommen werden.

Ab Kernmodul 6.0 liegt $SUPERX_DIR innerhalb der SuperX-Webanwendung:

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

Folgende Variablen müssen geprüft und passend zur Installation gesetzt werden:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
| WEBAPP
| Wurzelverzeichnis der SuperX-Webanwendung
|-
| SUPERX_DIR
| Datenbank- und Modulbereich unter $WEBAPP/WEB-INF/conf/edustore
|-
| DATABASE
| Datenbanksystem; für SuperX ist POSTGRES einzutragen
|-
| DBNAME
| Name der SuperX-Datenbank, standardmäßig superx
|-
| SX_CLIENT
| Verwendeter Datenbankclient; möglich sind psql oder jdbc
|-
| DB_PROPERTIES
| Pfad zur [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|db.properties]], standardmäßig $WEBAPP/WEB-INF/db.properties
|-
| JAVA_HOME
| Installationspfad der Java-Runtime; für Kernmodul 6.0 wird OpenJDK 17 verwendet
|-
| JAVA_OPTS
| Java-Optionen für Kernmodul-Shellscripte wie DOSQL, DOQUERY und die Upgrade-Scripte
|-
| CATALINA_OPTS
| Java-Optionen für einen manuell installierten oder mit SuperX betriebenen Tomcat
|-
| MAILPROG
| Mailprogramm unter UNIX, beispielsweise s-nail oder mailx
|-
| LOGMAIL/ERRORMAIL
| Mailadressen für Log- und Fehlermeldungen der ETL-Scripte
|-
| LOGGING_PROPERTIES
| Logging-Konfiguration des JDBC-Clients
|-
| PGHOST
| Hostname des PostgreSQL-Servers
|-
| DBDELIMITER
| Trennzeichen für Unload-Dateien, standardmäßig ^
|-
| JDBC_CLASSPATH
| Classpath der JDBC-Treiber, Klassen und benötigten Jakarta-Bibliotheken
|-
| XML_CLASSPATH
| Classpath der XML-Werkzeuge
|-
| FM_DEBUG
| Wenn FM_DEBUG=true gesetzt wird, bleiben die von DOSQL erzeugten temporären SQL-Dateien zur Fehlersuche erhalten
|}

==Java-Optionen für Kernmodul 6.0 ==

Die Java-Optionen werden an dieser Stelle zentral dokumentiert. Andere Artikel sollen auf diesen Abschnitt verweisen, damit die Konfiguration nicht mehrfach gepflegt werden muss.

Tragen Sie folgenden vollständigen Block in die SQL_ENV ein. Bei einem Tomcat aus den Ubuntu- oder Debian-Paketen wird derselbe Block in /etc/default/tomcat10 verwendet. Passen Sie die Speicherwerte an die Größe des Servers an:

<source lang="bash">
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
JAVA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME JAVA_OPTS
</source>

Wenn der eigene Tomcat CATALINA_OPTS verwendet, tragen Sie stattdessen folgenden vollständigen Block in dessen Startumgebung ein:

<source lang="bash">
WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
CATALINA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME CATALINA_OPTS
</source>

Zusätzliche Optionen für JMX, eigene Truststores oder besondere LDAP-Konfigurationen werden nur bei Bedarf ergänzt. Ungeschützte JMX-Ports und die Deaktivierung von Sicherheitsprüfungen gehören nicht in die allgemeine Standardkonfiguration.

==JDBC-Classpath für Tomcat 10 ==

Tomcat 10 verwendet die Jakarta-Servlet-API. Der JDBC_CLASSPATH muss deshalb die Jakarta-Bibliothek und $WEBAPP/WEB-INF/classes enthalten:

<source lang="bash">
JDBC_CLASSPATH="$WEBAPP/WEB-INF/lib_ext/jakarta.servlet-api-6.0.0.jar:$WEBAPP/WEB-INF/classes"
for i in $LIB_PATH/*.jar; do JDBC_CLASSPATH="$JDBC_CLASSPATH:$i"; done
XML_CLASSPATH=$JDBC_CLASSPATH
export JDBC_CLASSPATH XML_CLASSPATH
</source>

Ein alter Classpath mit servlet-api.jar kann zu java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServlet führen.

Die SQL_ENV sollte in jeder Shell geladen werden, in der Kernmodul-Scripte ausgeführt werden:

<source lang="bash">
. $SUPERX_DIR/db/bin/SQL_ENV
</source>

Der Aufruf kann beispielsweise in ~/.bashrc oder ~/.profile eingetragen werden.

==Nutzung der SQL_ENV unter HISinOne-BI ==

Die SuperX-Shellscripte lassen sich auch in HISinOne-BI unter Linux nutzen. Eine Beispielkonfiguration befindet sich unter $WEBAPP/WEB-INF/conf/edustore/db/bin/SQL_ENV_his1.sam. Setzen Sie auch dort WEBAPP, SUPERX_DIR, JAVA_HOME, DB_PROPERTIES und den Jakarta-Classpath entsprechend der tatsächlichen Installation.

Normalerweise wird für HISinOne-BI der JDBC-Client verwendet:

<source lang="bash">
SX_CLIENT=jdbc
export SX_CLIENT
</source>

{{Hinweis|Die Datei muss nicht SQL_ENV heißen. Für eine spezielle Konfiguration kann ein ergänzender Name wie SQL_ENV_FHDO verwendet werden.}}

= Datenbank- und SQL-Scripte =
==Propadmin ==
Der PropAdmin ist ein kleines Werkzeug, um den Zugriff auf jdbc-Datenbanken zu testen und die [[#dbProperties|''Verbindungsparameter'']] in einer übergebenen properties-Datei zu sichern. Wenn keine graphische Umgebung eingerichtet ist, müssen Sie die alle Verbindungsparameter manuell in die db.properties eintragen. Nur das Passwort kann mit dem propadmin bearbeitet werden.
Eine Musterdatei für PostgreSQL liegt unter $WEBAPP/WEB-INF/db-postgres.properties. Wenn kein Dateiname als Parameter übergeben wird, wertet das Script die Umgebungsvariable DB_PROPERTIES aus.
{| class="wikitable"
|-
| Syntax UNIX
| propadmin.x -nogui(optional) <Dateipfad zu db.properties>(optional)
|-
| Syntax DOS
| propadmin.bat <Dateipfad zu db.properties>(optional)
|}
Wenn die Default-Dateiencodierung der aktiven Locale für die Passwort-Verschlüsselung nicht ausreicht, wird eine Fehlermeldung ausgegeben. Unter Windows / DOS ist die Vorbelegung Cp1252 bei deutscher Codepage ausreichend, unter Unix wird die deutsche [[Kern_Installation_Upgrade#Zeichencodierung|Locale]] benötigt.

==DOSQL ==
Zum Absetzen beliebiger SQL-Kommandos werden die Befehle DOSQL und DOQUERY genutzt.
DOSQL kann SQL-Anweisung(en) in der der Datei (als Parameter) in der SuperX-Datenbank ausfuehren.
{| class="wikitable"
|-
| Syntax
| DOSQL "Dateiname mit sql-Anweisung(en)" header (true,false)(optional) Ausgabedatei(optional)
|-
| Beispiel
| DOSQL "/home/superx/db/isql/test.sql" false "^" output.txt
|}
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden.
Wenn
FM_DEBUG = true
export FM_DEBUG
gesetzt wird, werden bei Freemarker Scripten von DOSQL die *.tmp.sql-Dateien nicht gelöscht.

==DOQUERY ==
Shellvariablen setzen und eingegebene SQL-Anweisung (als Parameter) in der SuperX-Datenbank ausfuehren.
{| class="wikitable"
|-
| Syntax
| DOQUERY "sql-Anweisung" header (true,false)(optional) Delimiter(optional) Ausgabedatei(optional)
|-
| Beispiel
| DOQUERY "select name from userinfo" false "^" output.txt
|}
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden.
=XML-Scripte=
==sx_transform.x ==
Transformiert eine xml-Datei mit einer übergebenen XSL-Datei und gibt das Ergebnis in einen Ausgabekanal aus (stdout oder Datei). Dabei wird der in SuperX integrierte XML-Parser Xerces und der XSL-Prozessor Saxon benutzt.
{| class="wikitable"
|-
| Syntax
| sx_transform.x -IN:xml-Datei -XSL:xsl-Datei -OUT:Ausgabedatei -method:Ausgabeformat (text, xml,html,rtf,pdf) (optional) -params:Parameter(optional)
|-
| Beispiel
| sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html
|}
Als Parameter "method" kann ein spezielles Ausgabeformat gewählt werden, z.B. text (siehe Xalan-Doku). Bei rtf wird der RTF-Construktor Jfor aufgerufen, bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert. Wir gehen also nicht davon aus, dass .fo-Dateien die Eingabequelle darstellen.

Stylesheet Parameter werden mit "," getrennt optional angefügt, z.B.

sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html "-params:Jahr=2020,Monat=12"

==saxon_transform.x==
Wie sx_transform.x transformiert das Script XML via XSLT, hier werden allerdings Saxon-spezifische Parameter ermöglicht.
{| class="wikitable"
|-
| Syntax
| saxon_transform.x xml-Datei xsl-Datei Ausgabeformat (text, xml,html) (optional) Ausgabedatei (optional) Parameter (optional)
|-
| Beispiel
| sx_transform.x myxml.xml myxsl.xsl output.htm html
|}
Bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert.

Wenn ein XSL-Script mehrere Ausgabedateien erzeugen soll, kann dieses Script ggü. sx_transform.x Vorteile haben.
==show_fop_fontlist.x==
Zeigt die installierten Fonts für PDF Erzeugung mit XSL-FO an.
Das Script hat keine Argumente.
==sx_validate.x==
sx_validate.x validiert eine XML-Datei
*ob sie wohlgeform ist
*ob sie zu einem optional übergebenen Schema (XSD-Datei) valide ist.
sx_validate.x XML-Datei SCHEMA-Datei (optional)
==sx_xmlfileappender.x==
Das Script ''sx_xmlfileappender.x'' faßt mehrere XML-Dateien in einem übergebenen Pfad zu eine rDatei mit einem neuen root-Knoten "artificalroot" zusammen.

Aufruf:
sx_xmlfileappender.x Path file(regex oder Dateiname mehrere mit , getrennt) Outputfile

= Codierung in ISO und UTF-8=
Ältere Systeme arbeiten in der Regel mit der Zeichencodierung ISO-8859-1 bis ISO-8859-9. Dieser Zeichensatz wird auch LATIN-1 genannt. Die UNIX-Locale de_DE@euro entspricht z.B. ISO-8859-9 und enthält das EUR-Symbol.

Aktuelle SuperX-Installationen arbeiten in der Regel mit der UTF-8 Codierung, dies wird bei der [[Kern_Installation_Upgrade#Zeichencodierung|Installation]] gesetzt.

Mit dem Wechsel von ISO-Codierung zu UTF8 bleibt oft der Bedarf bestehen, Dateien hin- und herzucodieren. Sei es, weil beim Entladen aus einer entfernten Datenbank noch das ISO-System genutzt wird, oder bei der Migration eines Systems. Nach unserer Erfahrung sollten Umlaute in Dateinamen unbedingt vermieden werden.
SuperX bietet unter UNIX Shellscripte zur Erfassung und Änderung der Zeichencodierung (Verzeichnis $SUPERX_DIR/db/bin). Im Wesentlichen werden dabei die Unix-Kommandos file und recode genutzt, die Shellscripte machen den Umgang mit umfangreichen Dateilisten komfortabler. Bei der Verarbeitung von Dateilisten sollte man die Scripte sehr vorsichtig einsetzen, es finden keine Sicherheitsüberprüfungen statt.
{{Achtung| Die Scripte wurden bisher nur unter Linux mit bash getestet, andere UNIXe wie BSD verhalten sich ggf. anders als erwartet. Daher bitte mit Vorsicht benutzen.}}

==sx_show_encoding.x ==
Das Script zeigt die Encodierung einer Datei an.
{| class="wikitable"
|-
| Syntax
| sx_show_encoding.x <Datei>
|-
| Beispiel
| sx_show_encoding.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| /home/superx/webserver/tomcat/webapps/superx/WEB-INF/web.xml: XML
ISO
|}
Das Script nutzt verschiedene UNIX-Tools, je nach System kann die Ausgabe variieren. Bei XML-Dateien wird auch der Dateiinhalt (XML-Header) ausgewertet.
==sx_recode_iso2utf.x ==
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_iso2utf.x <Datei>
|-
| Beispiel
| sx_recode_iso2utf.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| --keine--
|}
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="ISO-8859-1"?>
der Header
<?xml version="1.0" encoding="UTF-8"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
==sx_recode_utf2iso.x ==
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_utf2iso.x <Datei>
|-
| Beispiel
| sx_recode_utf2iso.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml
|-
| Ausgabe
| --keine--
|}
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="UTF-8"?>
der Header
<?xml version="1.0" encoding="ISO-8859-1"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
==sx_list_isofiles.x ==
Das Script listet alle ISO-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
{| class="wikitable"
|-
| Syntax
| sx_list_isofiles.x <Pfad>
|-
| Beispiel
| sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF
|-
| Ausgabe
| webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt
[...]
webserver/tomcat/webapps/superx/WEB-INF/db.properties
|}
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script [[#sxrecodeisofilesx|''sx_recode_isofiles.x'']] als Eingabedatei genutzt werden.
sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >iso.txt
==sx_recode_isofiles.x ==
Das Script konvertiert alle Dateien in der übergebenen Dateiliste von ISO nach UTF-8:
{| class="wikitable"
|-
| Syntax
| sx_recode_isofiles.x <Datei>
|-
| Beispiel
| sx_list_isofiles.x iso.txt
|-
| Ausgabe
| --Keine--
|}
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes [[#sxlistisofilesx|''''sx_list_isofiles.x'''']].
==sx_list_utf8files.x ==
Das Script listet alle UTF-8-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
{| class="wikitable"
|-
| Syntax
| sx_list_utf8files.x <Pfad>
|-
| Beispiel
| sx_list_utf8files.x webserver/tomcat/webapps/superx/WEB-INF
|-
| Ausgabe
| webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt
[...]
webserver/tomcat/webapps/superx/WEB-INF/db.properties
|}
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script [[#sxrecodeutffilesx|''sx_recode_utf8files.x'']] als Eingabedatei genutzt werden.
sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >utf.txt
==sx_recode_utf8files.x ==
Das Script konvertiert alle UTF-8 Dateien in der übergebenen Dateiliste von UTF-8 nach ISO:
{| class="wikitable"
|-
| Syntax
| sx_recode_utf8files.x <Datei>
|-
| Beispiel
| sx_recode_utf8files.x utf.txt
|-
| Ausgabe
| --Keine--
|}
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes [[Kernmodul_Shellscripte#sx_list_utf8files.x|sx_list_utf8files.x]].

=Umgang mit Tabellen =
In SuperX werden ständig Tabellen erstellt / geladen / entladen. Zu diesem Zweck wurden Shellscripte entwickelt.
==sx_unload_table.x ==
Entlädt die Inhalte der Tabelle nach <<Dateiname>>(optional) oder <<name>>.unl
{| class="wikitable"
|-
| Syntax
| sx_unload_table.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_unload_table.x userinfo
|}

==sx_upload_table.x ==
Löscht die Inhalte der Tabelle <<name>>, und lädt die Inhalte einer Datei in die Tabelle mit [[#sxuploadrecords|''sx_upload_records'']]. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
{| class="wikitable"
|-
| Syntax
| sx_upload_table.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_upload_table.x userinfo
|}

==sx_upload_records.x ==
Lädt die Inhalte einer Datei in die Tabelle, ohne vorherige Inhalte zu löschen. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
{| class="wikitable"
|-
| Syntax
| sx_upload_records.x <<name>> <<Dateiname>>(optional)
|-
| Beispiel
| sx_upload_records.x userinfo
|}
Bei Postgres als DB-System wird eine Java-Klasse (de.superx.bin.UnlFileConverter) aufgerufen, die die Unload-Datei entsprechend einer Spezifikation aufbereitet (siehe $SUPERX_DIR/db/conf/unldescr*).
Wenn der jdbc-Client benutzt wird, können umfangreiche Parameter übergeben werden (Import mit Spaltenüberschriften, Ausgabe von Fehlerprotokollen). Vergleichen Sie die Kommentare im Script.
==sx_schema.x ==
Entlädt das Schema einer Tabelle in einem vorgegebenen Format.
{| class="wikitable"
|-
| Syntax
| sx_schema.x Tabelle format (pg|ids|ansi|xml|HIS)) (optional) Ausgabedatei (optional)
|-
| Beispiel
| sx_schema.x userinfo ids myschema.sql
|-
| Die Formate
| Die Formate sind SQL für PostgreSQL oder ANSI sowie XML beziehungsweise ein XML-Format in Anlehnung an die Datenbank-DTD der HIS.
|}

= Modulverwaltung =
Die Verwaltung der Module, einschließlich Installation, Aktualisierung, Sicherung und Logdateien, erfolgt über zentrale Shellscripte in $SUPERX_DIR/db/bin. Die Shellscripte bilden die operativen Hüllen um die eigentlichen SQL-Scripte. Diese werden zum Teil manuell und zum Teil automatisch aus einer zentralen Steuerdatei erzeugt:
$SUPERX_DIR/db/module/<<Modulname>>/conf/<<Modulname>>.xml
Für PostgreSQL werden daraus die benötigten Installations- und Aktualisierungsscripte erzeugt.

== module_scripts_create.x ==
Das Script erzeugt die Installationsdateien für ein Modul nach dem Schema 
<<Modulname>>_<<Scriptaktion>>_<<Kürzel für Datenbanksystem>>.sql
Beispielsweise wird für das BAU-Modul aus der Datei $BAU_PFAD/conf/bau.xml das Script bau_load_pg.sql erzeugt, das die Rohdaten unter PostgreSQL lädt.
{| class="wikitable"
|-
| Syntax
| module_scripts_create.x -Modulkürzel- -Modulpfad- -Datenbanksystem-
|-
| Beispiel
| module_scripts_create.x bau $BAU_PFAD POSTGRES
|}
Im Grunde handelt es sich um XML-Transformationen. Die Stylesheets für dieses Script befinden sich im Verzeichnis $SUPERX_DIR/db/conf, und die XML-Datei für das Module in $SUPERX_DIR/db/module/-Modulname-/conf. Wenn die Datei nicht gefunden wird, bricht das Script ab.

== module_install.x ==
Installiert ein Modul -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.

{| class="wikitable"
|-
| Syntax
| module_install.x -Modulkürzel- -Modulpfad-
|-
| Beispiel
| module_install.x bau $BAU_PFAD
|}

== module_drop.x ==
Löscht die Komponenten eines Moduls -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.

{| class="wikitable"
|-
| Syntax
| module_drop.x -Modulkürzel- -Modulpfad-
|-
| Beispiel
| module_drop.x bau $BAU_PFAD
|}

== Entladen ==
Das Entladescript lautet $SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.x. Die Entladeparameter werden in folgender Datei festgelegt: 
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_ENV
Entladeroutine bei mandantenfähigen Installationen:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_ENV
Dokumentation zu den jew. Parametern finden Sie in den jeweiligen Administrationshandbüchern der Module. Meist kann man Start-Semester oder -Jahre für das Entladen festlegen. Immer muß man auch das Datenbank-Vorsystem festlegen (Hostname, Kennung etc) sowie, bei HIS-Systemen, die Versionsnummer.
== module_etl.x ==
Aktualisiert ein Modul -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.
{| class="wikitable"
|-
| Syntax
| module_etl.x -Modulname- -Modulpfad-
|-
| Beispiel
| module_etl.x bau $BAU_PFAD
|}
Die folgende Abbildung zeigt, wie die Komponenten zusammenhängen (klicken Sie auf die Grafik, um sie zu vergrößern):

Zunächst werden die Rohdaten geladen, die Daten vorbereitet, transformiert, und nachbereitet. Danach werden die Hilfstabellen erzeugt und, bei erfolgreichem durchlaufen, das Standdatum aktualisiert.

[[Bild:etl.png|417x313px]]

Bei Fehlern im ETL-Prozeß wird die Sicherung wiederhergestellt, und eine Mail an die Administrator_in verschickt. Außerdem werden die übernommenen Daten überprüft; wenn z.B. Schlüssel fehlen oder Rohdaten falsch zu sein scheinen, wird dies als Attachment an die Log- oder Fehlermail angehängt.
In der Praxis wird dieses Script nicht direkt von Cronjobs ausgeführt, sondern von einem Shellscript, das vorher die Umgebung einrichtet. Das folgende Beispiel zeigt ein Update-Script für das BAU-Modul:
bau_update.x
<source lang="bash">
#!/bin/sh
. /home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore/db/bin/SQL_ENV
ERRORMAIL="bau-admin@hochschule.de"
export ERRORMAIL
LOGMAIL=$ERRORMAIL
export LOGMAIL
module_etl.x bau $BAU_PFAD >$BAU_ERRORDAT 2>&1
</source>
Wie Sie sehen ist es möglich, für jedes Modul unterschiedliche Mailadressen zuzuweisen. Die Mailadressen werden systemweit in der [Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] eingetragen.
Im allgemeinen ETL-Prozeß wird standardmäßig auch die Tabelle protokoll in einem festzulegendem Rhythmus (Konstante Löschung Protokoll (Tage)) gelöscht. Beim Vorgabewert 90 werden bei jeder ETL-Routine Einträge, die älter als 90 Tage sind, gelöscht.

=== Hochschulspezifische Transformationen im ETL-Prozess ===

Zusätzlich lassen sich im ETL-Prozeß hochschulspezifische Scripte ausführen (und überwachen). Dazu müssen Dateien mit einem gewissen Namensschema im Stammverzeichnis des Moduls vorhanden sein. Es gibt einen vereinfachten und einen erweiterten Modus für hochschulspezifische Transformationen.
*Einfacher Modus
**Wenn im Modulpfad die Datei "preparation.sql" existiert, wird sie nach dem LOAD-Schritt ausgeführt.
**Wenn im Modulpfad die Datei "finalize.sql" existiert, wird sie nach dem TRANS-Schritt ausgeführt.
* Erweiterter Modus / mandantenspezifische Scripte
**Wenn im Modulpfad Dateien nach dem Schema <<Modulname>>_<<ETL-Schritt>>_<<Mandatennr.>>.sql exisitieren, werden diese jeweils nach dem "normalen" ETL-Schritt ausgeführt.

Wenn also z.B. die Datei
$COB_PFAD/cob_trans_70.sql
existiert und in der SQL_ENV die Umgebungsvariable $MANDANTID auf "70" steht, dann wird das Script nach dem normalen Trans-Schritt ausgeführt und nach
L_cob_trans_mandant_70.log
geloggt.

Der erweiterte Modus erlaubt die beliebige Anpassung eines Modus an eigene Bedürfnisse, z.B. Schlüsselumsetzung o.ä. Gleichzeitig erlaubt er einen echten mandentenfähigen Betrieb der ETL-Scripte.

===Logging der Shellscripte ===
Hinweis: bei mandantenfähigen Installationen steht vor der Endung .log immer die MandantID.

==== Installation / Upgrade ====
Fürs Kernmodul lauten die Dateien bei der Installation:
$SUPERX_DIR/db/install/L_*.log
Beim Upgrade:
$SUPERX_DIR/db/install/upgrade/upgrade.log
Für alle anderen Komponenten:
$SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Installationsschritt>>.log
==== Laderoutinen ====
Für alle Module sind die Dateien wie folgt benannt:
Entladeroutine:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.err
Entladeroutine bei mandantenfähigen Installationen:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_unload.err

Laderoutine:
$SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Ladeschritt>>.log
wobei <<Ladeschritt>> wie folgt aufgebaut ist:
# Unload (Entladen aus Vorsystem)
# Load (CSV-Upload)
# Transformation (Schlüsselharmonisierung, Prüfroutinen)
# Aggregation (Aufbau der Hilfstabellen)
# System (Ladedatum aktualisieren, Datenbank-Wartung)
Wenn die Laderoutine erfolgreich ist, werden alle Schritte hintereinander ausgeführt und geloggt. Wenn nicht, dann wird der jew. Schritt zuende geführt, und dann die Laderoutine gestoppt. Wenn also z.B. beim LOAD ein Fehler auftritt, dann wird der Schritt "Transformation" gar nicht erst begonnen. So ist sichergestellt daß die Auswertungen trotz Fehler laufen.

=== Debugging von Freemarker Scripten ===
Da die Laderoutinen oft mit Freemarker Scripten arbeiten, werden diverse SQL-Scripte nur zur Laufzeit generiert und ausgeführt, und danach wieder gelöscht. Um die Laderoutinen transparenter "beobachten" zu können, können Sie die die Löschung der Scripte mit dem Parameter
FM_DEBUG="true"
export FM_DEBUG
Wenn FM_DEBUG = true gesetzt wird, werden bei Freemarker Scripten von [[Kernmodul_Shellscripte#DOSQL|DOSQL]] die *.tmp.sql-Dateien nicht gelöscht. Sie können den Parameter in der aktuellen Shell setzen, oder permanent in der [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]].

==Kettle-Jobs starten==
Da Kettle in der Webanwendung integriert ist, können Sie Kettle Jobs auch ohne die PDI-Standalone-Installation per Kommandozeile ausführen. Wenn die [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] eingerichtet und geladen ist, geben Sie z.B. einfach ein:

sx_kitchen.x -file "sospos_res1.kjb" -norep
Die Parameter werden direkt an die Java Anwendung "kitchen" weitergereicht, d.h. weitere Dokumentation finden Sie in unserem [[Kettle_Kurs_Teil_2#Kitchen|Kettle-Kurs]].

=Installation und Wartung=
==Patch einspielen==
Für SuperX können spezielle Patch-Dateien per Kommandozeile installiert werden. Vorbedingung ist, dass die bash und das Paket unzip installiert sind.
patch_apply.x
Das Script entpackt eine übergebene Patch-Datei (zip-File), und installiert die Dateien und DB-Operationen für die jeweils installierten und zum Patch passenden Module. Sie starten es direkt aus dem Patchordner, in dem der zu installierende Patch liegt:
patch_apply.x -PatchFile-
Ein Beispiel:
patch_apply.x patch_2011-06-01_superx_iso.zip
Dabei wird in dem Verzeichnis der Patch entpackt und ausgeführt. Je nach Patch muss auch ein Tomcat Neustart erfolgen, ein entsprechender Hinweis befindet sich in der Patch-Dokumentation.
Wenn ein Patch auch Dateien unterhalb von webapps/superx enthält, müssen Sie im Falle von Tomcat Clusterbetrieb den Patch auf alle Tomcat Hosts übertragen, entweder direkt oder mit git / rsync.
Weitere Hinweise zum Script finden Sie im [[Kern_Installation_Upgrade#Patch_einspielen|Installationshandbuch]].
{{Hinweis|Bei HISinOne-BI funktioniert das patch-apply Script nicht, der Patch mit dem Kürzel "webapps" im Dateinamen wird einfach in webapps/superx entpackt, und in der Regel sollten die jew. Module geupgradet werden. Weitere Hinweise finden Sie in der jew. Patch-Readme.}}
==JasperReports kompilieren==
Wenn Sie mit Unterberichten arbeiten, müssen Sie kompilierte .jasper-Dateien einbinden und ausliefern. Da dieser Dateityp normalerweise (und richtigerweise) im ".gitignore" ist, d.h. nicht über git ausgeliefert werden kann, können Sie die Dateien auch direkt auf dem Applikationsserver mit der exakt passenden JR-Version erzeugen. Typischerweise führen Sie das Script im Ordner WEB-INF/reports aus. Der Aufruf:
cd $WEBAPP/WEB-INF/reports
java $JAVA_OPTS -cp "$JDBC_CLASSPATH" de.superx.bin.SxJasperCompiler <JRXML-Datei>
Der Workflow ist wie folgt:
* Die Quelldatei.jrxml ist die XML-Beschreibungsdatei des Berichts
* Der compile erzeugt aus der Quelldatei.jrxml eine Datei Quelldatei.jasper im gleichen Verzeichnis
* Die Quelldatei.jasper ist kompilierte Beschreibungsdatei für den Bericht, und wird in Unterberichten und Booklets genutzt. Weitere Details siehe unser [https://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/f_AufbaudesHauptberichts.htm JR-Handbuch].
==LDAP User deaktivieren==
Ausschließlich für SuperX-Standalone-Anwender können wir im System eine Gültigkeit von UserAccounts und automatisiertes Sperren von LDAP-Usern mit Sperr-Merkmal einbauen.
Die Tabelle userinfo und das entsprechende Formular zum Userbearbeiten hat die Merkmale Beginn Gültigkeit (gueltig_von) und Ende Gültigkeit (gueltig_bis), so dass SuperX-Standalone Hochschulen z.B. für befristete Mitarbeiter_innen in der Userverwaltung direkt eintragen können, dass ein Mitarbeiter sich z.B. nach dem 31.12.2024 nicht mehr anmelden können soll.
Wenn die Hochschule eine Passwortkontrolle via LDAP macht, kann diese per Script User mit einem entsprechenden Merkmal wie userLocked=true automatisiert zu sperren.
Hierfür setzt das Script den Eintrag userinfo.maxVersuch (also die maximal erlaubten Anmeldeversuche) auf 0 gesetzt, als "Ende Gültigkeit" wird das Vortagsdatum eingetragen sowie die Spalte ''password_sha'' (verschlüsseltes SuperX-Passwort) geleert.

Aufruf:
sx_ldap_lockout.x Pfad/zu/db.properties pfad/zu/superx_standalone_ldap.properties
Das Script kann nächtlich ausgeführt werden.

= Masken-Verwaltung =
Die Masken-Verwaltung ist detailliert im [[Masken-Tutorial|Entwicklerhandbuch SuperX]] beschrieben. Hier nur ein paar Hinweise zur Verwaltung der Masken. Zum Erzeugen und Verändern von Masken gibt es unter UNIX eine Kommandoschnittstelle, die auf dem Gebrauch folgender Skripte beruht. Die Skripte stehen unter dem Verzeichnis
$SUPERX_DIR/db/bin
und erzeugen oder verwenden Dateien in dem gegenwärtigen Arbeitsverzeichnis. Nach dem Einspielen der Datenbank sollten Sie darauf achten, den Dateien Ausführungsberechtigung (chmod 750 *) zu geben.

==Eine Maske suchen ==
Wenn Sie eine Maske suchen, sollten die die Felder tid oder name in der Tabelle maskeninfo durchsuchen. Das folgende Script macht dies automatisch:
sx_search_mask
{| class="wikitable"
|-
| Aufruf:
| sx_search_mask <String>
|-
| Aktion:
| sx_search_mask sucht die Masken, deren Name <String> enthält
|-
| Ausgabe: .
| tid, name der gefundenen Masken
|}

==Eine Maske sichern und entladen ==
Um eine Maske zu sichern, müssen Sie die entsprechenden Einträge in den Tabellen
# felderinfo,
# masken_felder_bez,
# maskeninfo,
# sachgeb_maske_bez,
# maske_system_bez
selektieren und sichern. Für dies gibt es das Script sx_select_mask.
sx_select_mask
{| class="wikitable"
|-
| Aufruf:
| sx_select_mask <TID>
|-
| Aktion:
| sx_select_mask entlädt alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez, maske_system_bez zur Maske mit tid = <TID>.
|-
| Ausgabe:
| Fünf Dateien:
# <TID>_felderinfo.unl,
# <TID>_masken_felder_bez.unl,
# <TID>_maskeninfo.unl,
# <TID>_sachgeb_maske_bez.unl,
# <TID>_maske_system_bez.unl

|}

=====Eine Maske neu einfügen =====
Um eine Maske neu einzufügen, müssen Sie die entsprechenden Einträge in den Tabellen
# felderinfo,
# masken_felder_bez,
# maskeninfo,
# sachgeb_maske_bez,
# maske_system_bez
einfügen. Dafür gibt es das Script sx_insert_mask.

sx_insert_mask
{| class="wikitable"
|-
| Aufruf:
| sx_insert_mask <TID> [<neue TID>] [j]
|-
| Aktion:
| sx_insert_mask lädt den Inhalt der fünf Dateien
# <TID>_felderinfo.unl,
# <TID>_masken_felder_bez.unl,
# <TID>_maskeninfo.unl,
# <TID>_sachgeb_maske_bez.unl,
# <TID>_maske_system_bez.unl
in die jeweiligen Tabellen der SuperX-Datenbank. Mit "j" wird die Sicherheitsabfrage umgangen.

|}

Falls <neue TID> nicht angegeben wird, werden die Metadaten wieder mit der alten TID in die Datenbank eingespielt (=Update).
Falls <neue TID> angegeben wird, werden die Metadaten mit der neuen TID in die Datenbank eingespielt (=Insert). Dabei werden alle TIDs in den abhängigen Tabellen angepasst. So können Masken sehr einfach kopiert werden. Eine neue TID bekommt man durch die Wahl der nächsten Zehnerzahl, die größer als die größte vorkommende Nummer ist. Die größte vorkommende Nummer erhält man durch Ausführung des folgenden SQL-Ausdrucks mit Hilfe des Kommandos DBACCESS:
select max(tid) from maskeninfo;

{| class="wikitable"
|-
| !
| Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis xxxx0000 bis xxxx9990 liegen, wobei xxxx der von der HIS verwandten Hochschulnummer entspricht. Die Zehnerschritte ergeben sich daraus, dass die dazwischen liegenden Nummern für die Maskenfelder (Tabelle felderinfo) reserviert sind<ref><blockquote> Aus historischen Gründen liegen die Nummern aus Karlsruhe im Bereich 0-9990, aus Duisburg im Bereich 10000-19990.
</blockquote></ref>.
|}

Wie im Abschnitt [[Kern_Benutzerverwaltung|Userverwaltung]] beschrieben, kann die neue Maske Benutzern oder Gruppen zugänglich gemacht werden.

== Eine Maske löschen ==
Um eine Maske zu löschen, müssen Sie die Einträge in den oben genannten Tabellen entfernen. Dafür gibt es das Script sx_delete_mask
sx_delete_mask
{| class="wikitable"
|-
| Aufruf:
| sx_delete_mask <TID>
|-
| Aktion:
| sx_delete_mask löscht alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez und maske_system_bez zur Maske mit tid = <TID>.
|}

==Änderungen an einer Maske vornehmen ==
1. Selektieren der Metadaten der betreffenden Maske: sx_select_mask <TID>
2. Editieren der fünf Metadaten-Dateien ,,<TID>_..."
3. Abspeichern der neuen Metadaten: sx_insert_mask <TID>
==Masken per Kommandozeile==
In diversen Szenarien kann es sinnvoll sein, Masken nicht nur im Browser über die Webanwendung auszuführen, sondern über Kommandozeile, also ohne laufenden Tomcat:
* Für Entwicklungszwecke kann es praktisch sein, wenn man keinen laufenden Tomcat braucht, und Masken z.B. in Eclipse ausführt und debuggen kann
* Große Ergebnisdateien lassen sich leichter erzeugen, weil man von der Webanwendung unabhängig ist und z.B. dem Kommandozeilenaufruf mehr Arbeitsspeicher zuteilt.
* Für die Verteilung von Downloads kann es sinnvoll sein, Berichtsergebnisse in Dateiform zu generieren und im [[Kern_Konfiguration#Downloads_einrichten_und_verteilen|Download-Bereich]] zu verlinken.

Masken können bei eingerichteter Kommandozeilenumgebung direkt ausgeführt werden:

* Unter SuperX: [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]]
* Unter HISinOne-BI: [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|Nutzung der SQL_ENV unter HISinOne-BI]], oder Einrichtung einer HISinOne-Umgebung unter Eclipse: https://wiki.his.de/mediawiki/index.php/Einrichtung_einer_HISinOne-Arbeitsumgebung

Damit der Aufruf unter Kernmodul 6.0 funktioniert, muss der zentral unter [[#JDBC-Classpath_für_Tomcat_10|JDBC-Classpath für Tomcat 10]] dokumentierte Jakarta-Classpath geladen sein.

Der Kommandozeilenaufruf sieht unter Linux wie folgt aus:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:Maskennummer -out:Ausgabedatei -user:Benutzerkennung "-params:Parameter..." -logger:$SUPERX_DIR/db/conf/logging.properties

Hier ein Beispiel für den Aufruf der Maske "Studierende und Studienanfänger (Zeitreihe)" (tid=16000) als Admin-User und deren Ausgabe in die Datei "test.htm":

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.htm -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel läßt sich fortführen für andere Ausgabeformate, hier z.B. für PDF:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.pdf -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_fo_pdf.xsl&contenttype=application/pdf" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel zeigt daß über das Params-Argument beliebige Ausgabeformate übergeben werden können, z.B. auch Excel (xlsx):

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.xlsx -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_xls.xsl&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -logger:$SUPERX_DIR/db/conf/logging.properties

oder als CSV Export:
java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.csv -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&contenttype=text/csv" -logger:$SUPERX_DIR/db/conf/logging.properties

Über den "Deep-Link"-Button lassen sich beliebige Parameter-Zeichenketten erzeugen und nutzen. Auch Aufrufe von JasperReports sind damit möglich, z.B. ein Studierendenbericht als Excel-Report:

java -cp $JDBC_CLASSPATH $JAVA_OPTS -Xmx2048m de.superx.bin.ExecuteMask -tid:160440 -out:$OUTFILE "-params:maxoffset=1000000&stylesheet=tabelle_160440_semester_geschlecht.jrxml&tablestylesheet=tabelle_160440_semester_geschlecht.jrxml&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -user:superx -logger:$SUPERX_DIR/db/conf/logging.properties

Bei Datenblattberichten sollte auch der Parameter tablestylesheet übergeben werden.

Unter Eclipse sieht der Aufruf für das erste Beispiel (Ausgabe nach html) so aus:

[[Bild:execute_mask_eclipse1.png|680px]]

Und hier die Parameter:

[[Bild:execute_mask_eclipse2.png|680px]]

Das Beispiel lässt sich leicht auf andere Plattformen (DOS, Netbeans) übertragen.

Sie können auch Parameter bewußt leer übergeben, indem Sie den Parameter ohne Wert übergeben, hier z.B. den Parameter „Sprache“:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:70170 -out:test.htm -user:admin "-params:Stichwort=REPORT&Sprache=" -logger:$SUPERX_DIR/db/conf/logging.properties

==Ausführen von JasperReports ==
Neben der Ausführung im Browser gibt es eine "Kommandozeilenversion" des Aufrufs: sx_jasper.x

{| class="wikitable"
|-
| Aufruf:
| sx_jasper.x -JRXML:<JRXML-Datei> -XML:<Datei mit XML-Datenquelle> -db_properties:Pfad_zur_db.properties -IGNORE_PAGINATION:<true oder false> und optional -JASPER:<Jasper-Datei> -JRPRINT:<Jrprint-Datei> -OUT:<Ausgabedatei>
|-
| Aktion:
| sx_jasper.x führt einen JasperReports-Task aus. Die Datenquelle kann entweder xml sein (Parameter -XML), oder eine Datenbankverbindung in der Datei db.properties. Das Ergebnis wird in eine Datei <Ausgabedatei> ausgegeben.
Wenn keine Ausgabedatei angegeben wird, wird der jrxml-Dateiname verwendet, und eine PDF-Ausgabe erzeugt.
|}
Sie können es mit einer Maskenausführung kombinieren, oder zum Entwickeln. Bei der Maskenausführung können Sie aber im Script [[Kernmodul_Shellscripte#Masken_per_Kommandozeile|ExecuteMask]] direkt JasperReports aufrufen.

= Mailversand =
Für den Mailversand empfehlen wir die Unix Anwendung s-nail. Installation unter Ubuntu mit
apt-get install -y s-nail
Unter RedHat
yum install s-nail
== Einrichtung .mailrc ==
Das s-nail in Ubuntu 22.04 (Version 14.9.23) bietet die Möglichkeit, in der Shell mails für verschiedene Accounts zu verschicken. Zur Konfiguration wird die Datei $HOME/.mailrc genutzt.

alt:
set smtp="smtp://smtp.variomedia.de:587"
set from="mail@memtext.de"
set smtp-auth=login
set smtp-auth-user="noreply@superx-projekt.de"
set smtp-auth-password=securepw1234

neu:
<source lang="sh">
set v15-compat
account test {
set from="Memtext <mail@memtext.de>"
set mta=smtp://noreply%40superx-projekt.de:securepw1234@smtp.variomedia.de:587
set smtp-use-starttls
}
</source>

{{Achtung|Sollte nur für den Benutzer lesbar sein. Es ist nicht sicher, das Passwort direkt in der Konfigurationsdatei zu speichern. Eine sicherere Variante wäre, pass oder gnome-keyring zu nutzen.}}

== Mail verschicken über die bash ==
Zum Verschicken einer Testmail schreiben Sie z.B.
<source lang="bash">
echo "test" | s-nail --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de
</source>
Das CLI von s-nail verhält sich etwas UNIX-untypisch: Beachten Sie dass mehrere Mailadressat_innen mit Leerzeichen getrennt hinten angefügt werden - ohne Anführungszeichen um alle Mailadressen.

Mit dem zusätzlichen Parameter -v können detaillierte Debug-Informationen ausgegeben werden:
<source lang="bash">
echo "test" | s-nail -v --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de
</source>
Damit lässt sich dann prüfen, ob der Versand verschlüsselt (mit set smtp-use-starttls) oder unverschlüsselt stattgefunden hat.
Unverschlüsselt sähe dann z.B. so aus:
<source lang="bash">
echo "Testmail" | s-nail -v --account=test-ohne-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.
</source>

Und verschlüsselt so:
<source lang="bash">
echo "Testmail" | s-nail -v --account=test-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.
s-nail: Certificate depth 2
s-nail: subject = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: notBefore = Feb 1 00:00:00 2010 GMT
s-nail: notAfter = Jan 18 23:59:59 2038 GMT
s-nail: issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: Certificate depth 1
s-nail: subject = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail: notBefore = Nov 2 00:00:00 2018 GMT
s-nail: notAfter = Dec 31 23:59:59 2030 GMT
s-nail: issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail: Certificate depth 0
s-nail: subject = /C=DE/ST=Brandenburg/O=Memtext AG/CN=*.superx-projekt.de
s-nail: notBefore = Feb 8 00:00:00 2024 GMT
s-nail: notAfter = Mar 10 23:59:59 2025 GMT
s-nail: issuer = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail: Comparing subject_alt_name: need<smtp.superx-projekt.de> is<*.superx-projekt.de>
s-nail: TLS certificate ok
s-nail: TLS BLAKE2s256 fingerprint: 7A:0A:D3...
s-nail: TLS connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
</source>

== SQL_ENV mit s-nail ==
In der [[Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|SQL_ENV]] für die neue Konfig-Syntax am besten die Variable MAILPROG mit z.B.
MAILPROG="s-nail --account=test"
angeben.
=Shellscripte in der HISinOne-BI=
Die Shellscripte von superX sind auch in der HISinOne-BI nutzbar, sofern Linux als Betriebssystem genutzt wird. Vorbedingung ist
* die Einrichtung der [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|SQL_ENV]]
* Machen Sie alle Shellscripte im Ordner .../webapps/superx/WEB-INF/conf/edustore/db/bin ausführbar
chmod +x .../webapps/superx/WEB-INF/conf/edustore/db/bin/*
* Nützlich ist auch die Installation von psql, also mindestens das Paket postgresql-client
Im folgenden Beispiel wird ein HISinOne-BI-spezifisches Modul eingerichtet.

==Shellscripte zur Verwaltung von RES==
Das Forschungsmodul RES der HIS e.G. ist ein Beispiel für ein Nicht-SuperX-Modul, das aber auch mit Shellscripten verwaltet werden kann. Hier das Vorgehen:
*Entpacken Sie die ZIP-Datei H1-CS-CM-RM_<<Version>>.zip in einem Ordner Ihrer Wahl.
*Setzen Sie in der [[Kernmodul_Shellscripte#Nutzung_der_SQL_ENV_unter_HISinOne-BI|SQL_ENV]] die Pfade und Variablen:
RES_PFAD=.../webapps/superx/WEB-INF/conf/edustore/db/module/res; export RES_PFAD
RES_ERRORDAT=$RES_PFAD/res_load.err; export RES_ERRORDAT
RES_LOAD_PFAD=$RES_PFAD/rohdaten; export RES_LOAD_PFAD
RES_ERRORMAIL=$ERRORMAIL; export RES_ERRORMAIL
RES_LOGMAIL=$LOGMAIL; export RES_LOGMAIL
* Machen Sie die Shellscripte in $RES_PFAD und $RES_LOAD_PFAD ausführbar:
chmod +x $RES_PFAD/*.x
chmod +x $RES_PFAD/rohdaten/*.x
chmod +x $RES_PFAD/upgrade/*.x

Danach können Sie das Modul installieren mit
cd $RES_PFAD
module_install.x res .

Dann entladen Sie aus H1, indem Sie in $RES_LOAD_PFAD die Datei RES_ENV analog einrichten wie Sie z.B. die ZUL_ENV oder SOS_ENV eingerichtet haben

cd $RES_LOAD_PFAD
res_unload.x

Dann starten Sie den Update:

cd $RES_PFAD
module_etl.x res .

Es kann Probleme geben, wenn das Kernmodul nicht zu der ZIP Datei von HIS paßt. Fehler bzgl. "dim_bp_apnr"... können Sie ignorieren.

Eine Datenbank-Dokumentation befindet sich hier:
.../webapps/superx/WEB-INF/conf/edustore/db/module/res/conf/res.html

Kernmodul Regelbetrieb

2026-08-04T07:55:26Z

Andrek:

=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=

Das bereitgestellte Migrationsskript ermöglicht die Umstellung einer bestehenden SuperX-Installation auf die empfohlene Webapp-Struktur.

Dabei können sowohl klassische Installationen mit separatem DB-Verzeichnis als auch bestehende Webapp-Installationen migriert werden. Die Migration kann je nach Anwendungsfall vollständig oder ausschließlich für das DB-Verzeichnis durchgeführt werden.
Hier eine Anleitung "in short", wenn Sie bisher das "klasssische" Layout genutzt haben (also Unix Benutzer "superx", Installation in "/home/superx").

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git
#Script ausführen und neues ENV laden:
cd BI_Maintenance/webapps_migration
./migrate_superx_webapp.sh

Das Skript liest die bestehende Installation anhand der vorhandenen SQL_ENV-Datei ein und erzeugt daraus die gewünschte Zielstruktur. Details können in der Konfigurationsdatei
<source lang="text">
migrate_superx.conf
</source>
konfiguriert, siehe folgende Dokumentation.

==Zielstruktur==

Die Webapp wird standardmäßig nicht direkt im Tomcat-Webapp-Verzeichnis abgelegt, sondern unter:

<source lang="text">
/home/superx/webapps/superx
</source>

Dadurch bleibt die Installation unabhängig von der verwendeten Tomcat-Distribution und kann einfacher per Git, rsync oder Modulupdate gepflegt werden.

Die zugehörige DB-Struktur befindet sich anschließend unter:

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

==Tomcat-Anbindung==

Für den Zugriff des Tomcat-Servers auf die Webapp gibt es grundsätzlich zwei Möglichkeiten:

* Verwendung eines symbolischen Links vom Tomcat-Webapp-Verzeichnis auf die eigentliche Webapp.
* Anpassung der Tomcat-Konfiguration (z. B. appBase oder Context-Konfiguration).

Empfohlen wird die Verwendung eines symbolischen Links.

Beispiel:

<source lang="text">
/srv/tomcat/webapps/superx
-> /home/superx/webapps/superx
</source>

==Wichtige Variablen==

Die wichtigsten Einstellungen erfolgen in der Datei:

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

===TARGET_WEBAPP===

Definiert das Zielverzeichnis der Webapp.

Beispiel:

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"
</source>

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Ergebnis:

<source lang="text">
Owner: superx
Group: tomcat
</source>

===MIGRATION_MODE===

Steuert die Art der Migration.

Vollständige Migration:

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

Nur Migration des DB-Verzeichnisses:

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

==Migration des DB-Verzeichnisses==

Das DB-Verzeichnis kann entweder kopiert oder verschoben werden.

===DB_TRANSFER_MODE=copy===

Das bestehende DB-Verzeichnis bleibt erhalten.

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

Intern wird hierfür rsync verwendet.

===DB_TRANSFER_MODE=move===

Das DB-Verzeichnis wird verschoben.

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

Intern wird hierfür mv verwendet. Ist das Zielverzeichnis bereits vorhanden und
<code>ALLOW_EXISTING_TARGET_DB="true"</code> gesetzt, wird das vorhandene Ziel-DB-Verzeichnis vor dem Verschieben vollständig ersetzt. Damit verbleiben keine alten Dateien im Ziel.

Dies ist der empfohlene Standard für die Migration klassischer SuperX-Installationen und vermeidet unnötigen zusätzlichen Speicherbedarf.

==Automatische Anpassung der SQL_ENV==

Nach der Migration kann die SQL_ENV-Datei automatisch angepasst werden.

Dabei werden insbesondere folgende Variablen aktualisiert:

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

Zusätzlich wird sichergestellt, dass folgende Einstellung vorhanden ist:

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

Vor der Änderung wird automatisch eine Sicherungskopie der SQL_ENV-Datei angelegt.

==Benutzer und Gruppen==

Die folgenden Variablen steuern, welchem Benutzer und welcher Gruppe die Ziel-Webapp nach der Migration zugeordnet wird.

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

Alle Dateien und Verzeichnisse der Ziel-Webapp werden diesem Benutzer zugeordnet, sofern die Rechteverwaltung aktiviert ist.

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Die Gruppe wird für alle Dateien und Verzeichnisse der Ziel-Webapp verwendet.

Durch das gesetzte setgid-Bit auf den Verzeichnissen erben neu angelegte Dateien und Unterverzeichnisse automatisch diese Gruppe.

==Automatische Rechtebehandlung==

Die Migration kann sowohl als root als auch – unter bestimmten Voraussetzungen – direkt als Anwendungsbenutzer ausgeführt werden.

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

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

Das Skript entscheidet abhängig vom aktuellen Benutzer automatisch, ob ein Besitzerwechsel erforderlich ist.

====Ausführung als root====

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe der Ziel-Webapp auf die konfigurierten Werte gesetzt.

<source lang="bash">
chown -R $WEBAPP_USER:$WEBAPP_GROUP ...
</source>

Zusätzlich wird auch das übergeordnete Verzeichnis der Webapp (z. B. /home/superx/webapps) auf die gleichen Besitz- und Gruppenrechte gesetzt.

====Ausführung als WEBAPP_USER====

Wird das Skript direkt als der konfigurierte WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der konfigurierten WEBAPP_GROUP, wird kein chown ausgeführt.

Stattdessen verwendet das Skript bei Bedarf ein chgrp, um die Gruppenzugehörigkeit der Dateien anzupassen.

In diesem Fall kann die Migration häufig vollständig ohne root-Rechte durchgeführt werden.

====Ausführung als anderer Benutzer====

Wird das Skript weder als root noch als WEBAPP_USER mit passender Gruppenmitgliedschaft ausgeführt, bricht das Skript mit einer entsprechenden Fehlermeldung ab.

===ADD_WEBAPP_USER_TO_GROUP===

Optional kann das Skript die Gruppenmitgliedschaft des Zielbenutzers automatisch anpassen.

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

Hierfür sind root-Rechte erforderlich.

==Tomcat-Symlink==

Optional kann das Skript den Symlink für den Tomcat automatisch erzeugen.

===CREATE_TOMCAT_SYMLINK===

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

===TOMCAT_WEBAPPS_DIR===

<source lang="bash">
TOMCAT_WEBAPPS_DIR="/srv/tomcat/webapps"
</source>

===TOMCAT_CONTEXT_NAME===

<source lang="bash">
TOMCAT_CONTEXT_NAME="superx"
</source>

===REPLACE_EXISTING_SYMLINK===

Bestehende Symlinks können bei Bedarf automatisch ersetzt werden.

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

Normale Dateien oder Verzeichnisse werden dabei niemals automatisch gelöscht.

==Sicherheitsprüfungen==

Vor Beginn der Migration werden verschiedene Sicherheitsprüfungen durchgeführt.

Unter anderem wird geprüft:

* Existiert die SQL_ENV-Datei?
* Existiert der konfigurierte Benutzer?
* Existiert die konfigurierte Gruppe?
* Sind Quell- und Zielverzeichnis identisch?
* Würde eine Verzeichnisverschachtelung entstehen?
* Befindet sich SUPERX_DIR bereits innerhalb von WEBAPP?

Wird erkannt, dass die Installation bereits der neuen Struktur entspricht, bricht das Skript standardmäßig ab.

===FORCE_ALREADY_MIGRATED===

In Ausnahmefällen kann diese Prüfung übersteuert werden.

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

Dies sollte nur verwendet werden, wenn die Auswirkungen bekannt sind.

==Typischer Ablauf==

# Laden der migrate_superx.conf
# Laden der bestehenden SQL_ENV
# Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
# Sicherheitsprüfungen
# Optionales Stoppen des Tomcat-Dienstes
# Kopieren der Webapp
# Kopieren oder Verschieben des DB-Verzeichnisses
# Anpassen der SQL_ENV
# Setzen von Besitzern, Gruppen und Rechten
# Optionales Erzeugen des Tomcat-Symlinks
# Optionales Starten des Tomcat-Dienstes

==Empfohlene Standardkonfiguration==

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"

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

CREATE_TOMCAT_SYMLINK="true"
</source>

==Hinweise==

* Standardziel ist /home/superx/webapps/superx.
* Die Tomcat-Anbindung kann über einen Symlink erfolgen.
* Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen, sofern der Benutzer Mitglied der Gruppe tomcat ist.
* Root wird nur benötigt, wenn Besitzer geändert, Benutzer oder Gruppen angepasst oder Systemkonfigurationen verändert werden müssen.

Kernmodul Komponentenverwaltung

2026-07-14T12:29:28Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden Installation, Deinstallation, Aktualisierung und Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX Komponentenverwaltung beschrieben.

Die SuperX Komponentenverwaltung ist vor allem für die Ausführung und Überwachung von ETL-Prozessen, für Modul-Upgrades sowie für die Installation von im Dateisystem vorhandenen Modulen vorgesehen. Die Deinstallation von Modulen erfolgt weiterhin über die Shell-Skripte.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung der SuperX Komponentenverwaltung beschrieben. Anschließend folgt die Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX Komponentenverwaltung =
Die SuperX Komponentenverwaltung dient dazu, ETL-Prozesse der SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Sie bietet eine zentrale Übersicht über installierte und installierbare Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht der SuperX Komponentenverwaltung mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten sowie die im Dateisystem erkannten installierbaren Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist. Nicht installierte, aber im Dateisystem verfügbare Module können ebenfalls erscheinen.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul. Bei nicht installierten Modulen wird anstelle von „Upgrade“ die Aktion „Installieren“ angeboten.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

Die Oberfläche ermittelt die ausführbaren Aktionen aus den verfügbaren technischen Jobs des jeweiligen Moduls. Falls die Jobliste nicht vollständig geliefert wird, können die grundsätzlichen Angaben aus der Komponentenliste als Fallback genutzt werden. Dadurch können Standardaktionen wie „Unload“, „Update“ oder „Unload & Update“ trotzdem angeboten werden, wenn sie für das Modul grundsätzlich vorgesehen sind.

Vor dem Start einer Aktion erscheint ein Bestätigungsdialog. Dort werden die geplante Aktion, der Modulname und das technische Kürzel angezeigt. Technische REST-Aufrufe werden im normalen Dialog nicht angezeigt.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update sowie Installieren bzw. Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Installieren ===

Die Aktion „Installieren“ wird angezeigt, wenn ein Modul im Dateisystem vorhanden, aber noch nicht installiert ist.

Die Installation legt die benötigten Datenbankobjekte, Abfragen und weiteren Modulbestandteile an. Nach erfolgreicher Installation erscheint das Modul als installiert. An derselben Stelle wird dann statt „Installieren“ die Aktion „Upgrade“ angezeigt.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Je nach Einrichtung können beim Kennzahlen-Modul auch „Unload“ oder „Unload & Update“ angeboten werden. Die Oberfläche richtet sich dabei nach den verfügbaren Jobs bzw. nach den Modulangaben aus der Komponentenliste.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul installieren ===

Wenn ein Modul im Dateisystem vorhanden, aber noch nicht installiert ist, wird in der Modulzeile die Aktion „Installieren“ angezeigt.

Geeignete Aktion:

<pre>
Installieren
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung der SuperX Komponentenverwaltung sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Vor dem Start von Installieren, Upgrade, Unload, Update oder Unload & Update sollte der Bestätigungsdialog geprüft werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* hergeleitete Startaktionen
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der SuperX Komponentenverwaltung. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe der SuperX Komponentenverwaltung verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Die SuperX Komponentenverwaltung stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“ und „Unload & Update“ im Vordergrund. Zusätzlich können Module installiert oder per Upgrade auf den ausgelieferten Stand gebracht werden.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Kernmodul Komponentenverwaltung

2026-07-13T06:51:43Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden die Installation, Deinstallation, Aktualisierung und das Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX ETL Manager beschrieben.

Der SuperX ETL Manager ist vor allem für die Ausführung und Überwachung von ETL-Prozessen sowie für Modul-Upgrades vorgesehen. Die Installation und Deinstallation von Modulen stehen dort bisher nicht zur Verfügung und werden weiterhin über die Shell-Skripte durchgeführt.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung des SuperX ETL Managers beschrieben. Anschließend folgt die Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX ETL Manager =
Der SuperX ETL Manager dient dazu, ETL-Prozesse der installierten SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Er bietet eine zentrale Übersicht über installierte Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht des SuperX ETL Managers mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten bzw. erkannten Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update und Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung des ETL Managers sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der ETL-Manager-Installation. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe des ETL Managers verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Der SuperX ETL Manager stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“, „Unload & Update“ und „Upgrade“ im Vordergrund.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Kernmodul Komponentenverwaltung

2026-07-13T06:45:00Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden die Installation, Deinstallation, Aktualisierung und das Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX ETL Manager beschrieben.

Der SuperX ETL Manager ist vor allem für die Ausführung und Überwachung von ETL-Prozessen sowie für Modul-Upgrades vorgesehen. Die Installation und Deinstallation von Modulen stehen dort bisher nicht zur Verfügung und werden weiterhin über die Shell-Skripte durchgeführt.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung des SuperX ETL Managers beschrieben. Anschließend folgt die bisherige Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX ETL Manager =
Der SuperX ETL Manager dient dazu, ETL-Prozesse der installierten SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Er bietet eine zentrale Übersicht über installierte Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht des SuperX ETL Managers mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten bzw. erkannten Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update und Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung des ETL Managers sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der ETL-Manager-Installation. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe des ETL Managers verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Der SuperX ETL Manager stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“, „Unload & Update“ und „Upgrade“ im Vordergrund.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Datei:SuperX ETL Manager Aktueller Lauf.png

2026-07-13T06:42:38Z

Andrek:

Datei:SuperX ETL Manager Aktionsbuttons.png

2026-07-13T06:42:23Z

Andrek: