Eigene Laderoutinen sind öfter gewünscht, wenn bestimmte Daten von den bisherigen Modulen (noch) nicht übernommen werden.
Als Beispiele könnten sein
Dabei geht es darum, die Daten zunächst aus dem Quellsystem zu entladen (CSV), sie dann in SuperX/BI einzuspielen und ggfs. noch zu transformieren.
Folgende Lade-Techniken sind möglich:
Die Technische Universität Hamburg (TUHH) erfasst die Mathematiknoten, welche Bewerber auf ihrem bisherigen Bildungsweg erreichten. Diese Mathematiknoten sollen zukünftig in Auswertungen einbezogen werden.
Das Ziel der Laderoutine ist das Befüllen einer neuen Tabelle mit Bewerbernummer und Mathematiknote. Diese neue Tabelle wird über das Feld 'Weitere Tabellen' im "Bewerbungen und Zulassungen Datenblatt" erreichbar sein. Ggf. ist noch ein Zeitraum anzugeben. Tabellenstruktur:
Entladen der Tabelle application_content, im Ergebnis eine CSV Datei
Hochladen mit Kettle oder Shellscript in _neu-Tabelle
Aus der _neu-Tabelle in die finale Tabelle schreiben, ggf. noch Tranformation, z.B. von Noten-Punkten zur Note Dezimal (z.B. 11="gut")
Nächtliches Laden mit Shellscript oder Kettle
Im ETL-Modul gibt es die Möglichkeit, eigene Sonderladeroutinen zu entwerfen. Diese können dann auch in der HISinOne-BI ab Version 2024.12 in der neuen Komponentenverwaltung genutzt werden.
Voraussetzung dafür ist, dass das ETL-Modul aus dem Downloadbereich installiert ist.
Eine Laderoutine kann Entladeschritte, Ladeschritte und Transformationsschritte (SQL) enthalten.
Die Installation einer Sonderladeroutine läuft über ein komplexes Script, dass mit Freemarker-Variablen gefüllt wird und dann später zu reinem SQL transformiert wird, der die Installation ausführt.
Kontrollieren Sie, ob die BI-Tabelle etl_step_type mit fünf Datensätzen gefüllt ist.
Falls diese bei Ihnen leer ist, fügen Sie folgende Step-Types ein
Um fertigen SQL zu generieren muss in der verwendeten Datenbank in der Tabelle fm_templates die ETL_MAKRO aus mind. ETL-Modul 0.5 installiert sein. Damit ist nur die Generierung von Installations-SQL gemeint, zur Verwendung der Steps ist dies nicht nötig.
Ausgangspunkt ist die Definition einer (oder mehrerer) Sonderladeroutinen.
Als uniquename muss eine eindeutige Kennung gewählt werden, die auf "special" endet und bei systeminfo, die ID zu welchem Teilbereich (wie Finanzen,Personal oder Studierende) entsprechend der Tabelle systeminfo die Sonderladeroutine gehört und unter deren Hauptkonnektor sie erscheinen soll. etl_job_params können leer bleiben.
In einem einfachen Fall will man bestimmte Zusatzfelder entladen. Dazu legt man zwei ETL-Steps an.
Das Attribut "etl_job" verweist auf den ETL-JOB ("fin_inst_special") zu dem die Steps gehören sollen.
Dann gibt man ihnen einen uniquename, einen Namen und einen Typ
Folgende Parameter müssen für einen UNLOAD-Step hinterlegt werden datasource,sql und unlFile.
Das attribut "datasource" gibt die Quelldatenbankverbindung in HisInOne an. (hier im Beispiel mbs).
Im Script darf es für alle step_properties nur eine Definition mit <#assign etl_step_properties= .. geben, weitere StepProperties müssen in dieser Aufzählung ergänzt werden.
Die folgenden Parameter werden vom Script automatisch mit defaultwerten gefüllt, könnten bei Bedarf aber zusätzlich definiert werden
Folgende Parameter müssen für einen LOAD-Step hinterlegt werden.
Das Attribut "tableName" (hier im Beispiel "fin_inst_plus")gibt die Zieltabelle an, in die vorher entladenen Daten eingespielt werden sollen.
Im Script darf es für alle step_properties nur eine Definition mit <#assign etl_step_properties= .. geben, weitere StepProperties müssen in dieser Aufzählung ergänzt werden.
Die folgenden Parameter werden vom Script automatisch mit defaultwerten gefüllt, könnten bei Bedarf aber zusätzlich definiert werden, insbesondere header true könnte interessant sein.
Einen DOSQL-Step, der eine SQL-Datei ausführt legt man folgendermaßen an:
Innerhalb der etl_steps Definition mach man einen Eintrag mit dem etl_job und einem eindeutigen uniquename, der später die SQL-Datei referenziert, Typ ist "DOSQL".
Innerhalb der etl_step_properties muss für den DOSQL-Step der folgende Eintrag definiert werden
Hinweis:
Es sollte nicht mit SUPERX_DIR gearbeitet werden, denn bei Ausführung im Browser funktioniert das, per Shellscript ist es aber anders definiert.
Einen DOQUERY-Step, der einen einzelnen SQL-Befehli ausführt legt man folgendermaßen an:
Innerhalb der etl_steps Definition mach man einen Eintrag mit dem etl_job und einem eindeutigen uniquename, der später die SQL-Datei referenziert, Typ ist "DOQUERY".
Innerhalb der etl_step_properties müssen für den DOSQL-Step der folgende Eintrag definiert werden
Die folgenden Parameter werden vom Script automatisch mit defaultwerten gefüllt, könnten bei Bedarf aber zusätzlich definiert werden
wird von HisInOne 2024.12 noch nicht unterstützt
Für Ausführung per HisInOne SHellscript muss ein Job das Attribut custom_job = 1 haben (0= HIS Auslieferung, 1= hochschulspezfisch,2 Memtext AUslieferung)
Das Makro ETL erzeugt derzeit 2 Memtext Auslieferung, also für Ausführung per Shellscript noch nachbearbeiten:
UPDATE etl_job SET custom_job = 1 WHERE uniquename='fin_inst_proj_special';
Allgemeine Hinweise zum Ausführen von Laderoutinen per Script finden sich im HisWiki.
Kopieren Sie unter webapps/superx/scripts/shell die Datei component_admin_cli.sh.sam nach component_admin_cli.sh und passen darin die Variable SUPERX_DIR gemäß Ihrer Installation an.
Dann geben Sie der Datei Ausführungsrechte.
Eine Sonderladeroutine kann man ausführen mit
component_admin_cli.sh -e UNIQUENAME
z.B.
component_admin_cli.sh -e fin_inst_proj_special
Es erscheinen eine Menge Logausgaben wie
2025-06-17 09:31:00,558 [main] INFO org.springframework.batch.core.launch.support.SimpleJobLauncher - No TaskExecutor has been set, defaulting to synchronous executor.
2025-06-17 09:31:00,613 [main] WARN org.springframework.data.convert.CustomConversions - Registering converter from class java.lang.Boolean to class org.springframework.data.jdbc.core.convert.JdbcValue as writing converter although it doesn't convert to a store-supported type! You might want to check your annotation setup at the converter implementation.
2025-06-17 09:31:01,098 [main] WARN org.springframework.batch.core.configuration.annotation.DefaultBatchConfigurer - No transaction manager was provided, using a DataSourceTransactionManager
2025-06-17 09:31:01,111 [main] INFO org.springframework.batch.core.repository.support.JobRepositoryFactoryBean - No database type set, using meta data indicating: POSTGRES
2025-06-17 09:29:41,741 [main] INFO de.superx.rest.EtlJobApi - Job not registered yet: Zusatzfelder Inst und Proj aus MBS übertragen
2
Die hier aufgeführten WARN Meldungen kann man ignorieren.Andererseits sind Meldungen, die sich konkret auf den Job beziehen wichtig. Im folgenden Beispiel wird ein Script nicht gefunden
2025-06-17 09:31:02,641 [main] WARN de.superx.spring.service.BatchJobDescriptionAdapter - SQL Skriptfile doesn't exist: $FIN_PFAD/potsdam/7950_update_fin_zusatzmerkmale.sql
oder hier ein allgemeiner ERROR-Meldung
2025-06-17 09:37:16,188 [main] ERROR de.superx.bin.ComponentAdminCLI - ERROR executing job fin_inst_proj_special
Der Exitstatus des Script scheint in HisInOne2024.12 auch bei Fehlern noch teilweise 0 zurückzuliefern.
Man sollte also auf etwaige Fehler ggfs. manuell die Logdateien prüfen.
Diese liegt unter webapps/superx/WEB-INF/logs/jobs/JOBNAME.log
Cannot invoke "javax.sql.DataSource.unwrap(java.lang.Class)" because the return value of de.superx.spring.batch.reader.JdbcUnloadReader.getDataSource()" is null
bedeutet,dass bei einem UnloadStep als dataSource z.B. "mbs" angegeben wurde, aber in der databases.xml (oder Spezialversion davon) keine Datenquelle "mbs" definiert ist.
ERROR: null value in column "step_type_id" of relation "etl_step" violates not-null constraint
Kontrollieren Sie, ob die Tabelle etl_step_type gefüllt ist (s.o.).
[main] ERROR de.superx.bin.ComponentAdminCLI - ERROR executing job fin_inst_proj_special org.springframework.jdbc.BadSqlGrammarException: PreparedStatementCallback; bad SQL grammar tid, uniquename, caption, systeminfo_id, custom_job FROM etl_job WHERE uniquename like ?; nested exception is org.postgresql.util.PSQLException: Cannot cast to boolean: "2.0"
Für Ausführung per HisInOne SHellscript muss ein Job das Attribut custom_job = 1 haben (0= HIS Auslieferung, 1= hochschulspezfisch,2 Memtext AUslieferung)
Das Makro ETL erzeugt derzeit 2 Memtext Auslieferung, also für Ausführung per Shellscript noch nachbearbeiten:
UPDATE etl_job SET custom_job = 1 WHERE uniquename='fin_inst_proj_special';