SuperX - Benutzerbeiträge [de]

Kernmodul Regelbetrieb

2026-08-01T09:55:39Z

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

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

Dies kann insbesondere bei großen Installationen sinnvoll sein, um unnötigen zusätzlichen Speicherbedarf zu vermeiden.

==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="full"
DB_TRANSFER_MODE="copy"

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.

Masken-Tutorial

2026-06-27T08:10:43Z

Danielq:

=Orientierung=

<blockquote>
Die Abfragemasken liefern die Daten aus den Basissystemen an das SuperX-Frontend aus. Einige Abfragen zur Administration sind im Kernmodul enthalten, die Abfragen zu den Basissystemen sind in den jeweiligen Modulen enthalten. Die Abfragen in der Administration erlauben es, neue Masken anzulegen, zu kopieren und zu löschen.
</blockquote>
<blockquote>
Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis 1xxxx0000 bis 1xxxx9970 liegen, wobei xxxx der von DESTATIS verwandten Hochschulnummer entspricht (bei dreistelligen Nummern mit führender 0), also z.B. 1'''1810'''0000 für die erste Maske der Uni Mannheim. Es sind Dreißigerschritte zu wählen, da die dazwischen liegenden Nummern für die Maskenfelder (Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo']) reserviert sind.
</blockquote>

<blockquote>
Im Folgenden finden Sie allgemeine Hinweise für die Verwaltung der Masken. Die Masken lassen sich browserbasiert, über UNIX-Shellscripte, und über Access administrieren. Weitergehende Möglichkeiten bietet aber das XML-Frontend (Möglichkeit der Editierung von großen text -Feldern bei Postgres als Datenbanksystem). Nach der Anmeldung haben Administratoren das Recht, Masken zu löschen, zu kopieren und erzeugen. Die einzelnen Felder der Masken lassen sich direkt in der Datenbank oder z.B. mit MS Access verändern. Im Applet sind nur grundlegende Verwaltungsoperationen möglich. Sie sind als Ersatz für die UNIX- Scripte gedacht.
</blockquote>

<blockquote>
Maske kopieren: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskeneueinfgen.htm#sxinsertmask UNIX - Script] wir eine Maske in eine neue Maske kopiert, und alle zugehörigen Tabellen werden aktualisiert. Zusätzlich wird auch der Eintrag im Themenbaum gemacht. Bei der Nummer der Maske (tid) sollten Sie das Nummernschema von SuperX einhalten, um in Zukunft Abfragen-Pooling zu ermöglichen.Maske löschen: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskelschen.htm#sxDeleteMask UNIX-Script] werden Masken aus allen dazugehörigen Tabellen entfernt. Zusätzlich wird auch der Eintrag im Themenbaum gelöscht. Zur Sicherheit muss die Nummer der Maske manuell eingegeben werden.Maske suchen: Sie können Masken suchen und im XML-Frontend komfortabel editieren. Schränken Sie Ihre Auswahl auf ein Sachgebiet ein, und drücken Sie "Abschicken". Sie erhalten eine Liste mit "Treffern", und rechts befinden sich jeweils Buttons zum ansehen bzw. editieren einer Maske.
Die Maske läuft nur unter Postgres, weil Informix kein direktes Bearbeiten von Blob-Feldern mit sql unterstützt.Analog können Felder kopiert, gelöscht oder gesucht werden.
</blockquote>

<blockquote>

Die Abfragen sind selbsterklärend; das Erzeugen neuer Masken, Löschen vorhandener Masken und Kopieren vorhandener Masken ist nur für Userkennungen möglich, die in der Tabelle userinfo im Feld administration den Wert 1 haben. Natürlich sollten die Abfragen sehr vorsichtig benutzt werden, sie sind die einzigen Abfragen in SuperX, die tatsächlich Änderungen an der Datenbank vornehmen können.

</blockquote>

=Grundlagen=

In den folgenden Abschnitten werden die Grundlagen der Maskenentwicklung erläutert. Beginnend beim Abruf einer Ergebnistabelle aus einer Maske, über die Definition der Felder dieser Maske, bis hin zur Definition der dahinterliegenden SQL-Anweisungen.

==Abrufen einer Ergebnistabelle==
Der Ausgangspunkt ist ein Beispiel aus dem SOS-Modul. Auf der folgenden Abbildung ist der Themenbaum ersichtlich, welcher sich in verschiedene Bereiche gliedert.

<blockquote>
{{ImagePara |imgsrc=Themenbaum.PNG|width=600|caption=Themenbaum}}

Wählt man aus der Navigation auf der linken Seite einen Bereich aus, werden Abfragen sichtbar. In diesem Fall ist der Bereich "Bewerbung, Zulassung" ausgewählt und es wird unter anderem die Abfrage "Bewerbungsprozess nach Fach/Studiengang" sichtbar.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Maske.PNG|width=600|caption=Maske}}

Wählt man eine Abfrage aus, erscheint eine Maske, welche verschiedene Möglichkeiten zur Parametrisierung bietet.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Ergebnistabelle.PNG|width=600|caption=Ergebnistabelle}}

Nach einem Klick auf "Abschicken" erscheint die entsprechende Ergebnistabelle.
</blockquote>

==Die Felddefinitionen==
Gehen wir kurz zurück zur Auswahlmaske. Jedes Feld der Maske, z.B. "Semester", ist ein Datensatz in der Tabelle 'felderinfo' . Dort finden Sie Angaben zum Namen, Inhalt und Layout des Feldes. Gehen wir zunächst zum Inhalt des Feldes: Die Liste der Semester.

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemester.png|width=400|caption=MaskenfeldSemester}}

Beim Klick auf das Feld Semester erhalten wir eine Reihe von Semestern zur Auswahl. Die Liste ist absteigend sortiert. Sie wird durch die SQL Anweisung [<<SQL>> select tid, eintrag from zul_semester order by tid DESC;] erzeugt. Die SQL-Anweisung liefert aus der Tabelle 'zul_semester' die Felder 'tid' ("Tupelidentifier") und 'eintrag' (der Volltext des Semesters). Der Schlüssel des Feldes 'tid' ist unsichtbar, sorgt aber dafür, dass die Sortierung richtig erfolgt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=DatenbanktabelleZulSemester.png|width=400|caption=DatenbanktabelleZulSemester}}

Hier sehen Sie einen Screenshot der Tabelle 'zul_semester' direkt in der Datenbank. Die Nummerierung ist fünfstellig und besteht aus Jahr (vier Stellen) und 1 für Sommer- und 2 für Wintersemester.
</blockquote>

==Speichern der Felddefinition==
Wo wird nun in SuperX die Felddefinition gespeichert? Viele Scripte in SuperX werden selbst in Datenbanktabellen abgelegt, die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo felderinfo] enthält die relevanten Angaben für die Felder. Um dies zu sehen, öffnen wir ein Formular im XML-Frontend. Dort befinden sich Bearbeitungsformulare für Felder und Masken.

<blockquote>
{{ImagePara |imgsrc=FeldSuchen.png|width=600|caption=FeldSuchen}}

Im Themenbaum des XML-Frontends finden wir den Menüpunkt '''Administration → Felder → Feld suchen'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenMaske.png|width=600|caption=FeldSuchenMaske}}

In dem Formular wählen wir die Abfrage "Bewerbungsprozess nach Fach/Studiengang" aus. Zusätzlich sehen wir auch die Nummer der Maske (26020), was bei der Maskenbearbeitung ganz nützlich ist. Mit einem Klick auf "Abschicken" werden die Eingaben bestätigt und abgeschickt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenErgebnis.png|width=600|caption=FeldSuchenErgebnis}}

Es wird eine Liste mit den vorhandenen Feldern geliefert. Wir sehen die Nummer des Feldes und den Namen. Rechts daneben befindet sich ein Knopf zum Bearbeiten des Feldes.
</blockquote>

Ein kleiner Hinweis an dieser Stelle: Die Felder werden in der Tabelle masken_felder_bez der Maske Nr. 26020 zugeordnet. Wir zählen also bei Feldnummern in Einer-Schritten von der Maskennummer aus hoch. Aus diesem Grunde wählen wir bei Maskennummern größere Intervalle.

<blockquote>
{{ImagePara |imgsrc=BearbeitungsformularFeld.png|width=600|caption=BearbeitungsformularFeld}}

Wir wählen nun das Feld "Semester" und gelangen in ein Bearbeitungsformular der Tabelle 'felderinfo' . Wir sehen Name, Nummer, Position auf der Maske, Breite und Typ des Feldes (ganzzahlig). Das Feld ist obligatorisch und von der Art Nr. 1 (Nummer + Text, mit Dialog). Im Feld 'relation' steht nach dem Steuerungszeichen <<SQL>> der SQL-Befehl. Unten ist noch der Defaultwert für das Feld angegeben, ebenfalls ein SQL-Ausdruck.
</blockquote>

SuperX liest also aus der Datenbank die Scripte für eine Maske bzw. für ein Feld aus einer Tabelle, und führt Sie dann in der Datenbank aus.

==Änderung einer Felddefinition==

<blockquote>
{{ImagePara |imgsrc=FeldBearbeiten.png|width=600|caption=FeldBearbeiten}}

Um die Felddefinition zu ändern, kann nun beispielsweise beim SQL-Befehl DESC durch ASC ersetzt und gespeichert werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemesterASC.png|width=400|caption=MaskenfeldSemesterASC}}

Um das neue Script aus der Datenbank zu laden, muss die Maske nun erneut über den Themebaum aufgerufen werden. Wenn wir dann in der Maske auf "Semester" klicken, erscheinen die Semester in aufsteigender Reihenfolge.
</blockquote>

Auf diese Art und Weise können wir alle Maskenfelder bearbeiten. Die restlichen Attribute in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] sind im [https://super-ics.de/superx/doku/kern_modul/admin/f_TabelleFelderinfo.htm Administrationshandbuch Kernmodul] erläutert.

==Maskendefinition==

So weit so gut, wir können nun also Felder ändern. Wie können wir nun die Ergebnistabellen bearbeiten? 
SuperX arbeitet hier ebenfalls mit SQL-Scripten, die als Felder in einer Tabelle gespeichert sind. Die Tabelle lautet [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_maskeninfo 'maskeninfo']. Wir können uns diese Tabelle ebenfalls im XML-Frontend anschauen:

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenMaske.png|width=600|caption=MaskeSuchenMaske}}

Im Themenbaum wählen wir "Administation → Masken verwalten → Maske suchen". Es erscheint eine Auswahlmaske ohne Vorbelegung. Es lässt sich nun eine Maske anhand einer Auswahlliste oder Maskennummer suchen. Um das Feld für die Suche mit Maskennummer einzublenden, muss das Schlüsselsymbol geklickt werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenErgebnis.png|width=600|caption=MaskeSuchenErgebnis}}

Als Ergebnis sehen wir unsere Maske sowie mehrere Bearbeitungsbuttons. Wir wählen den ersten Button, '''Bearbeiten'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeninfoVerwalten.png|width=600|caption=MaskeninfoVerwalten}}

