Zuletzt bearbeitet vor 2 Tagen
von Andre Knieschewski

Kernmodul Sonderladeroutinen

Version vom 16. September 2026, 09:28 Uhr von Andre Knieschewski (Diskussion | Beiträge) (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…“)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

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: 

etl_jobs
etl_job_params
etl_steps
etl_step_properties
testfaelle

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

Darunter beginnt das erste Makro, beispielsweise: 

<#macro etl_steps_def_check>

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 

<@ETL_STEPS_FUELLEN/>

gestartet.

ETL-Job

In etl_jobs wird der eigentliche Ladejob definiert.

Beispiel: 

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

Die wichtigsten Angaben sind:

uniquename

Technisch eindeutiger Name des Jobs.

Bei einer Sonderladeroutine muss der uniquename auf 

_special

enden.

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

Beispiel: 

kern_special_demo_special

Die Namen der einzelnen ETL-Schritte müssen dagegen nicht auf _special 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: 

9

logfile

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

"logfile":""

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

webapps/superx/WEB-INF/logs/jobs/

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

JOBNAME.log

erzeugt.

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

webapps/superx/WEB-INF/logs/jobs/kern_special_demo_special.log

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: 

datasource
dataSource
database
sqlVarSource
sqlVarDataSource

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 

webapps/superx/WEB-INF/conf/his1_databases.properties

konfiguriert.

Dort kann beispielsweise eine Verbindung unter dem Namen 

eduetl

definiert sein.

Dieser Name wird dann auch in der Sonderladeroutine verwendet: 

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

oder bei einem LOAD-Schritt: 

{"prop_name":"database",
 "prop_value":"eduetl"}

Der physische Datenbankname kann davon abweichen.

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

Die genaue Konfiguration der Datei his1_databases.properties wird separat beschrieben.

ETL-Jobparameter

Über etl_job_params können Parameter für einen Ladejob definiert werden.

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

<#assign etl_job_params = [
] />

Ein Parameter besitzt drei wesentliche Angaben: 

param_name
name
param_default

Beispiel: 

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

Dabei bedeutet:

etl_job
Der Job, zu dem der Parameter gehört.
param_name
Technischer Name des Parameters, im Beispiel semester.
name
Bezeichnung des Parameters, im Beispiel Semester.
param_default
Defaultwert, der verwendet beziehungsweise bei der Ausführung vorbelegt werden kann, im Beispiel 20262.

Weitere denkbare Parameter wären beispielsweise: 

startdatum
dateiname
nur_pruefen

mit Defaultwerten wie: 

2026-01-01
daten.unl
false

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 etl_steps definiert.

Beispiel: 

<#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":""}
] />

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 etl_steps bestimmt die Ausführungsreihenfolge.

Verfügbare Step-Typen

Das Template unterstützt folgende Step-Typen:

Typ Funktion
UNLOAD Ergebnis einer SQL-Abfrage in eine Datei schreiben
LOAD Datei in eine Datenbanktabelle laden
DOQUERY SQL-Befehl direkt ausführen
DOSQL SQL-Skriptdatei ausführen
MSG Ausgabe beziehungsweise Nachricht innerhalb der Verarbeitung

Für typische Sonderladeroutinen werden insbesondere UNLOAD, LOAD, DOQUERY und DOSQL verwendet.

Step-Properties

Die Eigenschaften der einzelnen ETL-Schritte werden über etl_step_properties definiert.

Der allgemeine Aufbau lautet: 

{"etl_step":"NAME_DES_SCHRITTES",
 "prop_name":"PROPERTY",
 "prop_value":"WERT"}

etl_step verweist dabei auf den uniquename eines zuvor definierten ETL-Schrittes.

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

UNLOAD

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

Beispiel: 

{"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"}

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 datasource 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 DOQUERY kann ein SQL-Befehl direkt ausgeführt werden.

Beispiel: 

{"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))"}

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 postgres.
sourceVersions
Optionale Einschränkung nach Quellversionen.

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

LOAD

Mit LOAD wird eine Datei in eine Datenbanktabelle geladen.

Beispiel: 

{"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"}

Wichtige Properties:

database
Datenbankverbindung der Zieltabelle.
unlFilePath
Pfad der einzulesenden Datei.
tableName
Zieltabelle.
delimiter
Feldtrenner. Standard ist ^.
header
Gibt an, ob die Datei eine Kopfzeile enthält. Standard ist false.
refresh
Legt fest, ob die Tabelle vor dem Laden geleert wird. Standard ist true.
usePostgresCopyApi
Verwendet bei PostgreSQL die COPY-basierte Ladefunktion. Standard ist true.

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

DOSQL

Mit DOSQL wird eine vorhandene SQL-Skriptdatei ausgeführt.

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

Beispiel: 

{"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"}

Wichtige Properties sind: 

sqlScriptPath
dataSource
sqlVarDataSource
databaseSystem
limitDebugStmts

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

Unterschiedliche Datenbank-Properties

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

Step-Typ Datenbank-Property
UNLOAD datasource
DOQUERY dataSource
DOSQL dataSource
LOAD database

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

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

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: 

systemInfoId
active = true
custom = true

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

Beispielsweise bei LOAD: 

database           = eduetl
delimiter          = ^
header             = false
refresh            = true
usePostgresCopyApi = true

Bei DOQUERY werden unter anderem verwendet: 

databaseSystem   = postgres
dataSource       = eduetl
sqlVarDataSource = eduetl

Damit können einfache Sonderladeroutinen relativ kompakt definiert werden.

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

Pfade

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

Beispiele: 

$KERN_LOAD_PFAD/unl/datei.unl
$SVA_LOAD_PFAD/unl/datei.unl
$SVA_PFAD/schluesseltabellen/script.sql

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: 

select 1, 'Demo'

wird innerhalb von prop_value geschrieben: 

select 1, ''Demo''

Beispiel: 

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

Testfälle

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

Wenn keine Tests benötigt werden: 

<#assign testfaelle = [
] />

Ein Testfall besteht aus: 

testcase
assertion
sql
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: 

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

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 

<#macro ...>

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 DOSQL eingespielt.

Beispiel: 

DOSQL kern_sonderladeroutine_demo.sql

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 uniquename auf _special endet.

Demo-Sonderladeroutine

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

Die Demo-Datei befindet sich im Git-Repository: 

BI_Maintenance

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: 

select 1 as id, 'Demo' as name;

Das Ergebnis wird in eine UNL-Datei geschrieben.

Anschließend erzeugt ein DOQUERY-Step eine kleine Zieltabelle: 

create table if not exists tmp_kern_special_demo
(
    id integer,
    name varchar(20)
);

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

Der Ablauf ist damit: 

Datenbank
  ↓
UNLOAD
  ↓
UNL-Datei
  ↓
LOAD
  ↓
Zieltabelle

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 uniquename des ETL-Jobs muss auf _special enden.
  • Für Datenbanken den in his1_databases.properties 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 prop_value einfache Hochkommata verdoppeln.
  • Bei LOAD darauf achten, dass Aufbau der Datei und Aufbau der Zieltabelle zusammenpassen.
  • Für kurze SQL-Befehle eignet sich DOQUERY, für umfangreichere vorhandene SQL-Dateien DOSQL.
  • Bei Problemen das Jobprotokoll unter WEB-INF/logs/jobs/JOBNAME.log prüfen.
Abgerufen von „https://superxhosting.de/wiki/index.php?title=Kernmodul_Sonderladeroutinen&oldid=16619“