Kernmodul Shellscripte

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/<>/conf. Wenn die Datei nicht gefunden wird, bricht das Script ab.

Die folgende Abbildung zeigt die Arbeitsweise:

module_install.x

Installiert ein Modul < in der Datenbank, wobei die Installationsdateien sich im <> befinden.

module_drop.x

Löscht die Komponenten eines Moduls < in der Datenbank, wobei die Installationsdateien sich im <> befinden.

Entladen

Das Entladescript lautet $SUPERX_DIR/db/module/</rohdaten/<_unload.x. Die Entladeparameter werden in folgender Datei festgelegt:

$SUPERX_DIR/db/module/</rohdaten/<>_ENV

Entladeroutine bei mandantenfähigen Installationen:

$SUPERX_DIR/db/module/</rohdaten</<>_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 < in der Datenbank, wobei die Installationsdateien sich im <> befinden.

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.

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 das Update-Script für Bau unter Informix:

bau_update.x

#!/bin/sh
.  /home/superx/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

Wie Sie sehen ist es möglich, für jedes Modul unterschiedliche Mailadressen zuzuweisen. Die Mailadressen werden systemweit in der 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 <_<_<>.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/</L_<_<>.log

Laderoutinen

Für alle Module sind die Dateien wie folgt benannt:

Entladeroutine:

$SUPERX_DIR/db/module/</rohdaten/<>_unload.err

Entladeroutine bei mandantenfähigen Installationen:

$SUPERX_DIR/db/module/</rohdaten</<>_unload.err

Laderoutine:

$SUPERX_DIR/db/module/</L_<_<>.log

wobei <> wie folgt aufgebaut ist:

1. Unload (Entladen aus Vorsystem)
2. Load (CSV-Upload)
3. Transformation (Schlüsselharmonisierung, Prüfroutinen)
4. Aggregation (Aufbau der Hilfstabellen)
5. 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 DOSQL die *.tmp.sql-Dateien nicht gelöscht. Sie können den Parameter in der aktuellen Shell setzen, oder permanent in der 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 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.

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 Installationshandbuch.

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  

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

Eine Maske sichern und entladen

Um eine Maske zu sichern, müssen Sie die entsprechenden Einträge in den Tabellen

1. felderinfo,
2. masken_felder_bez,
3. maskeninfo,
4. sachgeb_maske_bez,
5. maske_system_bez

selektieren und sichern. Für dies gibt es das Script sx_select_mask.

sx_select_mask

Eine Maske neu einfügen

Um eine Maske neu einzufügen, müssen Sie die entsprechenden Einträge in den Tabellen

1. felderinfo,
2. masken_felder_bez,
3. maskeninfo,
4. sachgeb_maske_bez,
5. maske_system_bez

einfügen. Dafür gibt es das Script sx_insert_mask.

sx_insert_mask

Falls

Falls

select max(tid) from maskeninfo;

Wie im Abschnitt 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

Änderungen an einer Maske vornehmen

1. Selektieren der Metadaten der betreffenden Maske: sx_select_mask

2. Editieren der fünf Metadaten-Dateien ,,_..."

3. Abspeichern der neuen Metadaten: sx_insert_mask

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 Download-Bereich zu verlinken.

Seit dem Kernmodul 4.2.1 bzw. HISinOne-BI 5.1 ist diese Funktionalität vorhanden, wenn die Kommandozeile eingerichtet ist:

• Unter SuperX: 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 klappt, muss man in die Umgebungsvariable JDBC_CLASSPATH noch die Tomcat Library servlet-api.jar aufnehmen, diese liegt in ..webapps/superx/lib_ext. Der Aufruf muss bis Kernmodul 5.0 oder HISinOne-BI 2022.12 in dem Verzeichnis $WEBAPP/WEB-INF ausgeführt werden.

Der Kommandozeilenaufruf sieht unter Linux wie folgt aus:

java  -cp  "$JDBC_CLASSPATH"  $JAVA_OPTS  de.superx.bin.ExecuteMask  -tid:Maskennummer  -out:usgabedatei  -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:

Und hier die Parameter:

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

Sie können es mit einer Maskenausführung kombinieren, oder zum Entwickeln. Bei der Maskenausführung können Sie aber im Script 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:

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

Mail verschicken über die bash

Zum Verschicken einer Testmail schreiben Sie z.B.

echo  "test"  |  s-nail  --account=test  -s  "test"  support@superx-projekt.de  support1@superx-projekt.de  support2@superx-projekt.de

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.

SQL_ENV mit s-nail

In der SQL_ENV für die neue Konfig-Syntax am besten die Variable MAILPROG mit z.B.

MAILPROG="s-nail  --account=test"

angeben.