Wir gelangen in das Bearbeitungsformular der Maske. Neben der Nummer der Maske sehen wir unter anderem den Namen und die Felder 'Select-Statement' und 'Spaltenlayout'. Das Feld 'Select-Statement' enthält das SQL-Script und 'Spaltenlayout' die Ergebnisdarstellung.
</blockquote>

==Abfragen in Maskendefinitionen==

Allgemein formuliert arbeiten wir so:
# Zunächst werden die Eingaben in den Auswahlfeldern ausgewertet und eine Ergebnismenge ermittelt, meist in Form einer temporären Tabelle.
# Diese Tabelle wird mit den Hilfstabellen in der Datenbank gejoined, und es wir eine Ergebnistabelle berechnet. Ggf. werden noch Summen oder Prozente berechnet, meist benötigen wir dazu weitere temporäre Tabellen.
# Der letzte select im Feld 'Select-Statement' enthält die Ergebnistabelle, die das Applet empfängt. Im Feld 'Spaltenlayout' werden die Spaltenüberschriften- und Breiten gesetzt und das Ergebnis wird angezeigt.
# Direkt danach wird die letzte temporäre Tabelle gedroppt, und die Datenbankverbindung wird an das SuperX-Servlet zurückgegeben.

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenPruefungsstatistik.png|width=600|caption=MaskeSuchenPruefungsstatistik}}

Im Folgenden wird als Beispiel der Bericht "Studierende, Prüfungen → Einzelprüfungen → Prüfungsstatistik" herangezogen. Das Script in 'Select-Statement' ist relativ lang, wir wollen es daher nur Auszugsweise kommentieren.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement1.png|width=600|caption=SelectStatement1}}

Zu Beginn des Select-Statements wird über <code>select ... into temp tmp_ergebnis</code> die Ergebnismenge der temporären Tabelle 'tmp_ergebnis' übergeben. Einige Felder unterliegen bestimmten Kriterien, wie bspw. das Feld 'bestanden': <code>(case when P.pstatus='BE' then 1 else 0 end) as bestanden</code>
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement2.png|width=600|caption=SelectStatement2}}

In der folgenden where-Klausel werden verschiedene Bedingungen festgelegt. Hier finden sich Platzhalter wie <code><<Seit Semester>></code>. Diese Platzhalter entsprechen den Maskenfeldern und werden mit den Benutzereingaben gefüllt. Passagen innerhalb <code>/* ... */</code> werden nur dann ausgeführt, wenn das entsprechende Maskenfeld gefüllt wurde. Da es sich bei <code><<Seit Semester>></code> um ein Pflichtfeld handelt, ist diese Einschränkung dort nicht nötig.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement3.png|width=600|caption=SelectStatement3}}

Um diverse Berechnungen anzustellen werden, wird die Ergebnismenge in eine zweite temporäre Tabelle überführt: <code>select ... into temp tmp_ergebnis2</code>. Die erste temporäre Ergebnistabelle wird gelöscht: <code>drop table tmp_ergebnis;</code>.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement4.png|width=600|caption=SelectStatement4}}

Der letzte Select greift auf die zweite temporäre Tabelle zu und enthält die Ergebnistabelle.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Spaltenlayout.png|width=600|caption=Spaltenlayout}}

Im Feld 'Spaltenlayout' wird das Layout der Spalten der Ergebnistabelle festgelegt. Der markierte Bereich definiert das Layout der ersten Spalte. Spaltenüberschriften sind von 0 aufsteigend durchnummeriert, und die Überschriften selbst können durch "\n" mit Zeilenumbrüchen versehen werden. Pro Überschrift wird ein Absatz formuliert, u.a. auch die Breite der Spalte. Dabei ist zu beachten, dass die Darstellung in HTML vom verwandten Browser abhängt. 'Width' beispielsweise hat auf die HTML-Darstellung keinen Einfluss.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=CleanupStatements.png|width=600|caption=CleanupStatements}}

Wichtig ist außerdem, dass die zweite temporäre Tabelle gelöscht wird. Dies geschieht durch ein kurzes SQL-Statement in 'Cleanup Statements'.
</blockquote>

==Masken erstellen aus Kopien==

Zur Maskenerstellung werden Kopien bereits existierender Masken erstellt. Es ist ratsam Masken zu kopieren, welche der neu zu erstellenden Masken thematisch ähneln. Das bringt den Vorteil, dass diverse Felder der Kopie weiterverwendet werden können. Unter {{Pfad3|Administration|Masken verwalten|Maske kopieren}} findet sich die entsprechende Maske.

<blockquote>
Es wird zunächst die zu kopierende Maske gewählt und anschließend eine tid und ein Name, sowie eine Erläuterung für die neue Maske vergeben. Nach Patch 2022-01-28 kann wahlweise die neue Maske direkt als Makro erstellt werden.

{{ImagePara |imgsrc=Maske_kopieren_1.png|width=600|caption=Auswahlmaske Maske kopieren}}

Bei diesem Beispiel würde die Maske "Studierende nach Alter" kopiert und eine neue Masken "Studierende nach Geschlecht" mit der tid 15980 erstellt.
</blockquote>

{{Achtung|Bei der Vergabe der neuen tid unbedingt darauf achten, dass diese nicht bereits belegt ist.}}

Bei der Vergabe der neuen tid wird mindestens in Dreißigerintervallen vorgegangen, damit für die Felder der Masken ausreichend tids verfügbar sind.

<blockquote>
Um die belegten Masken-tid zu ermitteln eignet sich {{Pfad3|Administration|Masken verwalten|Maske suchen}}, da dort beim Feld Maske die Masken nach tids aufsteigend sortiert sind.

{{ImagePara |imgsrc=Masken_tids.png|width=600|caption=Auswahlmaske Maske suchen}}
</blockquote>

Die Feld-tids werden beginnend ab der Masken-tid direkt aufeinanderfolgend vergeben. Ein Dreißigerintervall zwischen den Masken-tids ermöglicht es somit dreißig Felder pro Maske zu vergeben. Trotzdem sollte immer geprüft werden, ob die vorherige Maske gegebenenfalls mehr als dreißig Felder besitzt und entsprechend ein größeres Intervall zu wählen ist. Hierfür eignet sich {{Pfad4|Administration|Masken verwalten|Felder|Feld suchen}}

<blockquote>
{{ImagePara |imgsrc=Feld_suchen_1.png|width=600|caption=Auswahlmaske Felder suchen}}

{{ImagePara |imgsrc=Feld_suchen_2.png|width=400|caption=Ergebnistabelle Felder suchen}}

Die Maske "16340-Studierende nach Alter" besitzt 17 Felder. Ein Dreißigerintervall wäre somit ausreichend.
</blockquote>

==Masken oder Felder löschen==

Masken und Felder werden über {{Pfad4|Administration|Masken verwalten|Felder|Feld löschen}} und {{Pfad3|Administration|Masken verwalten|Maske löschen}} gelöscht. Dies hat den Vorteil, dass anhand der entsprechenden tid die Einträge für diese Maske oder dieses Feld aus sämtlichen Tabellen gelöscht wird. Falls die Einträge für ein Feld oder eine Maske nur in den Tabellen maskeninfo und felderinfo gelöscht würden, wären beispielsweise in der Feldverwaltung leere Felder zu finden. Um den Datenbestand sauber zu halten wird daher empfohlen, die angesprochenen Formulare "Feld löschen" und "Maske löschen" zu nutzen.

==Konventionen==

Für die Erstellung von SQL-Abfragen gibt es ein paar wichtige Konventionen:
* wenn Sie Abfragen schreiben, sollten Sie temporäre Tabellen immer mit "tmp_" vorab benennen. Grund: es könnte mal sein, dass wir die Tabelle auch als statische Tabelle nutzen. Dann gibt es einen SQL-Fehler.
* vermeiden Sie bei temporären Tabellen Umlaute in Spaltennamen (z.B. "Fakultät"). Das klappt zwar unter Informix, aber nicht unter Postgres.
* Nutzen Sie, wenn möglich, die ANSI-SQL-Standards.

=Abfragenentwurf mit SuperX-Sichten=

