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

2026-09-16T09:28:02Z

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

Neue Seite

=Sonderladeroutinen in SuperX=

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

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

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

==Aufbau der Definitionsdatei==

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

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

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

Darunter beginnt das erste Makro, beispielsweise:

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

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

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

Am Ende der Datei wird die Verarbeitung mit

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

gestartet.

==ETL-Job==

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

Beispiel:

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

Die wichtigsten Angaben sind:

===uniquename===

Technisch eindeutiger Name des Jobs.

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

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

enden.

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

Beispiel:

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

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

===name===

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

===systeminfo_id===

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

Für das Kernmodul ist dies beispielsweise:

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

===logfile===

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

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

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

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

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

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

erzeugt.

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

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

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

==Datenbankverbindungen==

Bei einer Sonderladeroutine können unterschiedliche Datenbankverbindungen verwendet werden.

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

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

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

Verwendet wird der in SuperX konfigurierte Name der Datenbankverbindung.

Die Datenbankverbindungen werden in

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

konfiguriert.

Dort kann beispielsweise eine Verbindung unter dem Namen

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

definiert sein.

Dieser Name wird dann auch in der Sonderladeroutine verwendet:

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

oder bei einem LOAD-Schritt:

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

Der physische Datenbankname kann davon abweichen.

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

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

==ETL-Jobparameter==

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

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

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

Ein Parameter besitzt drei wesentliche Angaben:

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

Beispiel:

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

Dabei bedeutet:

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

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

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

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

Weitere denkbare Parameter wären beispielsweise:

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

mit Defaultwerten wie:

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

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

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

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

==ETL-Schritte==

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

Beispiel:

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

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

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

Die wichtigsten Angaben sind:

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

;uniquename
:Technisch eindeutiger Name des ETL-Schrittes.

;name
:Bezeichnung des Schrittes.

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

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

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

==Verfügbare Step-Typen==

Das Template unterstützt folgende Step-Typen:

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

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

==Step-Properties==

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

Der allgemeine Aufbau lautet:

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

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

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

==UNLOAD==

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

Beispiel:

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

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

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

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

Wichtige Properties:

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

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

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

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

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

==DOQUERY==

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

Beispiel:

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

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

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

Wichtige Properties:

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

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

;sql
:Auszuführender SQL-Befehl.

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

;sourceVersions
:Optionale Einschränkung nach Quellversionen.

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

==LOAD==

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

Beispiel:

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

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

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

Wichtige Properties:

;database
:Datenbankverbindung der Zieltabelle.

;unlFilePath
:Pfad der einzulesenden Datei.

;tableName
:Zieltabelle.

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

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

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

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

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

==DOSQL==

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

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

Beispiel:

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

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

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

Wichtige Properties sind:

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

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

==Unterschiedliche Datenbank-Properties==

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

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

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

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

==Automatische Standardwerte==

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

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

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

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

Beispielsweise bei <code>LOAD</code>:

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

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

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

Damit können einfache Sonderladeroutinen relativ kompakt definiert werden.

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

==Pfade==

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

Beispiele:

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

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

==SQL innerhalb von prop_value==

SQL-Anweisungen werden innerhalb eines FreeMarker-Strings definiert.

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

Statt:

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

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

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

Beispiel:

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

==Testfälle==

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

Wenn keine Tests benötigt werden:

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

Ein Testfall besteht aus:

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

;testcase
:Name des Testfalls.

;assertion
:Erwarteter Wert.

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

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

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

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

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

==Bereich unterhalb der Definitionen==

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

Ab dem ersten

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

sollte die Datei nicht mehr bearbeitet werden.

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

==Einspielen der Sonderladeroutine==

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

Beispiel:

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

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

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

==Demo-Sonderladeroutine==

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

Die Demo-Datei befindet sich im Git-Repository:

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

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

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

Der erste Step entlädt einen einfachen Datensatz:

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

Das Ergebnis wird in eine UNL-Datei geschrieben.

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

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

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

Der Ablauf ist damit:

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

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

==Hinweise==

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

Kernmodul Sonderladeroutinen - Versionsgeschichte