<blockquote>
In SuperX können bei Auswahldialogen verschiedene Sichten angeboten werden (vgl. [[SuperX-Benutzungshandbuch_Basics#Alternative_Hierarchien_zur_Datenselektion|Alternative Hierarchien zur Datenselektion]]). Alternative Hierarchien bzw. Auswertungshierarchien aus COB werden automatisiert übernommen. Jede Hierarchie bekommt einen Eintrag in der Sichtentabelle.

<div id="SichtenAuswahl">{{ImagePara |imgsrc=SichtenAuswahl.png|width=600|caption=SichtenAuswahl}}</div>

{{Achtung|Die Inhalte und Rechte der Sichten werden gecached. Nach einer Änderung der Inhalte einer Sicht im laufenden Betrieb musst man im SuperXManager den Cache leeren und sich neu anmelden.}}Die Sichten werden in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten 'sichten'] definiert. Eine Übersicht über die Tabellenstruktur inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten hier].
</blockquote>

<blockquote>
Die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten sichten] lässt sich wie auch die Masken und Felder (s. Abschnitt [[Masken-Tutorial#Maskendefinition|Maskendefinition]] und [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) in SuperX über ein Bearbeitungsformular manipulieren.

{{ImagePara |imgsrc=SichtSuchen.png|width=600|caption=SichtSuchen}}

Im Folgenden wird die Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" näher betrachtet.

{{ImagePara |imgsrc=SichtFachAbschluss.png|width=600|caption=SichtFachAbschluss}}

</blockquote>

<blockquote>
Bei <code>sos_org_lehre_fach_absch_ude</code> handelt es sich um eine "View". Diese "View" beinhaltet mehrere Select-Statements, welche quasi die verschiedenen Ebenen der Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" darstellen.

{{ImagePara |imgsrc=ViewFachAbschUDE.png|width=600|caption=ViewFachAbschUDE}}

Das Organigramm stellt eine integrierende Sicht für verschiedene Datenquellen zusammen und ist somit die Voraussetzung für eine integrierte Betrachtung. Alle Einrichtungen, Institutionen und Projekte sind im Organigramm hierarchisch angeordnet (vgl. [https://super-ics.de/superx/doku/kern_modul/admin/f_DasOrganigramm.htm Das Organigramm]). Das Feld 'lehre' wird entweder mit 1 oder 0 gefüllt, um festzustellen ob die Institution relevant für Auswertungen im Bereich Lehre ist (1=ja, 0=nein).

Erläuterung des parent-Felds:Das Parent-Feld gibt die key_apnr der übergeordneten organisatorischen Einheit an. Das root-Element des Baums besitzt als parent einen null-Wert. Das Organigramm darf demenstprechend nur ein Element haben, dass keinen parent besitzt. Hier sollte grundsätzlich die Hochschulnummer eingetragen werden die auch in anderen HIS-Programmen verwendet wird. In Duisburg ist dies z.B. der Basiseintrag key_apnr = "70" ( GMU Duisburg ). Es ist praktisch der oberste "Knoten" im Baum. Dann werden alle Einträge in der Tabelle organigramm gesucht, die parent="70" haben – also direkte Kinder des Basiseintrags.Hier findet sich u.a. Einrichtungen Forschung und Lehre (key_apnr="7", parent="70"). Dieser Eintrag hat wiederum u.a. folgende Kinder:
*Fakultät 1 (key_apnr="1100", parent="7")
*Fakultät 2 (key_apnr="1200", parent="7")
*Faktultät 3 (key_apnr="1300", parent="7")
usw.

Die weiteren Äste des Baums werden rekursiv abgefragt. Die Struktur der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm 'organigramm'] inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm hier]. Die Tabelle [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang 'dim_studiengang'] enthält Datensätze zu Studiengängen (Die Struktur der Tabelle inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang hier]).
</blockquote>

<blockquote>
Für alle Sichten wird erwartet, dass mindestens die drei Felder name, key und parent geliefert werden (der konkrete Name der Spalten ist irrelevant).
Anschließend können optional noch Strukturinformationen folgen (entweder Integer oder String).Beispiel:<code>sp_fin_inst_hier(<<UserID>>,<<Stand>>,<<Sicht>>);select name,key,parent,strukturint from tmp_hier order by name; drop table tmp_hier;</code>strukturint (gefüllt aus fin_inst.orgstruktur) gibt mit Zahlen an, ob ein Eintrag eine Lehreinheit oder ein Fachbereich ist.Auf diese Information kann später in Abfragen mit FreeMarker zugegriffen werden.Beispiel:
{{ImagePara |imgsrc=FreemarkerStrukturInt.png|width=500|caption=FreemarkerStrukturInt}}
</blockquote>

==Einträge verstecken oder nicht-selektierbar machen==

<blockquote>
Es kann gewünscht sein, dass Einträge versteckt hinterlegt werden. Betrachtet sei weiterhin die Sicht [[#SichtenAuswahl|'FB/Fak, Lehreinheit, Fach/Abschluss']]. Die unterste sichtbare Ebene ist Fach/Abschluss. Man könnte also annehmen, es würde genügen, diese Sicht bis zur Ebene Fach/Abschluss aufzubauen. Dem ist allerdings nicht so. Es benötigt eine weitere, darunterliegende, aber nicht sichtbare Ebene "Studiengang".

<div id="ViewFachAbschUDESichtbarUnsichtbar">{{ImagePara |imgsrc=ViewFachAbschUDESichtbarUnsichtbar.png|width=600|caption=ViewFachAbschUDESichtbarUnsichtbar}}</div>
</blockquote>

<blockquote>
Zum Verständnis ein Beispiel anhand der Auswertung "Studierende nach Alter". Zunächst wird eine Kombination "Fach/Abschluss" ausgewählt.

{{ImagePara |imgsrc=AuswahlSichtBWLBA.png|width=400|caption=AuswahlSichtBWLBA}}
</blockquote>

<blockquote>
Es erscheint folgende Ergebnistabelle:

{{ImagePara |imgsrc=ErgebnistabelleStudierendeNachAlter.png|width=600|caption=ErgebnistabelleStudierendeNachAlter}}
</blockquote>

<blockquote>
Im SQL erfolgt die Einschränkung auf den im Sichtenbaum ausgewählten Eintrag durch <code>where ... 's_' || L.tid in <@printkeys Studiengang.allNeededKeysList/> ... </code>. Für unser Beispiel sieht diese Passage nach der Freemarker-Transformation folgendermaßen aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS','s_3','s_36','s_33','s_65','s_270','s_87') ...</code>. Würde die unterste, unsichtbare Ebene 'Studiengang' entfallen (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']]), sähe der SQL stattdessen so aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS') ...</code>. Das hätte zur Folge, dass keine Einträge gefunden würden, denn es wird nach dem Muster 's_tid' gesucht.

Um eine Ebene unsichtbar zu machen benötigt es das Attribut 'nodeattrib'. Wird diesem der Wert 1 übergeben, so ist die Ebene unsichtbar. Mit dem Wert 0 bleibt die Ebene sichtbar (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']], Zeile 21 und 30).

</blockquote>

<blockquote>
Weiterhin kann es gewünscht sein, dass man in einer Sicht nur spezielle Einträge auswählen kann. So können man eine Lehreinheitsauswahl vielleicht so darstellen:

Uni XY
* Fak 1
** Lehreinheit A
** Lehreinheit B
* Fak 2
** Lehreinheit C
** Lehreinheit D

Die Kategorisierung Fak 1/2 dient der Klarheit der Darstellung, für eine Abfrage soll aber vielleicht nur eine konkrete Lehreinheit auswählbar sein. In dem Fall kann wie oben das nodeattrib 2 vergeben werden. Dadurch wird ein Eintrag als nicht-selektierbar markiert.
</blockquote>

==User-/Gruppenrechte==

<blockquote>
Außer Administratoren dürfen normale User zunächst einmal keine der nicht-internen Sichten benutzen.In den Tabellen user_sichten und user_sichtarten kann hinterlegt werden, dass ein User eine einzelne Sicht (z.B. name_intern Kostenstellen-Hauptsicht) oder eine ganze Sichtart (z.B. Kostenarten) benutzen darf.Für Gruppen gibt es analog die Tabellen group_sichten und group_sichtarten.Außerdem sachgeb_sichten und sachgeb_sichtarten, wenn Leute die ganze Sachgebiete sehen dürfen auch Sicht sehen sollen.Die Pflege dieser Tabellen kann bequem über Administrationsformular im XML-Frontend vorgenommen werden.<blockquote> Achtung:Nach Änderungen muss der Server-Cache aktualisiert werden und der User muss sich neu anmelden. Alternativ könnte auch Tomcat neu gestartet werden. </blockquote>Im Dateisystem unter $SUPERX_DIR/db/bin gibt es zwei Skripte userrechte_sichern.x und userrechte_einspielen.x.Die entladen alle usertabellen (userinfo,groupinfo,user_sachgeb_bez etc) und spielen sie wieder ein.Diese können z.B. dafür benutzt werden um alle Einstellungen von Test auf Echtrechner zu übernehmen.
</blockquote>

==Benutzen der Sichten in Masken==

<blockquote>
In [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] (s. [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) muss als Art 12-Sicht eingetragen werden.Im Feld Relation muss ein Select stehen, der die 'tids' der gewünschten Sichten zurückliefert.

{{ImagePara |imgsrc=FeldBearbeitenArtSicht.png|width=600|caption=FeldBearbeitenArtSicht}}

<blockquote>Die aktiv-Einschränkung ist praktisch für Entwicklungs- und Wartungszwecke, weil man dann leicht einzelne Sichten de/aktivieren kann - Sortierung nach type, damit erst Hauptsichten und dann alternative Hierarchien angezeigt werden, dann nach Name.</blockquote>Der select sollte alle Sichtentids liefern, die ein Adminstrator sehen darf.Wenn ein User für einzelne Sichten keine Berechtigung hat, filtert der Server diese automatisch raus.
</blockquote>

Datei:uoh rechte fgb.png

2026-06-25T13:28:16Z

Danielq:

Masken-Tutorial

2026-06-25T07:01:56Z

Danielq: /* Orientierung */

=Orientierung=

<blockquote>
Die Abfragemasken liefern die Daten aus den Basissystemen an das SuperX-Frontend aus. Einige Abfragen zur Administration sind im Kernmodul enthalten, die Abfragen zu den Basissystemen sind in den jeweiligen Modulen enthalten. Die Abfragen in der Administration erlauben es, neue Masken anzulegen, zu kopieren und zu löschen.
</blockquote>
<blockquote>
Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis 1xxxx0000 bis 1xxxx9970 liegen, wobei xxxx der von DESTATIS verwandten Hochschulnummer entspricht (bei dreistelligen Nummern mit führender 0), also z.B. 1'''1810'''0000 für die erste Maske der Uni Mannheim. Es sind Dreißigerschritte zu wählen, da die dazwischen liegenden Nummern für die Maskenfelder (Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo']) reserviert sind.
</blockquote>

<blockquote>
Im Folgenden finden Sie allgemeine Hinweise für die Verwaltung der Masken. Die Masken lassen sich browserbasiert, über UNIX-Shellscripte, und über Access administrieren. Weitergehende Möglichkeiten bietet aber das XML-Frontend (Möglichkeit der Editierung von großen text -Feldern bei Postgres als Datenbanksystem). Nach der Anmeldung haben Administratoren das Recht, Masken zu löschen, zu kopieren und erzeugen. Die einzelnen Felder der Masken lassen sich direkt in der Datenbank oder z.B. mit MS Access verändern. Im Applet sind nur grundlegende Verwaltungsoperationen möglich. Sie sind als Ersatz für die UNIX- Scripte gedacht.
</blockquote>

<blockquote>
Maske kopieren: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskeneueinfgen.htm#sxinsertmask UNIX - Script] wir eine Maske in eine neue Maske kopiert, und alle zugehörigen Tabellen werden aktualisiert. Zusätzlich wird auch der Eintrag im Themenbaum gemacht. Bei der Nummer der Maske (tid) sollten Sie das Nummernschema von SuperX einhalten, um in Zukunft Abfragen-Pooling zu ermöglichen.Maske löschen: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskelschen.htm#sxDeleteMask UNIX-Script] werden Masken aus allen dazugehörigen Tabellen entfernt. Zusätzlich wird auch der Eintrag im Themenbaum gelöscht. Zur Sicherheit muss die Nummer der Maske manuell eingegeben werden.Maske suchen: Sie können Masken suchen und im XML-Frontend komfortabel editieren. Schränken Sie Ihre Auswahl auf ein Sachgebiet ein, und drücken Sie "Abschicken". Sie erhalten eine Liste mit "Treffern", und rechts befinden sich jeweils Buttons zum ansehen bzw. editieren einer Maske.
Die Maske läuft nur unter Postgres, weil Informix kein direktes Bearbeiten von Blob-Feldern mit sql unterstützt.Analog können Felder kopiert, gelöscht oder gesucht werden.
</blockquote>

<blockquote>

Die Abfragen sind selbsterklärend; das Erzeugen neuer Masken, Löschen vorhandener Masken und Kopieren vorhandener Masken ist nur für Userkennungen möglich, die in der Tabelle userinfo im Feld administration den Wert 1 haben. Natürlich sollten die Abfragen sehr vorsichtig benutzt werden, sie sind die einzigen Abfragen in SuperX, die tatsächlich Änderungen an der Datenbank vornehmen können.

</blockquote>

=Grundlagen=

In den folgenden Abschnitten werden die Grundlagen der Maskenentwicklung erläutert. Beginnend beim Abruf einer Ergebnistabelle aus einer Maske, über die Definition der Felder dieser Maske, bis hin zur Definition der dahinterliegenden SQL-Anweisungen.

==Abrufen einer Ergebnistabelle==
Der Ausgangspunkt ist ein Beispiel aus dem SOS-Modul. Auf der folgenden Abbildung ist der Themenbaum ersichtlich, welcher sich in verschiedene Bereiche gliedert.

<blockquote>
{{ImagePara |imgsrc=Themenbaum.PNG|width=600|caption=Themenbaum}}

Wählt man aus der Navigation auf der linken Seite einen Bereich aus, werden Abfragen sichtbar. In diesem Fall ist der Bereich "Bewerbung, Zulassung" ausgewählt und es wird unter anderem die Abfrage "Bewerbungsprozess nach Fach/Studiengang" sichtbar.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Maske.PNG|width=600|caption=Maske}}

Wählt man eine Abfrage aus, erscheint eine Maske, welche verschiedene Möglichkeiten zur Parametrisierung bietet.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Ergebnistabelle.PNG|width=600|caption=Ergebnistabelle}}

Nach einem Klick auf "Abschicken" erscheint die entsprechende Ergebnistabelle.
</blockquote>

==Die Felddefinitionen==
Gehen wir kurz zurück zur Auswahlmaske. Jedes Feld der Maske, z.B. "Semester", ist ein Datensatz in der Tabelle 'felderinfo' . Dort finden Sie Angaben zum Namen, Inhalt und Layout des Feldes. Gehen wir zunächst zum Inhalt des Feldes: Die Liste der Semester.

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemester.png|width=400|caption=MaskenfeldSemester}}

Beim Klick auf das Feld Semester erhalten wir eine Reihe von Semestern zur Auswahl. Die Liste ist absteigend sortiert. Sie wird durch die SQL Anweisung [<<SQL>> select tid, eintrag from zul_semester order by tid DESC;] erzeugt. Die SQL-Anweisung liefert aus der Tabelle 'zul_semester' die Felder 'tid' ("Tupelidentifier") und 'eintrag' (der Volltext des Semesters). Der Schlüssel des Feldes 'tid' ist unsichtbar, sorgt aber dafür, dass die Sortierung richtig erfolgt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=DatenbanktabelleZulSemester.png|width=400|caption=DatenbanktabelleZulSemester}}

Hier sehen Sie einen Screenshot der Tabelle 'zul_semester' direkt in der Datenbank. Die Nummerierung ist fünfstellig und besteht aus Jahr (vier Stellen) und 1 für Sommer- und 2 für Wintersemester.
</blockquote>

==Speichern der Felddefinition==
Wo wird nun in SuperX die Felddefinition gespeichert? Viele Scripte in SuperX werden selbst in Datenbanktabellen abgelegt, die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo felderinfo] enthält die relevanten Angaben für die Felder. Um dies zu sehen, öffnen wir ein Formular im XML-Frontend. Dort befinden sich Bearbeitungsformulare für Felder und Masken.

<blockquote>
{{ImagePara |imgsrc=FeldSuchen.png|width=600|caption=FeldSuchen}}

Im Themenbaum des XML-Frontends finden wir den Menüpunkt '''Administration → Felder → Feld suchen'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenMaske.png|width=600|caption=FeldSuchenMaske}}

In dem Formular wählen wir die Abfrage "Bewerbungsprozess nach Fach/Studiengang" aus. Zusätzlich sehen wir auch die Nummer der Maske (26020), was bei der Maskenbearbeitung ganz nützlich ist. Mit einem Klick auf "Abschicken" werden die Eingaben bestätigt und abgeschickt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenErgebnis.png|width=600|caption=FeldSuchenErgebnis}}

Es wird eine Liste mit den vorhandenen Feldern geliefert. Wir sehen die Nummer des Feldes und den Namen. Rechts daneben befindet sich ein Knopf zum Bearbeiten des Feldes.
</blockquote>

Ein kleiner Hinweis an dieser Stelle: Die Felder werden in der Tabelle masken_felder_bez der Maske Nr. 26020 zugeordnet. Wir zählen also bei Feldnummern in Einer-Schritten von der Maskennummer aus hoch. Aus diesem Grunde wählen wir bei Maskennummern größere Intervalle.

<blockquote>
{{ImagePara |imgsrc=BearbeitungsformularFeld.png|width=600|caption=BearbeitungsformularFeld}}

Wir wählen nun das Feld "Semester" und gelangen in ein Bearbeitungsformular der Tabelle 'felderinfo' . Wir sehen Name, Nummer, Position auf der Maske, Breite und Typ des Feldes (ganzzahlig). Das Feld ist obligatorisch und von der Art Nr. 1 (Nummer + Text, mit Dialog). Im Feld 'relation' steht nach dem Steuerungszeichen <<SQL>> der SQL-Befehl. Unten ist noch der Defaultwert für das Feld angegeben, ebenfalls ein SQL-Ausdruck.
</blockquote>

SuperX liest also aus der Datenbank die Scripte für eine Maske bzw. für ein Feld aus einer Tabelle, und führt Sie dann in der Datenbank aus.

==Änderung einer Felddefinition==

<blockquote>
{{ImagePara |imgsrc=FeldBearbeiten.png|width=600|caption=FeldBearbeiten}}

Um die Felddefinition zu ändern, kann nun beispielsweise beim SQL-Befehl DESC durch ASC ersetzt und gespeichert werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemesterASC.png|width=400|caption=MaskenfeldSemesterASC}}

Um das neue Script aus der Datenbank zu laden, muss die Maske nun erneut über den Themebaum aufgerufen werden. Wenn wir dann in der Maske auf "Semester" klicken, erscheinen die Semester in aufsteigender Reihenfolge.
</blockquote>

Auf diese Art und Weise können wir alle Maskenfelder bearbeiten. Die restlichen Attribute in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] sind im [https://super-ics.de/superx/doku/kern_modul/admin/f_TabelleFelderinfo.htm Administrationshandbuch Kernmodul] erläutert.

==Maskendefinition==

So weit so gut, wir können nun also Felder ändern. Wie können wir nun die Ergebnistabellen bearbeiten? 
SuperX arbeitet hier ebenfalls mit SQL-Scripten, die als Felder in einer Tabelle gespeichert sind. Die Tabelle lautet [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_maskeninfo 'maskeninfo']. Wir können uns diese Tabelle ebenfalls im XML-Frontend anschauen:

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenMaske.png|width=600|caption=MaskeSuchenMaske}}

Im Themenbaum wählen wir "Administation → Masken verwalten → Maske suchen". Es erscheint eine Auswahlmaske ohne Vorbelegung. Es lässt sich nun eine Maske anhand einer Auswahlliste oder Maskennummer suchen. Um das Feld für die Suche mit Maskennummer einzublenden, muss das Schlüsselsymbol geklickt werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenErgebnis.png|width=600|caption=MaskeSuchenErgebnis}}

Als Ergebnis sehen wir unsere Maske sowie mehrere Bearbeitungsbuttons. Wir wählen den ersten Button, '''Bearbeiten'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeninfoVerwalten.png|width=600|caption=MaskeninfoVerwalten}}

Wir gelangen in das Bearbeitungsformular der Maske. Neben der Nummer der Maske sehen wir unter anderem den Namen und die Felder 'Select-Statement' und 'Spaltenlayout'. Das Feld 'Select-Statement' enthält das SQL-Script und 'Spaltenlayout' die Ergebnisdarstellung.
</blockquote>

==Abfragen in Maskendefinitionen==

Allgemein formuliert arbeiten wir so:
# Zunächst werden die Eingaben in den Auswahlfeldern ausgewertet und eine Ergebnismenge ermittelt, meist in Form einer temporären Tabelle.
# Diese Tabelle wird mit den Hilfstabellen in der Datenbank gejoined, und es wir eine Ergebnistabelle berechnet. Ggf. werden noch Summen oder Prozente berechnet, meist benötigen wir dazu weitere temporäre Tabellen.
# Der letzte select im Feld 'Select-Statement' enthält die Ergebnistabelle, die das Applet empfängt. Im Feld 'Spaltenlayout' werden die Spaltenüberschriften- und Breiten gesetzt und das Ergebnis wird angezeigt.
# Direkt danach wird die letzte temporäre Tabelle gedroppt, und die Datenbankverbindung wird an das SuperX-Servlet zurückgegeben.

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenPruefungsstatistik.png|width=600|caption=MaskeSuchenPruefungsstatistik}}

Im Folgenden wird als Beispiel der Bericht "Studierende, Prüfungen → Einzelprüfungen → Prüfungsstatistik" herangezogen. Das Script in 'Select-Statement' ist relativ lang, wir wollen es daher nur Auszugsweise kommentieren.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement1.png|width=600|caption=SelectStatement1}}

Zu Beginn des Select-Statements wird über <code>select ... into temp tmp_ergebnis</code> die Ergebnismenge der temporären Tabelle 'tmp_ergebnis' übergeben. Einige Felder unterliegen bestimmten Kriterien, wie bspw. das Feld 'bestanden': <code>(case when P.pstatus='BE' then 1 else 0 end) as bestanden</code>
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement2.png|width=600|caption=SelectStatement2}}

In der folgenden where-Klausel werden verschiedene Bedingungen festgelegt. Hier finden sich Platzhalter wie <code><<Seit Semester>></code>. Diese Platzhalter entsprechen den Maskenfeldern und werden mit den Benutzereingaben gefüllt. Passagen innerhalb <code>/* ... */</code> werden nur dann ausgeführt, wenn das entsprechende Maskenfeld gefüllt wurde. Da es sich bei <code><<Seit Semester>></code> um ein Pflichtfeld handelt, ist diese Einschränkung dort nicht nötig.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement3.png|width=600|caption=SelectStatement3}}

Um diverse Berechnungen anzustellen werden, wird die Ergebnismenge in eine zweite temporäre Tabelle überführt: <code>select ... into temp tmp_ergebnis2</code>. Die erste temporäre Ergebnistabelle wird gelöscht: <code>drop table tmp_ergebnis;</code>.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement4.png|width=600|caption=SelectStatement4}}

Der letzte Select greift auf die zweite temporäre Tabelle zu und enthält die Ergebnistabelle.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Spaltenlayout.png|width=600|caption=Spaltenlayout}}

Im Feld 'Spaltenlayout' wird das Layout der Spalten der Ergebnistabelle festgelegt. Der markierte Bereich definiert das Layout der ersten Spalte. Spaltenüberschriften sind von 0 aufsteigend durchnummeriert, und die Überschriften selbst können durch "\n" mit Zeilenumbrüchen versehen werden. Pro Überschrift wird ein Absatz formuliert, u.a. auch die Breite der Spalte. Dabei ist zu beachten, dass die Darstellung in HTML vom verwandten Browser abhängt. 'Width' beispielsweise hat auf die HTML-Darstellung keinen Einfluss.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=CleanupStatements.png|width=600|caption=CleanupStatements}}

Wichtig ist außerdem, dass die zweite temporäre Tabelle gelöscht wird. Dies geschieht durch ein kurzes SQL-Statement in 'Cleanup Statements'.
</blockquote>

==Masken erstellen aus Kopien==

Zur Maskenerstellung werden Kopien bereits existierender Masken erstellt. Es ist ratsam Masken zu kopieren, welche der neu zu erstellenden Masken thematisch ähneln. Das bringt den Vorteil, dass diverse Felder der Kopie weiterverwendet werden können. Unter {{Pfad3|Administration|Masken verwalten|Maske kopieren}} findet sich die entsprechende Maske.

<blockquote>
Es wird zunächst die zu kopierende Maske gewählt und anschließend eine tid und ein Name, sowie eine Erläuterung für die neue Maske vergeben. Nach Patch 2022-01-28 kann wahlweise die neue Maske direkt als Makro erstellt werden.

{{ImagePara |imgsrc=Maske_kopieren_1.png|width=600|caption=Auswahlmaske Maske kopieren}}

Bei diesem Beispiel würde die Maske "Studierende nach Alter" kopiert und eine neue Masken "Studierende nach Geschlecht" mit der tid 15980 erstellt.
</blockquote>

{{Achtung|Bei der Vergabe der neuen tid unbedingt darauf achten, dass diese nicht bereits belegt ist.}}

Bei der Vergabe der neuen tid wird mindestens in Dreißigerintervallen vorgegangen, damit für die Felder der Masken ausreichend tids verfügbar sind.

<blockquote>
Um die belegten Masken-tid zu ermitteln eignet sich {{Pfad3|Administration|Masken verwalten|Maske suchen}}, da dort beim Feld Maske die Masken nach tids aufsteigend sortiert sind.

{{ImagePara |imgsrc=Masken_tids.png|width=600|caption=Auswahlmaske Maske suchen}}
</blockquote>

Die Feld-tids werden beginnend ab der Masken-tid direkt aufeinanderfolgend vergeben. Ein Dreißigerintervall zwischen den Masken-tids ermöglicht es somit dreißig Felder pro Maske zu vergeben. Trotzdem sollte immer geprüft werden, ob die vorherige Maske gegebenenfalls mehr als dreißig Felder besitzt und entsprechend ein größeres Intervall zu wählen ist. Hierfür eignet sich {{Pfad4|Administration|Masken verwalten|Felder|Feld suchen}}

<blockquote>
{{ImagePara |imgsrc=Feld_suchen_1.png|width=600|caption=Auswahlmaske Felder suchen}}

{{ImagePara |imgsrc=Feld_suchen_2.png|width=400|caption=Ergebnistabelle Felder suchen}}

Die Maske "16340-Studierende nach Alter" besitzt 17 Felder. Ein Dreißigerintervall wäre somit ausreichend.
</blockquote>

==Masken oder Felder löschen==

Masken und Felder werden über {{Pfad4|Administration|Masken verwalten|Felder|Feld löschen}} und {{Pfad3|Administration|Masken verwalten|Maske löschen}} gelöscht. Dies hat den Vorteil, dass anhand der entsprechenden tid die Einträge für diese Maske oder dieses Feld aus sämtlichen Tabellen gelöscht wird. Falls die Einträge für ein Feld oder eine Maske nur in den Tabellen maskeninfo und felderinfo gelöscht würden, wären beispielsweise in der Feldverwaltung leere Felder zu finden. Um den Datenbestand sauber zu halten wird daher empfohlen, die angesprochenen Formulare "Feld löschen" und "Maske löschen" zu nutzen.

==Konventionen==

Für die Erstellung von SQL-Abfragen gibt es ein paar wichtige Konventionen:
* wenn Sie Abfragen schreiben, sollten Sie temporäre Tabellen immer mit "tmp_" vorab benennen. Grund: es könnte mal sein, dass wir die Tabelle auch als statische Tabelle nutzen. Dann gibt es einen SQL-Fehler.
* vermeiden Sie bei temporären Tabellen Umlaute in Spaltennamen (z.B. "Fakultät"). Das klappt zwar unter Informix, aber nicht unter Postgres.
* Nutzen Sie, wenn möglich, die ANSI-SQL-Standards.

=Abfragenentwurf mit SuperX-Sichten=

<blockquote>
In SuperX können bei Auswahldialogen verschiedene Sichten angeboten werden (vgl. [[SuperX-Benutzungshandbuch_Basics#Alternative_Hierarchien_zur_Datenselektion|Alternative Hierarchien zur Datenselektion]]). Alternative Hierarchien bzw. Auswertungshierarchien aus COB werden automatisiert übernommen. Jede Hierarchie bekommt einen Eintrag in der Sichtentabelle.

<div id="SichtenAuswahl">{{ImagePara |imgsrc=SichtenAuswahl.png|width=600|caption=SichtenAuswahl}}</div>

{{Achtung|Die Inhalte und Rechte der Sichten werden gecached. Nach einer Änderung der Inhalte einer Sicht im laufenden Betrieb musst man im SuperXManager den Cache leeren und sich neu anmelden.}}Die Sichten werden in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten 'sichten'] definiert. Eine Übersicht über die Tabellenstruktur inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten hier].
</blockquote>

<blockquote>
Die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten sichten] lässt sich wie auch die Masken und Felder (s. Abschnitt [[Masken-Tutorial#Maskendefinition|Maskendefinition]] und [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) in SuperX über ein Bearbeitungsformular manipulieren.

{{ImagePara |imgsrc=SichtSuchen.png|width=600|caption=SichtSuchen}}

Im Folgenden wird die Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" näher betrachtet.

{{ImagePara |imgsrc=SichtFachAbschluss.png|width=600|caption=SichtFachAbschluss}}

</blockquote>

{{Achtung|Das Feld {{Feld|quelle}} in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten sichten] ist auf 255 Zeichen begrenzt. Falls mehr Zeichen benötigt werden, kann in den Feldern {{Feld|cacheapplet}} und {{Feld|cachexml}} der SQL fortgeführt werden. Die beiden genannten Felder waren historisch für andere Zwecke geplant, werden für diese aber nicht mehr benötigt.}}

<blockquote>
Bei <code>sos_org_lehre_fach_absch_ude</code> handelt es sich um eine "View". Diese "View" beinhaltet mehrere Select-Statements, welche quasi die verschiedenen Ebenen der Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" darstellen.

{{ImagePara |imgsrc=ViewFachAbschUDE.png|width=600|caption=ViewFachAbschUDE}}

Das Organigramm stellt eine integrierende Sicht für verschiedene Datenquellen zusammen und ist somit die Voraussetzung für eine integrierte Betrachtung. Alle Einrichtungen, Institutionen und Projekte sind im Organigramm hierarchisch angeordnet (vgl. [https://super-ics.de/superx/doku/kern_modul/admin/f_DasOrganigramm.htm Das Organigramm]). Das Feld 'lehre' wird entweder mit 1 oder 0 gefüllt, um festzustellen ob die Institution relevant für Auswertungen im Bereich Lehre ist (1=ja, 0=nein).

Erläuterung des parent-Felds:Das Parent-Feld gibt die key_apnr der übergeordneten organisatorischen Einheit an. Das root-Element des Baums besitzt als parent einen null-Wert. Das Organigramm darf demenstprechend nur ein Element haben, dass keinen parent besitzt. Hier sollte grundsätzlich die Hochschulnummer eingetragen werden die auch in anderen HIS-Programmen verwendet wird. In Duisburg ist dies z.B. der Basiseintrag key_apnr = "70" ( GMU Duisburg ). Es ist praktisch der oberste "Knoten" im Baum. Dann werden alle Einträge in der Tabelle organigramm gesucht, die parent="70" haben – also direkte Kinder des Basiseintrags.Hier findet sich u.a. Einrichtungen Forschung und Lehre (key_apnr="7", parent="70"). Dieser Eintrag hat wiederum u.a. folgende Kinder:
*Fakultät 1 (key_apnr="1100", parent="7")
*Fakultät 2 (key_apnr="1200", parent="7")
*Faktultät 3 (key_apnr="1300", parent="7")
usw.

Die weiteren Äste des Baums werden rekursiv abgefragt. Die Struktur der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm 'organigramm'] inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm hier]. Die Tabelle [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang 'dim_studiengang'] enthält Datensätze zu Studiengängen (Die Struktur der Tabelle inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang hier]).
</blockquote>

<blockquote>
Für alle Sichten wird erwartet, dass mindestens die drei Felder name, key und parent geliefert werden (der konkrete Name der Spalten ist irrelevant).
Anschließend können optional noch Strukturinformationen folgen (entweder Integer oder String).Beispiel:<code>sp_fin_inst_hier(<<UserID>>,<<Stand>>,<<Sicht>>);select name,key,parent,strukturint from tmp_hier order by name; drop table tmp_hier;</code>strukturint (gefüllt aus fin_inst.orgstruktur) gibt mit Zahlen an, ob ein Eintrag eine Lehreinheit oder ein Fachbereich ist.Auf diese Information kann später in Abfragen mit FreeMarker zugegriffen werden.Beispiel:
{{ImagePara |imgsrc=FreemarkerStrukturInt.png|width=500|caption=FreemarkerStrukturInt}}
</blockquote>

==Einträge verstecken oder nicht-selektierbar machen==

<blockquote>
Es kann gewünscht sein, dass Einträge versteckt hinterlegt werden. Betrachtet sei weiterhin die Sicht [[#SichtenAuswahl|'FB/Fak, Lehreinheit, Fach/Abschluss']]. Die unterste sichtbare Ebene ist Fach/Abschluss. Man könnte also annehmen, es würde genügen, diese Sicht bis zur Ebene Fach/Abschluss aufzubauen. Dem ist allerdings nicht so. Es benötigt eine weitere, darunterliegende, aber nicht sichtbare Ebene "Studiengang".

<div id="ViewFachAbschUDESichtbarUnsichtbar">{{ImagePara |imgsrc=ViewFachAbschUDESichtbarUnsichtbar.png|width=600|caption=ViewFachAbschUDESichtbarUnsichtbar}}</div>
</blockquote>

<blockquote>
Zum Verständnis ein Beispiel anhand der Auswertung "Studierende nach Alter". Zunächst wird eine Kombination "Fach/Abschluss" ausgewählt.

{{ImagePara |imgsrc=AuswahlSichtBWLBA.png|width=400|caption=AuswahlSichtBWLBA}}
</blockquote>

<blockquote>
Es erscheint folgende Ergebnistabelle:

{{ImagePara |imgsrc=ErgebnistabelleStudierendeNachAlter.png|width=600|caption=ErgebnistabelleStudierendeNachAlter}}
</blockquote>

<blockquote>
Im SQL erfolgt die Einschränkung auf den im Sichtenbaum ausgewählten Eintrag durch <code>where ... 's_' || L.tid in <@printkeys Studiengang.allNeededKeysList/> ... </code>. Für unser Beispiel sieht diese Passage nach der Freemarker-Transformation folgendermaßen aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS','s_3','s_36','s_33','s_65','s_270','s_87') ...</code>. Würde die unterste, unsichtbare Ebene 'Studiengang' entfallen (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']]), sähe der SQL stattdessen so aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS') ...</code>. Das hätte zur Folge, dass keine Einträge gefunden würden, denn es wird nach dem Muster 's_tid' gesucht.

Um eine Ebene unsichtbar zu machen benötigt es das Attribut 'nodeattrib'. Wird diesem der Wert 1 übergeben, so ist die Ebene unsichtbar. Mit dem Wert 0 bleibt die Ebene sichtbar (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']], Zeile 21 und 30).

</blockquote>

<blockquote>
Weiterhin kann es gewünscht sein, dass man in einer Sicht nur spezielle Einträge auswählen kann. So können man eine Lehreinheitsauswahl vielleicht so darstellen:

Uni XY
* Fak 1
** Lehreinheit A
** Lehreinheit B
* Fak 2
** Lehreinheit C
** Lehreinheit D

Die Kategorisierung Fak 1/2 dient der Klarheit der Darstellung, für eine Abfrage soll aber vielleicht nur eine konkrete Lehreinheit auswählbar sein. In dem Fall kann wie oben das nodeattrib 2 vergeben werden. Dadurch wird ein Eintrag als nicht-selektierbar markiert.
</blockquote>

==User-/Gruppenrechte==

<blockquote>
Außer Administratoren dürfen normale User zunächst einmal keine der nicht-internen Sichten benutzen.In den Tabellen user_sichten und user_sichtarten kann hinterlegt werden, dass ein User eine einzelne Sicht (z.B. name_intern Kostenstellen-Hauptsicht) oder eine ganze Sichtart (z.B. Kostenarten) benutzen darf.Für Gruppen gibt es analog die Tabellen group_sichten und group_sichtarten.Außerdem sachgeb_sichten und sachgeb_sichtarten, wenn Leute die ganze Sachgebiete sehen dürfen auch Sicht sehen sollen.Die Pflege dieser Tabellen kann bequem über Administrationsformular im XML-Frontend vorgenommen werden.<blockquote> Achtung:Nach Änderungen muss der Server-Cache aktualisiert werden und der User muss sich neu anmelden. Alternativ könnte auch Tomcat neu gestartet werden. </blockquote>Im Dateisystem unter $SUPERX_DIR/db/bin gibt es zwei Skripte userrechte_sichern.x und userrechte_einspielen.x.Die entladen alle usertabellen (userinfo,groupinfo,user_sachgeb_bez etc) und spielen sie wieder ein.Diese können z.B. dafür benutzt werden um alle Einstellungen von Test auf Echtrechner zu übernehmen.
</blockquote>

==Benutzen der Sichten in Masken==

<blockquote>
In [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] (s. [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) muss als Art 12-Sicht eingetragen werden.Im Feld Relation muss ein Select stehen, der die 'tids' der gewünschten Sichten zurückliefert.

{{ImagePara |imgsrc=FeldBearbeitenArtSicht.png|width=600|caption=FeldBearbeitenArtSicht}}

<blockquote>Die aktiv-Einschränkung ist praktisch für Entwicklungs- und Wartungszwecke, weil man dann leicht einzelne Sichten de/aktivieren kann - Sortierung nach type, damit erst Hauptsichten und dann alternative Hierarchien angezeigt werden, dann nach Name.</blockquote>Der select sollte alle Sichtentids liefern, die ein Adminstrator sehen darf.Wenn ein User für einzelne Sichten keine Berechtigung hat, filtert der Server diese automatisch raus.
</blockquote>

Masken-Tutorial

2026-06-25T06:56:39Z

Danielq: /* Orientierung */

=Orientierung=

<blockquote>
Die Abfragemasken liefern die Daten aus den Basissystemen an das SuperX-Frontend aus. Einige Abfragen zur Administration sind im Kernmodul enthalten, die Abfragen zu den Basissystemen sind in den jeweiligen Modulen enthalten. Die Abfragen in der Administration erlauben es, neue Masken anzulegen, zu kopieren und zu löschen. Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis 1xxxx0000 bis 1xxxx9970 liegen, wobei xxxx der von DESTATIS verwandten Hochschulnummer entspricht (bei dreistelligen Nummern mit führender 0), also z.B. 1'''1810'''0000 für die erste Maske der Uni Mannheim. Es sind Dreißigerschritte zu wählen, da die dazwischen liegenden Nummern für die Maskenfelder (Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo']) reserviert sind.
</blockquote>

<blockquote>
Im Folgenden finden Sie allgemeine Hinweise für die Verwaltung der Masken. Die Masken lassen sich browserbasiert, über UNIX-Shellscripte, und über Access administrieren. Weitergehende Möglichkeiten bietet aber das XML-Frontend (Möglichkeit der Editierung von großen text -Feldern bei Postgres als Datenbanksystem). Nach der Anmeldung haben Administratoren das Recht, Masken zu löschen, zu kopieren und erzeugen. Die einzelnen Felder der Masken lassen sich direkt in der Datenbank oder z.B. mit MS Access verändern. Im Applet sind nur grundlegende Verwaltungsoperationen möglich. Sie sind als Ersatz für die UNIX- Scripte gedacht.
</blockquote>

<blockquote>
Maske kopieren: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskeneueinfgen.htm#sxinsertmask UNIX - Script] wir eine Maske in eine neue Maske kopiert, und alle zugehörigen Tabellen werden aktualisiert. Zusätzlich wird auch der Eintrag im Themenbaum gemacht. Bei der Nummer der Maske (tid) sollten Sie das Nummernschema von SuperX einhalten, um in Zukunft Abfragen-Pooling zu ermöglichen.Maske löschen: Wie im [https://super-ics.de/superx/doku/entwicklerhandbuch/EineMaskelschen.htm#sxDeleteMask UNIX-Script] werden Masken aus allen dazugehörigen Tabellen entfernt. Zusätzlich wird auch der Eintrag im Themenbaum gelöscht. Zur Sicherheit muss die Nummer der Maske manuell eingegeben werden.Maske suchen: Sie können Masken suchen und im XML-Frontend komfortabel editieren. Schränken Sie Ihre Auswahl auf ein Sachgebiet ein, und drücken Sie "Abschicken". Sie erhalten eine Liste mit "Treffern", und rechts befinden sich jeweils Buttons zum ansehen bzw. editieren einer Maske.
Die Maske läuft nur unter Postgres, weil Informix kein direktes Bearbeiten von Blob-Feldern mit sql unterstützt.Analog können Felder kopiert, gelöscht oder gesucht werden.
</blockquote>

<blockquote>

Die Abfragen sind selbsterklärend; das Erzeugen neuer Masken, Löschen vorhandener Masken und Kopieren vorhandener Masken ist nur für Userkennungen möglich, die in der Tabelle userinfo im Feld administration den Wert 1 haben. Natürlich sollten die Abfragen sehr vorsichtig benutzt werden, sie sind die einzigen Abfragen in SuperX, die tatsächlich Änderungen an der Datenbank vornehmen können.

</blockquote>

=Grundlagen=

In den folgenden Abschnitten werden die Grundlagen der Maskenentwicklung erläutert. Beginnend beim Abruf einer Ergebnistabelle aus einer Maske, über die Definition der Felder dieser Maske, bis hin zur Definition der dahinterliegenden SQL-Anweisungen.

==Abrufen einer Ergebnistabelle==
Der Ausgangspunkt ist ein Beispiel aus dem SOS-Modul. Auf der folgenden Abbildung ist der Themenbaum ersichtlich, welcher sich in verschiedene Bereiche gliedert.

<blockquote>
{{ImagePara |imgsrc=Themenbaum.PNG|width=600|caption=Themenbaum}}

Wählt man aus der Navigation auf der linken Seite einen Bereich aus, werden Abfragen sichtbar. In diesem Fall ist der Bereich "Bewerbung, Zulassung" ausgewählt und es wird unter anderem die Abfrage "Bewerbungsprozess nach Fach/Studiengang" sichtbar.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Maske.PNG|width=600|caption=Maske}}

Wählt man eine Abfrage aus, erscheint eine Maske, welche verschiedene Möglichkeiten zur Parametrisierung bietet.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Ergebnistabelle.PNG|width=600|caption=Ergebnistabelle}}

Nach einem Klick auf "Abschicken" erscheint die entsprechende Ergebnistabelle.
</blockquote>

==Die Felddefinitionen==
Gehen wir kurz zurück zur Auswahlmaske. Jedes Feld der Maske, z.B. "Semester", ist ein Datensatz in der Tabelle 'felderinfo' . Dort finden Sie Angaben zum Namen, Inhalt und Layout des Feldes. Gehen wir zunächst zum Inhalt des Feldes: Die Liste der Semester.

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemester.png|width=400|caption=MaskenfeldSemester}}

Beim Klick auf das Feld Semester erhalten wir eine Reihe von Semestern zur Auswahl. Die Liste ist absteigend sortiert. Sie wird durch die SQL Anweisung [<<SQL>> select tid, eintrag from zul_semester order by tid DESC;] erzeugt. Die SQL-Anweisung liefert aus der Tabelle 'zul_semester' die Felder 'tid' ("Tupelidentifier") und 'eintrag' (der Volltext des Semesters). Der Schlüssel des Feldes 'tid' ist unsichtbar, sorgt aber dafür, dass die Sortierung richtig erfolgt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=DatenbanktabelleZulSemester.png|width=400|caption=DatenbanktabelleZulSemester}}

Hier sehen Sie einen Screenshot der Tabelle 'zul_semester' direkt in der Datenbank. Die Nummerierung ist fünfstellig und besteht aus Jahr (vier Stellen) und 1 für Sommer- und 2 für Wintersemester.
</blockquote>

==Speichern der Felddefinition==
Wo wird nun in SuperX die Felddefinition gespeichert? Viele Scripte in SuperX werden selbst in Datenbanktabellen abgelegt, die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo felderinfo] enthält die relevanten Angaben für die Felder. Um dies zu sehen, öffnen wir ein Formular im XML-Frontend. Dort befinden sich Bearbeitungsformulare für Felder und Masken.

<blockquote>
{{ImagePara |imgsrc=FeldSuchen.png|width=600|caption=FeldSuchen}}

Im Themenbaum des XML-Frontends finden wir den Menüpunkt '''Administration → Felder → Feld suchen'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenMaske.png|width=600|caption=FeldSuchenMaske}}

In dem Formular wählen wir die Abfrage "Bewerbungsprozess nach Fach/Studiengang" aus. Zusätzlich sehen wir auch die Nummer der Maske (26020), was bei der Maskenbearbeitung ganz nützlich ist. Mit einem Klick auf "Abschicken" werden die Eingaben bestätigt und abgeschickt.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=FeldSuchenErgebnis.png|width=600|caption=FeldSuchenErgebnis}}

Es wird eine Liste mit den vorhandenen Feldern geliefert. Wir sehen die Nummer des Feldes und den Namen. Rechts daneben befindet sich ein Knopf zum Bearbeiten des Feldes.
</blockquote>

Ein kleiner Hinweis an dieser Stelle: Die Felder werden in der Tabelle masken_felder_bez der Maske Nr. 26020 zugeordnet. Wir zählen also bei Feldnummern in Einer-Schritten von der Maskennummer aus hoch. Aus diesem Grunde wählen wir bei Maskennummern größere Intervalle.

<blockquote>
{{ImagePara |imgsrc=BearbeitungsformularFeld.png|width=600|caption=BearbeitungsformularFeld}}

Wir wählen nun das Feld "Semester" und gelangen in ein Bearbeitungsformular der Tabelle 'felderinfo' . Wir sehen Name, Nummer, Position auf der Maske, Breite und Typ des Feldes (ganzzahlig). Das Feld ist obligatorisch und von der Art Nr. 1 (Nummer + Text, mit Dialog). Im Feld 'relation' steht nach dem Steuerungszeichen <<SQL>> der SQL-Befehl. Unten ist noch der Defaultwert für das Feld angegeben, ebenfalls ein SQL-Ausdruck.
</blockquote>

SuperX liest also aus der Datenbank die Scripte für eine Maske bzw. für ein Feld aus einer Tabelle, und führt Sie dann in der Datenbank aus.

==Änderung einer Felddefinition==

<blockquote>
{{ImagePara |imgsrc=FeldBearbeiten.png|width=600|caption=FeldBearbeiten}}

Um die Felddefinition zu ändern, kann nun beispielsweise beim SQL-Befehl DESC durch ASC ersetzt und gespeichert werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskenfeldSemesterASC.png|width=400|caption=MaskenfeldSemesterASC}}

Um das neue Script aus der Datenbank zu laden, muss die Maske nun erneut über den Themebaum aufgerufen werden. Wenn wir dann in der Maske auf "Semester" klicken, erscheinen die Semester in aufsteigender Reihenfolge.
</blockquote>

Auf diese Art und Weise können wir alle Maskenfelder bearbeiten. Die restlichen Attribute in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] sind im [https://super-ics.de/superx/doku/kern_modul/admin/f_TabelleFelderinfo.htm Administrationshandbuch Kernmodul] erläutert.

==Maskendefinition==

So weit so gut, wir können nun also Felder ändern. Wie können wir nun die Ergebnistabellen bearbeiten? 
SuperX arbeitet hier ebenfalls mit SQL-Scripten, die als Felder in einer Tabelle gespeichert sind. Die Tabelle lautet [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_maskeninfo 'maskeninfo']. Wir können uns diese Tabelle ebenfalls im XML-Frontend anschauen:

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenMaske.png|width=600|caption=MaskeSuchenMaske}}

Im Themenbaum wählen wir "Administation → Masken verwalten → Maske suchen". Es erscheint eine Auswahlmaske ohne Vorbelegung. Es lässt sich nun eine Maske anhand einer Auswahlliste oder Maskennummer suchen. Um das Feld für die Suche mit Maskennummer einzublenden, muss das Schlüsselsymbol geklickt werden.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenErgebnis.png|width=600|caption=MaskeSuchenErgebnis}}

Als Ergebnis sehen wir unsere Maske sowie mehrere Bearbeitungsbuttons. Wir wählen den ersten Button, '''Bearbeiten'''.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=MaskeninfoVerwalten.png|width=600|caption=MaskeninfoVerwalten}}

Wir gelangen in das Bearbeitungsformular der Maske. Neben der Nummer der Maske sehen wir unter anderem den Namen und die Felder 'Select-Statement' und 'Spaltenlayout'. Das Feld 'Select-Statement' enthält das SQL-Script und 'Spaltenlayout' die Ergebnisdarstellung.
</blockquote>

==Abfragen in Maskendefinitionen==

Allgemein formuliert arbeiten wir so:
# Zunächst werden die Eingaben in den Auswahlfeldern ausgewertet und eine Ergebnismenge ermittelt, meist in Form einer temporären Tabelle.
# Diese Tabelle wird mit den Hilfstabellen in der Datenbank gejoined, und es wir eine Ergebnistabelle berechnet. Ggf. werden noch Summen oder Prozente berechnet, meist benötigen wir dazu weitere temporäre Tabellen.
# Der letzte select im Feld 'Select-Statement' enthält die Ergebnistabelle, die das Applet empfängt. Im Feld 'Spaltenlayout' werden die Spaltenüberschriften- und Breiten gesetzt und das Ergebnis wird angezeigt.
# Direkt danach wird die letzte temporäre Tabelle gedroppt, und die Datenbankverbindung wird an das SuperX-Servlet zurückgegeben.

<blockquote>
{{ImagePara |imgsrc=MaskeSuchenPruefungsstatistik.png|width=600|caption=MaskeSuchenPruefungsstatistik}}

Im Folgenden wird als Beispiel der Bericht "Studierende, Prüfungen → Einzelprüfungen → Prüfungsstatistik" herangezogen. Das Script in 'Select-Statement' ist relativ lang, wir wollen es daher nur Auszugsweise kommentieren.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement1.png|width=600|caption=SelectStatement1}}

Zu Beginn des Select-Statements wird über <code>select ... into temp tmp_ergebnis</code> die Ergebnismenge der temporären Tabelle 'tmp_ergebnis' übergeben. Einige Felder unterliegen bestimmten Kriterien, wie bspw. das Feld 'bestanden': <code>(case when P.pstatus='BE' then 1 else 0 end) as bestanden</code>
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement2.png|width=600|caption=SelectStatement2}}

In der folgenden where-Klausel werden verschiedene Bedingungen festgelegt. Hier finden sich Platzhalter wie <code><<Seit Semester>></code>. Diese Platzhalter entsprechen den Maskenfeldern und werden mit den Benutzereingaben gefüllt. Passagen innerhalb <code>/* ... */</code> werden nur dann ausgeführt, wenn das entsprechende Maskenfeld gefüllt wurde. Da es sich bei <code><<Seit Semester>></code> um ein Pflichtfeld handelt, ist diese Einschränkung dort nicht nötig.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement3.png|width=600|caption=SelectStatement3}}

Um diverse Berechnungen anzustellen werden, wird die Ergebnismenge in eine zweite temporäre Tabelle überführt: <code>select ... into temp tmp_ergebnis2</code>. Die erste temporäre Ergebnistabelle wird gelöscht: <code>drop table tmp_ergebnis;</code>.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=SelectStatement4.png|width=600|caption=SelectStatement4}}

Der letzte Select greift auf die zweite temporäre Tabelle zu und enthält die Ergebnistabelle.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=Spaltenlayout.png|width=600|caption=Spaltenlayout}}

Im Feld 'Spaltenlayout' wird das Layout der Spalten der Ergebnistabelle festgelegt. Der markierte Bereich definiert das Layout der ersten Spalte. Spaltenüberschriften sind von 0 aufsteigend durchnummeriert, und die Überschriften selbst können durch "\n" mit Zeilenumbrüchen versehen werden. Pro Überschrift wird ein Absatz formuliert, u.a. auch die Breite der Spalte. Dabei ist zu beachten, dass die Darstellung in HTML vom verwandten Browser abhängt. 'Width' beispielsweise hat auf die HTML-Darstellung keinen Einfluss.
</blockquote>

<blockquote>
{{ImagePara |imgsrc=CleanupStatements.png|width=600|caption=CleanupStatements}}

Wichtig ist außerdem, dass die zweite temporäre Tabelle gelöscht wird. Dies geschieht durch ein kurzes SQL-Statement in 'Cleanup Statements'.
</blockquote>

==Masken erstellen aus Kopien==

Zur Maskenerstellung werden Kopien bereits existierender Masken erstellt. Es ist ratsam Masken zu kopieren, welche der neu zu erstellenden Masken thematisch ähneln. Das bringt den Vorteil, dass diverse Felder der Kopie weiterverwendet werden können. Unter {{Pfad3|Administration|Masken verwalten|Maske kopieren}} findet sich die entsprechende Maske.

<blockquote>
Es wird zunächst die zu kopierende Maske gewählt und anschließend eine tid und ein Name, sowie eine Erläuterung für die neue Maske vergeben. Nach Patch 2022-01-28 kann wahlweise die neue Maske direkt als Makro erstellt werden.

{{ImagePara |imgsrc=Maske_kopieren_1.png|width=600|caption=Auswahlmaske Maske kopieren}}

Bei diesem Beispiel würde die Maske "Studierende nach Alter" kopiert und eine neue Masken "Studierende nach Geschlecht" mit der tid 15980 erstellt.
</blockquote>

{{Achtung|Bei der Vergabe der neuen tid unbedingt darauf achten, dass diese nicht bereits belegt ist.}}

Bei der Vergabe der neuen tid wird mindestens in Dreißigerintervallen vorgegangen, damit für die Felder der Masken ausreichend tids verfügbar sind.

<blockquote>
Um die belegten Masken-tid zu ermitteln eignet sich {{Pfad3|Administration|Masken verwalten|Maske suchen}}, da dort beim Feld Maske die Masken nach tids aufsteigend sortiert sind.

{{ImagePara |imgsrc=Masken_tids.png|width=600|caption=Auswahlmaske Maske suchen}}
</blockquote>

Die Feld-tids werden beginnend ab der Masken-tid direkt aufeinanderfolgend vergeben. Ein Dreißigerintervall zwischen den Masken-tids ermöglicht es somit dreißig Felder pro Maske zu vergeben. Trotzdem sollte immer geprüft werden, ob die vorherige Maske gegebenenfalls mehr als dreißig Felder besitzt und entsprechend ein größeres Intervall zu wählen ist. Hierfür eignet sich {{Pfad4|Administration|Masken verwalten|Felder|Feld suchen}}

<blockquote>
{{ImagePara |imgsrc=Feld_suchen_1.png|width=600|caption=Auswahlmaske Felder suchen}}

{{ImagePara |imgsrc=Feld_suchen_2.png|width=400|caption=Ergebnistabelle Felder suchen}}

Die Maske "16340-Studierende nach Alter" besitzt 17 Felder. Ein Dreißigerintervall wäre somit ausreichend.
</blockquote>

==Masken oder Felder löschen==

Masken und Felder werden über {{Pfad4|Administration|Masken verwalten|Felder|Feld löschen}} und {{Pfad3|Administration|Masken verwalten|Maske löschen}} gelöscht. Dies hat den Vorteil, dass anhand der entsprechenden tid die Einträge für diese Maske oder dieses Feld aus sämtlichen Tabellen gelöscht wird. Falls die Einträge für ein Feld oder eine Maske nur in den Tabellen maskeninfo und felderinfo gelöscht würden, wären beispielsweise in der Feldverwaltung leere Felder zu finden. Um den Datenbestand sauber zu halten wird daher empfohlen, die angesprochenen Formulare "Feld löschen" und "Maske löschen" zu nutzen.

==Konventionen==

Für die Erstellung von SQL-Abfragen gibt es ein paar wichtige Konventionen:
* wenn Sie Abfragen schreiben, sollten Sie temporäre Tabellen immer mit "tmp_" vorab benennen. Grund: es könnte mal sein, dass wir die Tabelle auch als statische Tabelle nutzen. Dann gibt es einen SQL-Fehler.
* vermeiden Sie bei temporären Tabellen Umlaute in Spaltennamen (z.B. "Fakultät"). Das klappt zwar unter Informix, aber nicht unter Postgres.
* Nutzen Sie, wenn möglich, die ANSI-SQL-Standards.

=Abfragenentwurf mit SuperX-Sichten=

<blockquote>
In SuperX können bei Auswahldialogen verschiedene Sichten angeboten werden (vgl. [[SuperX-Benutzungshandbuch_Basics#Alternative_Hierarchien_zur_Datenselektion|Alternative Hierarchien zur Datenselektion]]). Alternative Hierarchien bzw. Auswertungshierarchien aus COB werden automatisiert übernommen. Jede Hierarchie bekommt einen Eintrag in der Sichtentabelle.

<div id="SichtenAuswahl">{{ImagePara |imgsrc=SichtenAuswahl.png|width=600|caption=SichtenAuswahl}}</div>

{{Achtung|Die Inhalte und Rechte der Sichten werden gecached. Nach einer Änderung der Inhalte einer Sicht im laufenden Betrieb musst man im SuperXManager den Cache leeren und sich neu anmelden.}}Die Sichten werden in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten 'sichten'] definiert. Eine Übersicht über die Tabellenstruktur inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten hier].
</blockquote>

<blockquote>
Die Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten sichten] lässt sich wie auch die Masken und Felder (s. Abschnitt [[Masken-Tutorial#Maskendefinition|Maskendefinition]] und [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) in SuperX über ein Bearbeitungsformular manipulieren.

{{ImagePara |imgsrc=SichtSuchen.png|width=600|caption=SichtSuchen}}

Im Folgenden wird die Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" näher betrachtet.

{{ImagePara |imgsrc=SichtFachAbschluss.png|width=600|caption=SichtFachAbschluss}}

</blockquote>

{{Achtung|Das Feld {{Feld|quelle}} in der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_sichten sichten] ist auf 255 Zeichen begrenzt. Falls mehr Zeichen benötigt werden, kann in den Feldern {{Feld|cacheapplet}} und {{Feld|cachexml}} der SQL fortgeführt werden. Die beiden genannten Felder waren historisch für andere Zwecke geplant, werden für diese aber nicht mehr benötigt.}}

<blockquote>
Bei <code>sos_org_lehre_fach_absch_ude</code> handelt es sich um eine "View". Diese "View" beinhaltet mehrere Select-Statements, welche quasi die verschiedenen Ebenen der Sicht "FB/Fak, Lehreinheit, Fach/Abschluss" darstellen.

{{ImagePara |imgsrc=ViewFachAbschUDE.png|width=600|caption=ViewFachAbschUDE}}

Das Organigramm stellt eine integrierende Sicht für verschiedene Datenquellen zusammen und ist somit die Voraussetzung für eine integrierte Betrachtung. Alle Einrichtungen, Institutionen und Projekte sind im Organigramm hierarchisch angeordnet (vgl. [https://super-ics.de/superx/doku/kern_modul/admin/f_DasOrganigramm.htm Das Organigramm]). Das Feld 'lehre' wird entweder mit 1 oder 0 gefüllt, um festzustellen ob die Institution relevant für Auswertungen im Bereich Lehre ist (1=ja, 0=nein).

Erläuterung des parent-Felds:Das Parent-Feld gibt die key_apnr der übergeordneten organisatorischen Einheit an. Das root-Element des Baums besitzt als parent einen null-Wert. Das Organigramm darf demenstprechend nur ein Element haben, dass keinen parent besitzt. Hier sollte grundsätzlich die Hochschulnummer eingetragen werden die auch in anderen HIS-Programmen verwendet wird. In Duisburg ist dies z.B. der Basiseintrag key_apnr = "70" ( GMU Duisburg ). Es ist praktisch der oberste "Knoten" im Baum. Dann werden alle Einträge in der Tabelle organigramm gesucht, die parent="70" haben – also direkte Kinder des Basiseintrags.Hier findet sich u.a. Einrichtungen Forschung und Lehre (key_apnr="7", parent="70"). Dieser Eintrag hat wiederum u.a. folgende Kinder:
*Fakultät 1 (key_apnr="1100", parent="7")
*Fakultät 2 (key_apnr="1200", parent="7")
*Faktultät 3 (key_apnr="1300", parent="7")
usw.

Die weiteren Äste des Baums werden rekursiv abgefragt. Die Struktur der Tabelle [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm 'organigramm'] inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_organigramm hier]. Die Tabelle [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang 'dim_studiengang'] enthält Datensätze zu Studiengängen (Die Struktur der Tabelle inklusive Beschreibung findet sich [https://super-ics.de/superx/doku/sos_modul/sos.html#tab_dim_studiengang hier]).
</blockquote>

<blockquote>
Für alle Sichten wird erwartet, dass mindestens die drei Felder name, key und parent geliefert werden (der konkrete Name der Spalten ist irrelevant).
Anschließend können optional noch Strukturinformationen folgen (entweder Integer oder String).Beispiel:<code>sp_fin_inst_hier(<<UserID>>,<<Stand>>,<<Sicht>>);select name,key,parent,strukturint from tmp_hier order by name; drop table tmp_hier;</code>strukturint (gefüllt aus fin_inst.orgstruktur) gibt mit Zahlen an, ob ein Eintrag eine Lehreinheit oder ein Fachbereich ist.Auf diese Information kann später in Abfragen mit FreeMarker zugegriffen werden.Beispiel:
{{ImagePara |imgsrc=FreemarkerStrukturInt.png|width=500|caption=FreemarkerStrukturInt}}
</blockquote>

==Einträge verstecken oder nicht-selektierbar machen==

<blockquote>
Es kann gewünscht sein, dass Einträge versteckt hinterlegt werden. Betrachtet sei weiterhin die Sicht [[#SichtenAuswahl|'FB/Fak, Lehreinheit, Fach/Abschluss']]. Die unterste sichtbare Ebene ist Fach/Abschluss. Man könnte also annehmen, es würde genügen, diese Sicht bis zur Ebene Fach/Abschluss aufzubauen. Dem ist allerdings nicht so. Es benötigt eine weitere, darunterliegende, aber nicht sichtbare Ebene "Studiengang".

<div id="ViewFachAbschUDESichtbarUnsichtbar">{{ImagePara |imgsrc=ViewFachAbschUDESichtbarUnsichtbar.png|width=600|caption=ViewFachAbschUDESichtbarUnsichtbar}}</div>
</blockquote>

<blockquote>
Zum Verständnis ein Beispiel anhand der Auswertung "Studierende nach Alter". Zunächst wird eine Kombination "Fach/Abschluss" ausgewählt.

{{ImagePara |imgsrc=AuswahlSichtBWLBA.png|width=400|caption=AuswahlSichtBWLBA}}
</blockquote>

<blockquote>
Es erscheint folgende Ergebnistabelle:

{{ImagePara |imgsrc=ErgebnistabelleStudierendeNachAlter.png|width=600|caption=ErgebnistabelleStudierendeNachAlter}}
</blockquote>

<blockquote>
Im SQL erfolgt die Einschränkung auf den im Sichtenbaum ausgewählten Eintrag durch <code>where ... 's_' || L.tid in <@printkeys Studiengang.allNeededKeysList/> ... </code>. Für unser Beispiel sieht diese Passage nach der Freemarker-Transformation folgendermaßen aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS','s_3','s_36','s_33','s_65','s_270','s_87') ...</code>. Würde die unterste, unsichtbare Ebene 'Studiengang' entfallen (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']]), sähe der SQL stattdessen so aus: <code>where ... 's_' || L.tid in ('_LE-WI_021_BS') ...</code>. Das hätte zur Folge, dass keine Einträge gefunden würden, denn es wird nach dem Muster 's_tid' gesucht.

Um eine Ebene unsichtbar zu machen benötigt es das Attribut 'nodeattrib'. Wird diesem der Wert 1 übergeben, so ist die Ebene unsichtbar. Mit dem Wert 0 bleibt die Ebene sichtbar (s. View [[#ViewFachAbschUDESichtbarUnsichtbar|'sos_org_lehre_fach_absch_ude']], Zeile 21 und 30).

</blockquote>

<blockquote>
Weiterhin kann es gewünscht sein, dass man in einer Sicht nur spezielle Einträge auswählen kann. So können man eine Lehreinheitsauswahl vielleicht so darstellen:

Uni XY
* Fak 1
** Lehreinheit A
** Lehreinheit B
* Fak 2
** Lehreinheit C
** Lehreinheit D

Die Kategorisierung Fak 1/2 dient der Klarheit der Darstellung, für eine Abfrage soll aber vielleicht nur eine konkrete Lehreinheit auswählbar sein. In dem Fall kann wie oben das nodeattrib 2 vergeben werden. Dadurch wird ein Eintrag als nicht-selektierbar markiert.
</blockquote>

==User-/Gruppenrechte==

<blockquote>
Außer Administratoren dürfen normale User zunächst einmal keine der nicht-internen Sichten benutzen.In den Tabellen user_sichten und user_sichtarten kann hinterlegt werden, dass ein User eine einzelne Sicht (z.B. name_intern Kostenstellen-Hauptsicht) oder eine ganze Sichtart (z.B. Kostenarten) benutzen darf.Für Gruppen gibt es analog die Tabellen group_sichten und group_sichtarten.Außerdem sachgeb_sichten und sachgeb_sichtarten, wenn Leute die ganze Sachgebiete sehen dürfen auch Sicht sehen sollen.Die Pflege dieser Tabellen kann bequem über Administrationsformular im XML-Frontend vorgenommen werden.<blockquote> Achtung:Nach Änderungen muss der Server-Cache aktualisiert werden und der User muss sich neu anmelden. Alternativ könnte auch Tomcat neu gestartet werden. </blockquote>Im Dateisystem unter $SUPERX_DIR/db/bin gibt es zwei Skripte userrechte_sichern.x und userrechte_einspielen.x.Die entladen alle usertabellen (userinfo,groupinfo,user_sachgeb_bez etc) und spielen sie wieder ein.Diese können z.B. dafür benutzt werden um alle Einstellungen von Test auf Echtrechner zu übernehmen.
</blockquote>

==Benutzen der Sichten in Masken==

<blockquote>
In [https://super-ics.de/superx/doku/kern_modul/kern.html#tab_felderinfo 'felderinfo'] (s. [[Masken-Tutorial#Speichern_der_Felddefinition|Speichern der Felddefinition]]) muss als Art 12-Sicht eingetragen werden.Im Feld Relation muss ein Select stehen, der die 'tids' der gewünschten Sichten zurückliefert.

{{ImagePara |imgsrc=FeldBearbeitenArtSicht.png|width=600|caption=FeldBearbeitenArtSicht}}

<blockquote>Die aktiv-Einschränkung ist praktisch für Entwicklungs- und Wartungszwecke, weil man dann leicht einzelne Sichten de/aktivieren kann - Sortierung nach type, damit erst Hauptsichten und dann alternative Hierarchien angezeigt werden, dann nach Name.</blockquote>Der select sollte alle Sichtentids liefern, die ein Adminstrator sehen darf.Wenn ein User für einzelne Sichten keine Berechtigung hat, filtert der Server diese automatisch raus.
</blockquote>