Zuletzt bearbeitet vor einem Monat
von Andre Knieschewski

SuperX REST Schnittstelle: Unterschied zwischen den Versionen

Keine Bearbeitungszusammenfassung
Markierung: 2017-Quelltext-Bearbeitung
Zeile 1: Zeile 1:
=REST-Schnittstelle=
=REST-Schnittstelle=


Die REST-Schnittstelle ist die technische Grundlage, um Funktionen von SuperX nicht nur über klassische Skripte, sondern auch über Weboberflächen und externe Anwendungen bereitzustellen. Sie trennt die eigentliche Verarbeitung von der Darstellung im Browser und macht zentrale Funktionen wie Update, Upgrade oder Statusabfragen über standardisierte HTTP-Aufrufe nutzbar.
Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.


==Ziel==
Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.


Das wichtigste Ziel ist eine einfachere und flexiblere Bedienung. Aufgaben, die bisher meist skriptgesteuert auf dem Server ausgeführt wurden, können künftig direkt aus einer Administrationsoberfläche gestartet werden. Dazu gehören zum Beispiel das Aktualisieren von Moduldaten, Modul-Upgrades oder das Anzeigen von Protokollen laufender Jobs.
Zu den wichtigsten Einsatzbereichen gehören:


==Vorteile==
* Komponentenverwaltung und ETL-Jobs
* Status- und Protokollabfragen
* SuperX-Masken und deren Eingabefelder
* Ausführung von Masken und Abruf der Ergebnistabellen
* Export von Berichtsergebnissen
* Einbindung von SuperX-Funktionen in eigene Weboberflächen


*Administrationsaufgaben können über die Weboberfläche ausgeführt werden, ohne direkt auf der Kommandozeile arbeiten zu müssen.
In den folgenden Beispielen wird diese Beispielinstallation verwendet:
*Die vorhandenen ETL- und Batch-Prozesse bleiben erhalten und werden lediglich über eine zusätzliche Schnittstelle erreichbar gemacht.
*Weboberflächen können unabhängig von der eigentlichen Fachlogik gestaltet und weiterentwickelt werden.
*Hochschulen können Funktionen leichter in eigene Portale oder Webseiten einbinden und dabei ihr eigenes Corporate Design verwenden.
*Die Schnittstelle kann neben der Weboberfläche auch von Skripten oder anderen Anwendungen genutzt werden.


==Einsatzbereiche==
<source lang="text">
https://demo.superx-testserver.de/superx/
</source>


Ein erster Einsatzbereich ist die Komponentenverwaltung. Über die REST-Schnittstelle können installierte Module abgefragt, Updates gestartet, Upgrades ausgeführt und Logs angezeigt werden.
Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.


Ein weiterer Einsatzbereich sind zukünftige SuperX-Masken. Wenn Maskendefinitionen, Parameter und Ergebnisdaten über die REST-Schnittstelle bereitgestellt werden, kann die Darstellung stärker entkoppelt werden. Dadurch lassen sich Auswertungen flexibler in unterschiedliche Oberflächen integrieren.


==Grundidee==
==Grundlagen==


Die REST-Schnittstelle ersetzt die vorhandenen Verarbeitungsprozesse nicht. Sie stellt diese Prozesse nur auf einem modernen und einheitlichen Weg bereit. Dadurch können bestehende SuperX-Funktionen schrittweise besser in Weboberflächen, Administrationsseiten und externe Systeme eingebunden werden.
Die REST-Endpunkte befinden sich unterhalb von:


<source lang="text">
https://demo.superx-testserver.de/superx/ds/api/
</source>


==Einrichtung==
Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.


Dieses Kapitel beschreibt die grundlegenden Schritte, damit die REST-Schnittstelle für die Komponentenverwaltung verwendet werden kann. Die Beschreibung verwendet neutrale Platzhalter und kann dadurch auf unterschiedliche Installationen übertragen werden.
Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.


===Verwendete Platzhalter===


Die folgenden Platzhalter werden in den Beispielen verwendet. Sie müssen jeweils durch die konkreten Pfade der Installation ersetzt werden.
==Einrichtung und Voraussetzungen==


{| class="wikitable"
Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.
!Platzhalter!!Bedeutung
|-
|SUPERX_WEBAPP||Verzeichnis der deployten SuperX-Webapp. Dieses Verzeichnis enthält WEB-INF.
|-
|SUPERX_GIT||Lokales Checkout des SuperX-Git-Repositories.
|-
|TOMCAT_WEBAPPS||Webapps-Verzeichnis des verwendeten Tomcat.
|-
|MODUL_VERZEICHNIS||Verzeichnis eines SuperX-Moduls, das in die Komponentenverwaltung eingebunden werden soll.
|}
 
Beispielhafte Definitionen für eine Shell-Sitzung:
 
<source lang="bash">
SUPERX_WEBAPP=/pfad/zur/webapps/superx
SUPERX_GIT=/pfad/zum/superx-git
TOMCAT_WEBAPPS=/pfad/zum/tomcat/webapps
MODUL_VERZEICHNIS=/pfad/zum/modul
</source>


===Voraussetzungen===
Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:


Die REST-Schnittstelle ist Teil der SuperX-Webapp. Die Webapp muss daher grundsätzlich lauffähig sein und über den Tomcat erreichbar sein. Erst wenn die normale SuperX-Anwendung erreichbar ist und die Datenbankverbindung funktioniert, sollten die REST-Endpunkte für die Komponentenverwaltung geprüft werden.
* die SuperX-Webapp ist über Tomcat erreichbar,
* die Datenbankverbindung funktioniert,
* ein aktueller Kernstand ist installiert,
* die benötigten Modulverzeichnisse sind eingebunden,
* die ETL- und Jobdefinitionen wurden eingelesen.


===Aktuelles Kernpaket verwenden===
===Aktuelles Kernpaket verwenden===


Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles SuperX-Kernpaket verwendet werden. Bei älteren Kernständen können REST-Endpunkte, Spring-Batch-Konfigurationen oder benötigte Klassen fehlen.
Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.


Beispiel für den Download eines Kernpakets:
Beispiel:


<source lang="bash">
<source lang="bash">
Zeile 69: Zeile 58:
</source>
</source>


Das Kernpaket wird anschließend in die bestehende Webapp eingespielt. Vorher sollten lokale Anpassungen, kundenspezifische Dateien und projektspezifische Konfigurationen gesichert werden.
Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in <code>WEB-INF/lib</code> liegen bleiben.


===Wichtiger Hinweis zum Kern-Upgrade===
Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.


Bei einem Kern-Upgrade kann es zu Problemen kommen, wenn alte Bibliotheken im Verzeichnis WEB-INF/lib liegen bleiben. Deshalb sollte dieses Verzeichnis vor dem erneuten Entpacken des Kernpakets vollständig geleert werden.
Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden:
 
<source lang="bash">
cd $SUPERX_WEBAPP
rm -f WEB-INF/lib/*
</source>
 
Anschließend wird das neue Kernpaket in die Webapp entpackt. Dadurch ist sichergestellt, dass keine veralteten JAR-Dateien aus einem früheren Kernstand weiterverwendet werden.
 
Nach dem Upgrade sollten die folgenden Konfigurationsdateien geprüft werden, da sie für REST-Schnittstelle, Datenbankverbindung, Batch-Verarbeitung und Scheduler relevant sind:


<source lang="text">
<source lang="text">
SUPERX_WEBAPP/WEB-INF/classes/spring-batch.properties
WEB-INF/classes/spring-batch.properties
SUPERX_WEBAPP/WEB-INF/classes/hikari.properties
WEB-INF/classes/hikari.properties
SUPERX_WEBAPP/WEB-INF/classes/quartz.properties
WEB-INF/classes/quartz.properties
</source>
</source>


===Datenbankverbindung prüfen===
===Datenbankverbindung prüfen===


Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der dbforms-config.xml sollte daher der SpringBeanConnectionProvider verwendet werden. Dieser stellt die Verbindung über die Spring-Konfiguration der Anwendung bereit.
Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der <code>dbforms-config.xml</code> sollte der <code>SpringBeanConnectionProvider</code> verwendet werden:


<source lang="xml">
<source lang="xml">
Zeile 102: Zeile 82:
</source>
</source>


Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar erreichbar sein, aber beim Zugriff auf ETL-Jobs oder Komponenteninformationen fehlschlagen.
Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.


===Pflichtdatei module_ignore.properties===
===module_ignore.properties prüfen===


Die Datei module_ignore.properties muss im Modulverzeichnis der Webapp vorhanden sein. Fehlt diese Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.
Für die Komponentenverwaltung muss folgende Datei vorhanden sein:


<source lang="text">
<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module/module_ignore.properties
WEB-INF/conf/edustore/db/module/module_ignore.properties
</source>Inhalt z.B.:<syntaxhighlight lang="text">
ignore.modules=kennx,gxstage,bil
</syntaxhighlight>
 
===Fehlende Kern-ETL-Dateien ergänzen===
 
Für einige Funktionen der Komponentenverwaltung werden zusätzliche ETL-XML-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen. Falls diese Dateien im installierten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git in die Webapp kopiert werden.
 
Quellverzeichnis im SuperX-Git:
 
<source lang="text">
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>
</source>


Zielverzeichnis in der Webapp:
Beispielinhalt:


<source lang="text">
<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
ignore.modules=kennx,gxstage,bil
</source>
</source>


Benötigte Dateien:
Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.


*edustore_kern_man_unload_config_ids.xml
===Modulverzeichnisse bereitstellen===
*edustore_kern_man_unload_config_pg.xml
*edustore_kern_man_upload_config_ids.xml
*edustore_kern_man_upload_config_pg.xml


Beispiel zum Kopieren:
Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus:


<source lang="bash">
<source lang="text">
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_unload_config_ids.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
WEB-INF/conf/edustore/db/module
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_unload_config_pg.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_upload_config_ids.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_upload_config_pg.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
</source>
</source>


===Modulverzeichnis vorbereiten===
Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.


Die Komponentenverwaltung liest die verfügbaren Komponenten und ETL-Jobs aus dem Modulbereich der Webapp. Deshalb müssen die benötigten Modulverzeichnisse im Verzeichnis WEB-INF/conf/edustore/db/module erreichbar sein.
Beispiel:
 
<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module
</source>
 
Falls ein Modulverzeichnis außerhalb der Webapp gepflegt wird, kann es per symbolischem Link eingebunden werden.


<source lang="bash">
<source lang="bash">
cd $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module
cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
ln -s $MODUL_VERZEICHNIS .
</source>
</source>


Alternativ kann das Modulverzeichnis auch direkt in das Modulverzeichnis der Webapp kopiert werden. Welche Variante verwendet wird, hängt davon ab, ob die Module zentral gepflegt oder projektspezifisch abgelegt werden.
===Zusätzliche Kern-ETL-Dateien prüfen===


===ETL-Steuerdaten neu einlesen===
Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.


Nachdem Kern, Modulverzeichnisse und XML-Dateien vorbereitet wurden, müssen die ETL-Steuerdaten neu eingelesen werden. Das erfolgt über die ComponentAdminCLI. Der Aufruf sollte aus dem Tomcat-Webapps-Verzeichnis erfolgen, damit die relativen Pfade zu WEB-INF/classes, WEB-INF/lib und WEB-INF/lib_ext stimmen.
Quellverzeichnis im SuperX-Git:


<source lang="bash">
<source lang="text">
cd $TOMCAT_WEBAPPS
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" "de.superx.bin.ComponentAdminCLI" -r
</source>
</source>


Der Parameter -r liest die Komponenten- und Jobdefinitionen neu ein. Danach sollten die Jobs in der REST-Schnittstelle sichtbar sein.
Zielverzeichnis in der Webapp:


===Optional: Einzelnen Job über die CLI testen===
<source lang="text">
 
$WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
Nach dem Einlesen kann ein einzelner Job testweise über die CLI gestartet werden. Dadurch lässt sich prüfen, ob die Jobdefinitionen grundsätzlich funktionieren, bevor die REST-Schnittstelle oder die Weboberfläche verwendet wird.
 
<source lang="bash">
cd $TOMCAT_WEBAPPS
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" "de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
</source>
</source>


Wenn dieser Aufruf funktioniert, ist die Batch- und ETL-Konfiguration grundsätzlich verwendbar. Fehler an dieser Stelle deuten meistens auf fehlende Moduldateien, fehlerhafte Pfade, fehlende Datenbanktabellen oder eine unvollständige Konfiguration hin.
Benötigte Dateien:


===Optional: Indexproblem beim Einlesen beheben===
* edustore_kern_man_unload_config_ids.xml
* edustore_kern_man_unload_config_pg.xml
* edustore_kern_man_upload_config_ids.xml
* edustore_kern_man_upload_config_pg.xml


In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps zu Konflikten mit vorhandenen Indizes kommen. Im Testfall wurde folgender Index entfernt:
Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.


<source lang="sql">
===ETL-Steuerdaten einlesen===
drop index ix_etl_step1;
</source>


Dieser Schritt sollte nicht pauschal durchgeführt werden, sondern nur dann, wenn der konkrete Fehler beim Einlesen der ETL-Steps auf diesen Index verweist.
Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.


===Tomcat neu starten===
Beispiel:
 
Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden. Dadurch wird sichergestellt, dass die Webapp alle Klassen und Konfigurationen neu lädt.


<source lang="bash">
<source lang="bash">
systemctl restart tomcat
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
  "de.superx.bin.ComponentAdminCLI" -r
</source>
</source>


Je nach Distribution kann der Dienst auch anders heißen, zum Beispiel tomcat10.
Der Parameter <code>-r</code> liest die Komponenten- und Jobdefinitionen neu ein.


<source lang="bash">
Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden:
systemctl restart tomcat10
</source>
 
===REST-Schnittstelle prüfen===
 
Nach dem Neustart kann geprüft werden, ob die REST-Schnittstelle erreichbar ist. Die folgenden Aufrufe können direkt im Browser oder mit curl getestet werden.
 
Komponentenliste:


<source lang="text">
<source lang="text">
https://<<domain>>/superx/ds/api/etl/list
https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb
</source>
</source>


Jobliste aller bekannten Jobs:
===Einzelnen Job über die CLI testen===


<source lang="text">
Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.
https://<<domain>>/superx/ds/api/etl/job/list
</source>


Jobliste eines einzelnen Moduls:
Beispiel:


<source lang="text">
<source lang="bash">
https://<<domain>>/superx/ds/api/etl/job/list/hrstage
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
  "de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
</source>
</source>


Wenn diese Aufrufe JSON zurückliefern, ist die REST-Schnittstelle grundsätzlich erreichbar. Falls die Aufrufe HTTP 500 liefern, sollten zuerst die Tomcat-Logs, die Datenbankverbindung und das Einlesen der ETL-Steuerdaten geprüft werden.
Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.


===Erster Funktionstest===
===Tomcat neu starten===


Für einen ersten Funktionstest sollte zunächst ein Listenaufruf verwendet werden. Danach kann in einer Testumgebung ein technischer Job gestartet werden.
Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.


Beispiel für einen Transform-Aufruf:
Beispiel:


<source lang="text">
<source lang="bash">
https://<<domain>>/superx/ds/api/etl/transform/hrstage
systemctl restart tomcat10
</source>
</source>


Beispiel für den Start eines konkreten Jobs:
Je nach Installation kann der Dienst auch anders heißen.


<source lang="text">
===REST-Schnittstelle prüfen===
https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform
</source>


Der Startaufruf liefert im Erfolgsfall eine JobExecutionId zurück. Diese ID kann anschließend zur Status- und Logabfrage verwendet werden.
Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden:
 
Statusabfrage:


<source lang="text">
<source lang="text">
https://<<domain>>/superx/ds/api/etl/jobExecutionStatus/{jobExecutionId}
https://demo.superx-testserver.de/superx/ds/api/etl/list
</source>
</source>
Logabfrage:


<source lang="text">
<source lang="text">
https://<<domain>>/superx/ds/api/etl/jobLog/{jobExecutionId}
https://demo.superx-testserver.de/superx/ds/api/etl/job/list
</source>
</source>


===Zusammenfassung der Einrichtung===
Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.
 
Für eine funktionierende REST-Schnittstelle müssen Kernpaket, Webapp-Struktur, Datenbankverbindung, Modulverzeichnis, module_ignore.properties und ETL-Steuerdaten zusammenpassen. Erst wenn die Komponentenliste und die Jobliste über die REST-API korrekt ausgeliefert werden, sollte die Weboberfläche für die Komponentenverwaltung verwendet werden.


 
Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden:
==Funktionsbeschreibung der REST-Schnittstelle==
 
Dieses Kapitel beschreibt die REST-Schnittstelle der SuperX-Komponentenverwaltung aus Entwicklersicht. Es erklärt die wichtigsten Endpunkte, typische Aufrufmuster, Rückgabewerte und Fehlerfälle. Die Schnittstelle wird von der Administrationsoberfläche verwendet, kann aber auch direkt durch eigene Werkzeuge, Skripte oder externe Anwendungen angesprochen werden.
 
===Grundaufbau===
 
Die REST-Endpunkte liegen unterhalb der SuperX-Webapp. In den Beispielen wird der Platzhalter <<domain>> für die jeweilige Serveradresse verwendet.


<source lang="text">
<source lang="text">
https://<<domain>>/superx/ds/api/etl
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>
</source>


Ein vollständiger Aufruf setzt sich aus der Domain, dem SuperX-Kontext, dem REST-Basispfad und dem konkreten Endpunkt zusammen.
===Fehlersuche bei der Einrichtung===


<source lang="text">
Bei Problemen sollten insbesondere folgende Punkte geprüft werden:
https://<<domain>>/superx/ds/api/etl/list
</source>


Die Schnittstelle liefert in der Regel JSON zurück. Startaufrufe liefern häufig eine JobExecutionId zurück, mit der anschließend Status und Log des gestarteten Jobs abgefragt werden können.
{| class="wikitable"
 
!Problem!!Prüfung
===HTTP-Methoden===
|-
 
|REST-Endpunkt liefert HTTP 500
Viele Endpunkte der aktuellen Implementierung sind als GET-Endpunkte umgesetzt, auch wenn sie serverseitig Aktionen auslösen. Dazu gehören beispielsweise Startaufrufe für Jobs, Installationen, Upgrades oder Transform-Läufe. Für Entwickler ist daher wichtig, die tatsächlich vorhandenen Endpunkte der jeweiligen SuperX-Version zu verwenden und nicht nur von klassischen REST-Konventionen auszugehen.
|Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren.
|-
|Komponentenliste ist leer oder fehlerhaft
|Modulverzeichnis und <code>module_ignore.properties</code> prüfen.
|-
|Jobs fehlen
|ETL-Steuerdaten mit <code>ComponentAdminCLI -r</code> oder über <code>/etl/job/writeJobsToDb</code> neu einlesen.
|-
|Job funktioniert über REST nicht
|Denselben Job testweise über die CLI starten und Tomcat-Log prüfen.
|-
|Spezialjobs fehlen
|Zusätzliche ETL-XML-Dateien im Verzeichnis <code>edustore_update</code> prüfen.
|-
|REST-Aufruf funktioniert nach einem Upgrade nicht
|Bibliotheken in <code>WEB-INF/lib</code> sowie <code>spring-batch.properties</code>, <code>hikari.properties</code> und <code>quartz.properties</code> prüfen.
|-
|POST auf eine Maske liefert "Required request body is missing"
|Einen JSON-Body mitsenden, mindestens <code>{}</code>.
|-
|POST liefert "application/octet-stream is not supported"
|Header <code>Content-Type: application/json</code> setzen.
|}


Beispiel für einen aktionsauslösenden GET-Aufruf:
In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.


<source lang="text">
GET https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform
</source>


Falls die Schnittstelle später stärker an klassische REST-Konventionen angepasst wird, können solche Aktionsaufrufe perspektivisch auch als POST-Endpunkte angeboten werden. Für die hier beschriebene Implementierung sind jedoch die vorhandenen GET-Endpunkte maßgeblich.
==Komponentenverwaltung und ETL==


===Komponentenliste===
Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.


Die Komponentenliste liefert die aus SuperX bekannten Komponenten beziehungsweise Module mit technischen Zusatzinformationen. Die Administrationsoberfläche nutzt diesen Aufruf als Einstiegspunkt, um installierte Komponenten, Datenquellen und einfache Statusinformationen anzuzeigen.
Der Basis-Pfad lautet:


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/list
https://demo.superx-testserver.de/superx/ds/api/etl
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/list"
</source>
</source>


Beispielantwort:


<source lang="json">
===Übersicht der wichtigsten ETL-Aufrufe===
[
  {
    "name": "HR Basisdaten",
    "abbreviation": "hrstage",
    "systeminfoId": 180,
    "database": null,
    "lastUpdate": 1782308210481,
    "unload": true,
    "load": true,
    "installed": true,
    "databaseConnected": false,
    "connectors": [],
    "needsUpgrade": false
  }
]
</source>
 
Die wichtigsten Felder sind:


{| class="wikitable"
{| class="wikitable"
!Feld!!Bedeutung
!Funktion
!Methode
!Beispiel
!Zweck
|-
|Komponenten anzeigen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/list</code>
|Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen.
|-
|Installierbare Komponenten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/installables/list</code>
|Zeigt Komponenten, die grundsätzlich installiert werden können.
|-
|-
|name||Sprechender Name der Komponente.
|Alle ETL-Jobs
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/list</code>
|Liefert alle bekannten ETL- und Batch-Jobs.
|-
|-
|abbreviation||Technisches Kürzel der Komponente. Dieses Kürzel wird in vielen weiteren REST-Aufrufen als {component} verwendet.
|Jobs einer Komponente
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/list/hrstage</code>
|Zeigt nur die Jobs einer bestimmten Komponente.
|-
|-
|systeminfoId||Referenz auf die systeminfo-Tabelle.
|Jobdetails
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/hrstage_load_and_transform</code>
|Liefert technische Informationen zu einem bestimmten Job.
|-
|-
|database||Zugeordnete Datenquelle. Wenn keine spezielle Datenquelle vorhanden ist, kann dieser Wert null sein.
|Jobdefinitionen neu einlesen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb</code>
|Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein.
|-
|-
|lastUpdate||Zeitstempel des letzten Updates als numerischer Wert.
|Job starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform</code>
|Startet einen bestimmten Job und liefert eine JobExecutionId zurück.
|-
|-
|unload||Gibt an, ob für die Komponente eine Entladefunktion bekannt ist.
|Installation starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/install/hrstage</code>
|Startet die Installation einer Komponente.
|-
|-
|load||Gibt an, ob für die Komponente eine Lade- beziehungsweise Transform-Funktion bekannt ist.
|Upgrade starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade/hrstage</code>
|Startet ein Upgrade einer installierten Komponente.
|-
|-
|installed||Gibt an, ob die Komponente installiert ist.
|Alle Upgrades starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade_all</code>
|Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten.
|-
|-
|databaseConnected||Gibt an, ob die zugeordnete Datenquelle erreichbar ist.
|Komponente deinstallieren
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/uninstall/hrstage</code>
|Startet die Deinstallation einer Komponente.
|-
|-
|connectors||Liste zusätzlicher Spezialfunktionen oder Connector-Jobs.
|Unload starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/unload/hrstage</code>
|Startet den Unload einer Komponente.
|-
|-
|needsUpgrade||Gibt an, ob für die Komponente ein Upgradebedarf erkannt wurde.
|Transform starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/transform/hrstage</code>
|Startet die Transformation bereits vorhandener Daten.
|-
|Complete starten
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/complete/hrstage</code>
|Startet modulabhängige Abschlussarbeiten.
|-
|Installationsfunktionen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/installFunctions/hrstage</code>
|Zeigt zusätzliche Installationsfunktionen einer Komponente.
|-
|Laufende Jobs
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/running</code>
|Zeigt aktuell laufende Jobs.
|-
|Jobstatus
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionStatus/12345</code>
|Liefert den aktuellen Status einer Jobausführung.
|-
|Joblog
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobLog/12345</code>
|Liefert das Protokoll einer Jobausführung.
|-
|Jobausführungen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionInfos</code>
|Liefert Informationen zu Jobausführungen.
|-
|Job stoppen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/stop/12345</code>
|Stoppt eine bestimmte Jobausführung.
|-
|Job starten oder fortsetzen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/start/12345</code>
|Spricht eine vorhandene Jobausführung erneut an.
|-
|Alle Jobs stoppen
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/etl/job/stopAll</code>
|Stoppt alle laufenden Jobs.
|}
|}


===Installierbare Komponenten===
Über die Liste der installierbaren Komponenten kann ermittelt werden, welche Komponenten grundsätzlich installiert werden können. Dieser Aufruf ist besonders für Oberflächen interessant, die neben installierten Modulen auch noch nicht installierte Module anzeigen möchten.


<source lang="text">
===Typischer ETL-Ablauf===
GET /superx/ds/api/etl/installables/list
</source>


Beispiel:
Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.


<source lang="bash">
Ein typischer Ablauf für ein Modulupdate ist:
curl -s "https://<<domain>>/superx/ds/api/etl/installables/list"
</source>
 
Die genaue Rückgabestruktur kann je nach SuperX-Version und vorhandenen Moduldefinitionen variieren. Entwickler sollten die Antwort daher defensiv auswerten und nicht voraussetzen, dass jedes Feld in jeder Umgebung vorhanden ist.
 
===Jobliste aller Jobs===
 
Die vollständige Jobliste liefert alle bekannten ETL- und Batch-Jobs. Dieser Aufruf eignet sich für Entwicklerwerkzeuge, Debugging und Expertenoberflächen.


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/job/list
1. Komponenten laden
</source>
  /etl/list


Beispiel:
2. Jobs des Moduls laden
  /etl/job/list/hrstage


<source lang="bash">
3. Gewünschten Job starten
curl -s "https://<<domain>>/superx/ds/api/etl/job/list"
  /etl/job/execute/eduetl/hrstage_unload_load_transform
</source>


Beispielantwort:
4. Jobstatus abfragen
  /etl/jobExecutionStatus/12345


<source lang="json">
5. Jobprotokoll anzeigen
[
  /etl/jobLog/12345
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Load And Transform",
    "id": "hrstage_load_and_transform"
  },
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Unload, Load And Transform",
    "id": "hrstage_unload_load_transform"
  },
  {
    "type": "CONTAINER",
    "name": "KERN Konfiguration entladen",
    "id": "kern_unload_config_special"
  }
]
</source>
</source>


Für normale Administrationsoberflächen sollte diese globale Liste nicht ungefiltert angezeigt werden. Sinnvoller ist es, zunächst die Komponentenliste zu laden und anschließend je Komponente die zugehörigen Jobs abzufragen.
Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.


===Jobliste einer Komponente===
Spezialjobs wie beispielsweise
 
Die Jobliste einer einzelnen Komponente ist der wichtigste Aufruf für dynamische Administrationsoberflächen. Sie liefert die tatsächlich vorhandenen technischen Jobs eines Moduls.


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/job/list/{component}
kern_unload_config_special
kern_upload_config_special
</source>
</source>


Beispiel:
können ebenfalls über den generischen Execute-Endpunkt gestartet werden.


<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/list/hrstage"
</source>


Beispielantwort:
==SuperX-Masken und Berichte==


<source lang="json">
Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.
[
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Install/ Upgrade",
    "id": "hrstage_install_upgrade"
  },
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Uninstall",
    "id": "hrstage_uninstall"
  },
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Load And Transform",
    "id": "hrstage_load_and_transform"
  },
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Unload",
    "id": "hrstage_unload"
  },
  {
    "type": "CONTAINER",
    "name": "HRSTAGE Unload, Load And Transform",
    "id": "hrstage_unload_load_transform"
  }
]
</source>


Eine Oberfläche sollte diese Liste verwenden, um technische Aktionen dynamisch zu erzeugen. Dadurch werden nur Jobs angeboten, die im System tatsächlich existieren.
Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.


===Jobdetails===


Ein einzelner Job kann über seine technische Job-ID abgefragt werden. Dieser Aufruf ist vor allem für Entwickler und Diagnosewerkzeuge hilfreich.
===Übersicht der wichtigsten Masken- und Berichtsaufrufe===


<source lang="text">
{| class="wikitable"
GET /superx/ds/api/etl/job/{id}
!Funktion
</source>
!Methode
!Beispiel
!Zweck
|-
|Maskenaufbau laden
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030</code>
|Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften.
|-
|Abhängige Felder aktualisieren
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/form/71030/inputupdate</code>
|Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu.
|-
|Informationen zur Maske
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet.
|-
|Maske ausführen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report?tid=71030</code>
|Führt die Maske aus und liefert die Ergebnistabelle als JSON.
|-
|Ergebnis-Stylesheets
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/stylesheets?tid=71030</code>
|Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets.
|-
|Sichten eines Feldes
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/views?tid=71030&amp;fieldName=Institution</code>
|Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes.
|-
|Inhalt einer Sicht
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/report/view?tid=71030&amp;fieldName=Institution&amp;viewId=...</code>
|Liefert den Inhalt einer bestimmten Sicht.
|-
|Bericht herunterladen
|POST
|<code>https://demo.superx-testserver.de/superx/ds/api/report/download?tid=71030</code>
|Erzeugt einen Export des Berichtsergebnisses.
|-
|Themenbaum
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu/tree</code>
|Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum.
|-
|Teil des Themenbaums
|GET
|<code>https://demo.superx-testserver.de/superx/ds/api/menu?tid=71030</code>
|Liefert einen bestimmten Bereich des Themenbaums.
|}


Beispiel:


<source lang="bash">
===Masken verwenden===
curl -s "https://<<domain>>/superx/ds/api/etl/job/hrstage_load_and_transform"
</source>


Die Rückgabe enthält je nach Implementierung weitere Informationen zum Job, zum Beispiel Name, Typ, technische Struktur oder enthaltene Schritte. Für Oberflächen sollte dieser Aufruf nur ergänzend verwendet werden, da die einfache Jobliste für die meisten Anwendungsfälle ausreicht.
Der Aufruf
 
===Jobdefinitionen neu in die Datenbank schreiben===
 
Der folgende Endpunkt kann verwendet werden, um Jobs aus den vorhandenen Definitionen neu in die Datenbank zu schreiben. Er entspricht fachlich dem erneuten Einlesen der Jobdefinitionen und sollte nur durch Administratoren oder im Rahmen der Einrichtung verwendet werden.


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/job/writeJobsToDb
https://demo.superx-testserver.de/superx/ds/api/form/71030
</source>
</source>


Beispiel:
liefert unter anderem:


<source lang="bash">
* Namen der Eingabefelder
curl -s "https://<<domain>>/superx/ds/api/etl/job/writeJobsToDb"
* Feldtypen
</source>
* Beschriftungen
* Pflichtfelder
* Defaultwerte
* Auswahllisten
* Baum- beziehungsweise TreeSelect-Inhalte
* verfügbare Stylesheets


Dieser Aufruf sollte nicht als normale Benutzeraktion angeboten werden. Er ist eher für Einrichtung, Wartung und Entwicklung gedacht.
Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.


===Beliebigen Job starten===
Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet:
 
Ein konkreter Job kann über Datenquelle und Job-ID gestartet werden. Dieser Endpunkt ist die generische Startfunktion der Komponentenverwaltung.


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/job/execute/{sourceDatabase}/{jobId}
POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030
</source>
</source>


Beispiel:
Der Request benötigt:


<source lang="bash">
<source lang="text">
curl -s "https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform"
Content-Type: application/json
</source>
</source>


Beispielantwort:
Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden:


<source lang="json">
<source lang="json">
12345
{}
</source>
 
Die Zahl ist die JobExecutionId. Sie wird anschließend für Status- und Logabfragen verwendet.
 
Wenn der Server keinen neuen Job starten kann, kann als Rückgabe -1 erscheinen.
 
<source lang="json">
-1
</source>
 
Eine Rückgabe von -1 sollte von der Oberfläche nicht als JobExecutionId behandelt werden. Stattdessen sollte geprüft werden, ob bereits ein Job läuft.
 
<source lang="text">
GET /superx/ds/api/etl/running
</source>
 
===SourceDatabase bestimmen===
 
Der Parameter {sourceDatabase} gibt die Datenquelle beziehungsweise den technischen Ausführungskontext an. In vielen Fällen wird eduetl verwendet. Bei Komponenten mit eigener Datenquelle kann der Wert aus der Komponentenliste oder aus den Connector-Informationen abgeleitet werden.
 
Typisches Vorgehen in einer Oberfläche:
 
#Komponentenliste über /etl/list laden.
#Komponente anhand des Kürzels auswählen.
#Zugehörige Jobs über /etl/job/list/{component} laden.
#Für normale Datenläufe bevorzugt den Job {component}_unload_load_transform suchen.
#Falls dieser nicht existiert, auf {component}_load_and_transform zurückfallen.
#Als sourceDatabase bevorzugt die zum Job passende Connector-Datenquelle verwenden.
#Wenn keine spezielle Datenquelle bekannt ist, eduetl verwenden.
 
===Update starten===
 
Ein Update ist fachlich ein Datenlauf. Je nach Modul besteht es aus Unload, Load und Transform oder nur aus Load und Transform. Für die normale Administration sollte bevorzugt ein vollständiger Updatejob verwendet werden.
 
Bevorzugter Job:
 
<source lang="text">
{component}_unload_load_transform
</source>
 
Fallback:
 
<source lang="text">
{component}_load_and_transform
</source>
 
Beispiel für HRStage:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_unload_load_transform"
</source>
 
Falls dieser Job nicht existiert:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform"
</source>
 
Entwickler sollten nicht blind einen Jobnamen zusammensetzen, sondern vorher über /etl/job/list/{component} prüfen, welche Jobs tatsächlich vorhanden sind.
 
===Install starten===
 
Die Installation einer Komponente kann über einen eigenen Install-Endpunkt gestartet werden. Dieser Endpunkt entscheidet serverseitig, welcher Installationsjob für die Komponente relevant ist.
 
<source lang="text">
GET /superx/ds/api/etl/job/install/{component}
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/install/hrstage"
</source>
 
Der Aufruf liefert im Erfolgsfall ebenfalls eine JobExecutionId zurück. Diese kann anschließend über die Status- und Log-Endpunkte überwacht werden.
 
===Upgrade starten===
 
Ein Upgrade aktualisiert die installierte Modulversion. Dies ist fachlich von einem Datenupdate zu unterscheiden. Ein Upgrade sollte nur angeboten oder hervorgehoben werden, wenn die Komponentenliste needsUpgrade=true liefert oder wenn ein Administrator bewusst ein Upgrade starten möchte.
 
<source lang="text">
GET /superx/ds/api/etl/job/upgrade/{component}
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/upgrade/hrstage"
</source>
 
Die Oberfläche sollte vor dem Start eines Upgrades eine Bestätigung verlangen, da ein Upgrade Strukturänderungen, neue Tabellen, neue Felder oder andere dauerhafte Änderungen ausführen kann.
 
===Alle Upgrades starten===
 
Der folgende Endpunkt startet beziehungsweise verarbeitet Upgrades übergreifend. Er sollte nur im Administrationskontext und nicht in normalen Benutzeroberflächen verwendet werden.
 
<source lang="text">
GET /superx/ds/api/etl/job/upgrade_all
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/upgrade_all"
</source>
 
Für Weboberflächen ist dieser Aufruf nur mit deutlicher Warnung geeignet, da mehrere Komponenten betroffen sein können.
 
===Uninstall starten===
 
Die Deinstallation einer Komponente entfernt modulbezogene Strukturen oder Steuerdaten. Dieser Aufruf ist potenziell destruktiv und sollte ausschließlich im Expertenmodus angeboten werden.
 
<source lang="text">
GET /superx/ds/api/etl/job/uninstall/{component}
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/uninstall/hrstage"
</source>
 
Vor dem Start sollte eine Oberfläche immer eine zusätzliche Sicherheitsabfrage anzeigen.
 
===Unload starten===
 
Ein Unload exportiert oder entlädt Daten aus einem Quellsystem beziehungsweise bereitet Rohdaten für die weitere Verarbeitung vor. Der genaue Ablauf ist modulabhängig.
 
<source lang="text">
GET /superx/ds/api/etl/unload/{component}
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/unload/hrstage"
</source>
 
Ein einzelner Unload ist normalerweise kein vollständiger Datenlauf. Für normale Anwender sollte daher eher der vollständige Updatejob angeboten werden.
 
===Transform starten===
 
Ein Transform-Lauf verarbeitet bereits vorhandene oder zuvor entladene Daten und überführt sie in die Zielstrukturen. Dieser Aufruf setzt in der Regel voraus, dass die benötigten Rohdaten bereits vorhanden sind.
 
<source lang="text">
GET /superx/ds/api/etl/transform/{component}
</source>
</source>


Beispiel:
Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/transform/hrstage"
</source>
 
Ein Transform-Aufruf sollte in normalen Oberflächen nur dann angeboten werden, wenn klar ist, dass die Voraussetzungen erfüllt sind. Andernfalls sollte der vollständige Updatejob verwendet werden.
 
===Complete starten===
 
Der Complete-Aufruf startet modulabhängige Abschlussarbeiten. Das können zum Beispiel Aggregationen, Nacharbeiten, Prüfungen oder der Aufbau zusätzlicher Auswertungsstrukturen sein.
 
<source lang="text">
GET /superx/ds/api/etl/complete/{component}
</source>


Beispiel:
Beispiel:
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/complete/hrstage"
</source>
Da die Bedeutung von Complete vom jeweiligen Modul abhängt, sollte die Oberfläche diesen Aufruf eher im Expertenbereich anzeigen oder mit einer kurzen Beschreibung aus der Jobdefinition kombinieren.
===Konfigurationsjobs und Spezialjobs===
Spezialjobs werden in der Jobliste oder in den Connector-Informationen einer Komponente angezeigt. Beispiele sind das Entladen oder Wiedereinspielen von Konfigurationen.
Beispiele für technische Job-IDs:
<source lang="text">
kern_unload_config_special
kern_upload_config_special
</source>
Solche Jobs werden über den generischen Execute-Endpunkt gestartet.
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/kern_unload_config_special"
curl -s "https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/kern_upload_config_special"
</source>
Eine Oberfläche sollte Spezialjobs nicht anhand einer festen Liste hart verdrahten, sondern dynamisch aus /etl/job/list/{component} oder aus dem Feld connectors der Komponentenliste ableiten.
===Installationsfunktionen einer Komponente===
Für eine Komponente können installierbare oder vorbereitende Funktionen abgefragt werden. Dieser Aufruf ist vor allem für Entwickler und Setup-Oberflächen interessant.
<source lang="text">
GET /superx/ds/api/etl/installFunctions/{component}
</source>
Beispiel:
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/installFunctions/hrstage"
</source>
Die Rückgabe ist abhängig von den für die Komponente definierten Installationsfunktionen.
===Status eines Jobs abfragen===
Nach dem Start eines Jobs sollte die zurückgelieferte JobExecutionId regelmäßig abgefragt werden. Der Status-Endpunkt liefert Informationen zum aktuellen Zustand des Laufs.
<source lang="text">
GET /superx/ds/api/etl/jobExecutionStatus/{jobExecutionId}
</source>
Beispiel:
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/jobExecutionStatus/12345"
</source>
Beispielantwort, vereinfacht:


<source lang="json">
<source lang="json">
{
{
   "jobExecutionId": 12345,
   "Kennung": "admin",
   "status": "STARTED",
   "Gruppe": "",
   "exitStatus": {
   "Name": "",
    "exitCode": "UNKNOWN"
   "Institution": ""
  },
   "stepExecutions": []
}
}
</source>
</source>


Ein Client sollte die Antwort defensiv auswerten, da je nach Spring-Batch-Version und SuperX-Implementierung unterschiedliche Felder vorhanden sein können. Relevant sind vor allem JobExecutionId, Status, ExitStatus und eventuell enthaltene Step-Informationen.
Die Antwort enthält die Ergebnistabelle als JSON.


===Tippfehler-Endpunkt für Status===


In einigen Versionen existiert zusätzlich ein historischer Endpunkt mit Tippfehler im Namen.
===POST-Aufruf im Browser testen===


<source lang="text">
GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.
GET /superx/ds/api/etl/jobExcecutionStatus/{jobExecutionId}
</source>


Neue Entwicklungen sollten bevorzugt den korrekt geschriebenen Endpunkt jobExecutionStatus verwenden. Ein Fallback auf jobExcecutionStatus kann sinnvoll sein, wenn ältere Installationen unterstützt werden müssen.
Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:


===Joblog abfragen===
# Entwicklertools mit F12 öffnen.
# ''Netzwerkanalyse'' auswählen.
# Einen REST-Aufruf markieren und ''Bearbeiten und erneut senden'' auswählen.
# Methode von GET auf POST ändern.
# Header ergänzen:
#:<code>Content-Type: application/json</code>
# Unter ''Inhalt'' mindestens folgenden JSON-Body eintragen:
#:<code>{}</code>
# Anfrage senden.


Das Joblog kann über die JobExecutionId geladen werden. Dieser Aufruf ist für Administrationsoberflächen besonders wichtig, weil er dem Benutzer Rückmeldungen zum laufenden oder abgeschlossenen Job gibt.
Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu:


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/jobLog/{jobExecutionId}
Content-Type: application/json
Content-Length: 2
</source>
</source>


Beispiel:
Typische Fehler:


<source lang="bash">
{| class="wikitable"
curl -s "https://<<domain>>/superx/ds/api/etl/jobLog/12345"
!Fehler!!Ursache!!Lösung
</source>
|-
 
|<code>Required request body is missing</code>
Die Rückgabe kann je nach Implementierung als Text oder JSON-Struktur erfolgen. Eine Oberfläche sollte daher beide Varianten behandeln können. Wenn ein JSON-Objekt zurückkommt, sollte nach Feldern wie log, content, message oder ähnlichen Textfeldern gesucht werden. Andernfalls kann die Antwort direkt als Text dargestellt werden.
|Der POST-Request enthält keinen Body.
 
|Mindestens <code>{}</code> als Inhalt mitsenden.
===Laufende Jobs abfragen===
|-
 
|<code>Content-Type 'application/octet-stream' is not supported</code>
Mit dem running-Endpunkt kann geprüft werden, ob derzeit ein Job läuft. Das ist insbesondere wichtig, wenn ein Startaufruf -1 zurückliefert.
|Der Body wird ohne passenden Content-Type übertragen.
 
|<code>Content-Type: application/json</code> setzen.
<source lang="text">
|}
GET /superx/ds/api/etl/running
</source>


Beispiel:


<source lang="bash">
==Hinweise zur Verwendung==
curl -s "https://<<domain>>/superx/ds/api/etl/running"
</source>


Eine Oberfläche sollte diesen Endpunkt regelmäßig oder nach fehlgeschlagenen Startversuchen abfragen, um anzuzeigen, ob bereits ein anderer Job aktiv ist.
REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.


===Jobausführungen abfragen===
Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.


Der folgende Endpunkt liefert Informationen zu Jobausführungen. Er kann für Übersichten, Historien oder Diagnoseansichten verwendet werden.
Für die Komponentenverwaltung sind insbesondere die Kombinationen aus


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/jobExecutionInfos
/etl/list
/etl/job/list/{component}
</source>
</source>


Beispiel:
und für Masken
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/jobExecutionInfos"
</source>
 
Die genaue Struktur der Antwort sollte in der jeweiligen Installation geprüft werden, da sie von der konkreten Implementierung abhängen kann.
 
===Job stoppen===
 
Ein einzelner laufender Job kann über seine ID gestoppt werden.


<source lang="text">
<source lang="text">
GET /superx/ds/api/etl/stop/{id}
/form/{tid}
/report?tid={tid}
</source>
</source>


Beispiel:
relevant.
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/stop/12345"
</source>
 
Dieser Aufruf sollte nur für Administratoren verfügbar sein. Das Stoppen eines Jobs kann zu unvollständigen Datenständen führen, wenn der Job mitten in einem Verarbeitungsschritt beendet wird.
 
===Job starten oder fortsetzen===
 
Ein vorhandener Job beziehungsweise eine bekannte Ausführung kann über start angesprochen werden. Dieser Endpunkt ist vor allem für interne oder spezielle Administrationsfunktionen relevant.
 
<source lang="text">
GET /superx/ds/api/etl/start/{id}
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/start/12345"
</source>
 
Für normale Oberflächen ist in der Regel der Execute-Endpunkt mit sourceDatabase und jobId geeigneter.
 
===Alle Jobs stoppen===
 
Der folgende Endpunkt stoppt alle laufenden Jobs. Er ist ausschließlich für Administrations- und Notfallsituationen gedacht.
 
<source lang="text">
GET /superx/ds/api/etl/job/stopAll
</source>
 
Beispiel:
 
<source lang="bash">
curl -s "https://<<domain>>/superx/ds/api/etl/job/stopAll"
</source>
 
Eine Oberfläche sollte diesen Aufruf nur im Expertenmodus und mit deutlicher Sicherheitsabfrage anbieten.
 
===Typisches Client-Verhalten===
 
Ein robuster Client sollte nicht nur einzelne Endpunkte direkt aufrufen, sondern den Ablauf systematisch aufbauen.
 
#/etl/list laden und Komponenten anzeigen.
#Bei Auswahl einer Komponente /etl/job/list/{component} laden.
#Aktionen aus den tatsächlich vorhandenen Job-IDs ableiten.
#Beim Start eines Jobs die Rückgabe prüfen.
#Wenn eine positive JobExecutionId zurückkommt, Status und Log pollen.
#Wenn -1 zurückkommt, /etl/running prüfen.
#Bei HTTP-Fehlern die Fehlermeldung anzeigen und zusätzlich auf Tomcat-Logs verweisen.
 
===Beispielablauf: Update aus einer Weboberfläche===
 
Der folgende Ablauf beschreibt ein typisches Update aus Sicht einer JavaScript-basierten Administrationsoberfläche.
 
#Komponentenliste laden.
#Gewählte Komponente bestimmen, zum Beispiel hrstage.
#Jobliste der Komponente laden.
#Prüfen, ob hrstage_unload_load_transform existiert.
#Falls ja, diesen Job starten.
#Falls nein, prüfen, ob hrstage_load_and_transform existiert.
#Startaufruf ausführen.
#JobExecutionId speichern.
#Status regelmäßig über jobExecutionStatus abfragen.
#Log regelmäßig oder bei Bedarf über jobLog anzeigen.
#Nach Abschluss Oberfläche aktualisieren.
 
Beispielhafte Reihenfolge der HTTP-Aufrufe:
 
<source lang="text">
GET /superx/ds/api/etl/list
GET /superx/ds/api/etl/job/list/hrstage
GET /superx/ds/api/etl/job/execute/eduetl/hrstage_unload_load_transform
GET /superx/ds/api/etl/jobExecutionStatus/12345
GET /superx/ds/api/etl/jobLog/12345
</source>
 
===Beispielablauf: Upgrade===
 
Ein Upgrade sollte nur bewusst gestartet werden. Die Oberfläche sollte vorher prüfen, ob needsUpgrade=true gesetzt ist oder ob der Benutzer im Expertenmodus arbeitet.
 
<source lang="text">
GET /superx/ds/api/etl/list
GET /superx/ds/api/etl/job/upgrade/hrstage
GET /superx/ds/api/etl/jobExecutionStatus/12345
GET /superx/ds/api/etl/jobLog/12345
</source>
 
Ein Upgrade ist kein Datenupdate. Es aktualisiert die Modulstruktur beziehungsweise die Modulversion. Diese Unterscheidung sollte in der Oberfläche klar sichtbar sein.
 
===Beispielablauf: Konfiguration entladen===
 
Konfigurationsjobs werden über die Jobliste erkannt und anschließend über den generischen Execute-Endpunkt gestartet.
 
<source lang="text">
GET /superx/ds/api/etl/job/list/kern
GET /superx/ds/api/etl/job/execute/eduetl/kern_unload_config_special
GET /superx/ds/api/etl/jobLog/12345
</source>
 
Dieser Ablauf ist ein gutes Beispiel dafür, warum die Oberfläche technische Jobs dynamisch aus der Jobliste ableiten sollte. Spezialjobs sind nicht für jedes Modul gleich und sollten daher nicht fest in der Oberfläche verdrahtet werden.
 
===Fehlerbehandlung===
 
REST-Clients sollten mit mehreren typischen Fehlerfällen umgehen können.
 
{| class="wikitable"
!Fall!!Bedeutung!!Empfohlene Reaktion
|-
|HTTP 404||Endpunkt oder Job existiert nicht.||Jobliste erneut laden und prüfen, ob der Job in dieser Installation vorhanden ist.
|-
|HTTP 500||Serverseitiger Fehler.||Fehlermeldung anzeigen, Tomcat-Log prüfen und ETL-Konfiguration kontrollieren.
|-
|Rückgabe -1||Es wurde kein neuer Job gestartet.||/etl/running aufrufen und anzeigen, ob bereits ein Job läuft.
|-
|Leere Jobliste||Für die Komponente wurden keine Jobs eingelesen.||ComponentAdminCLI -r ausführen und Modulverzeichnis prüfen.
|-
|Kein Log verfügbar||Job ist noch nicht gestartet, bereits bereinigt oder Log-Endpunkt liefert keine Daten.||Status prüfen und Benutzerhinweis anzeigen.
|}
 
===Hinweise zur Sicherheit===
 
Viele Endpunkte können Daten verändern, Jobs starten oder Komponenten deinstallieren. Deshalb sollten sie nur für berechtigte Administratoren erreichbar sein. Besonders kritisch sind Install, Upgrade, Uninstall, stopAll und technische Spezialjobs.
 
Für eigene Oberflächen empfiehlt sich eine klare Trennung zwischen Normalmodus und Expertenmodus. Normale Benutzer sollten nur ungefährliche oder fachlich eindeutige Aktionen sehen, zum Beispiel Update, Details, Status und Log. Technische Einzeljobs sollten nur im Expertenbereich angeboten werden.
 
===Hinweise zur Frontend-Implementierung===
 
Eine Weboberfläche sollte die verfügbaren Aktionen nicht fest codieren, sondern aus den Daten der REST-Schnittstelle ableiten. Besonders wichtig ist die Kombination aus /etl/list und /etl/job/list/{component}. Dadurch funktioniert die Oberfläche auch dann, wenn ein Modul zusätzliche Spezialjobs besitzt oder bestimmte Standardjobs nicht vorhanden sind.
 
Empfohlene Ableitung von Aktionen aus Job-IDs:
 
{| class="wikitable"
!Job-ID-Muster!!Aktion in der Oberfläche
|-
|*_unload_load_transform||Update starten
|-
|*_load_and_transform||Load & Transform starten
|-
|*_unload||Unload starten
|-
|*_install_upgrade||Install/Upgrade starten
|-
|*_uninstall||Deinstallation starten
|-
|*_unload_config_special||Konfiguration entladen
|-
|*_upload_config_special||Konfiguration einspielen
|-
|andere Spezialjobs||Mit technischem Namen oder sprechendem Jobnamen anzeigen
|}
 
===Zusammenfassung===
 
Die REST-Schnittstelle stellt die technische Grundlage bereit, um SuperX-Komponenten und ETL-Jobs über Weboberflächen oder externe Anwendungen zu steuern. Entwickler sollten die Endpunkte dynamisch auswerten, Jobstarts immer über Status- und Logabfragen begleiten und sicherheitskritische Aktionen nur im Administrations- oder Expertenkontext anbieten.

Version vom 22. September 2026, 08:09 Uhr

REST-Schnittstelle

Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.

Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.

Zu den wichtigsten Einsatzbereichen gehören:

  • Komponentenverwaltung und ETL-Jobs
  • Status- und Protokollabfragen
  • SuperX-Masken und deren Eingabefelder
  • Ausführung von Masken und Abruf der Ergebnistabellen
  • Export von Berichtsergebnissen
  • Einbindung von SuperX-Funktionen in eigene Weboberflächen

In den folgenden Beispielen wird diese Beispielinstallation verwendet: 

https://demo.superx-testserver.de/superx/

Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.


Grundlagen

Die REST-Endpunkte befinden sich unterhalb von: 

https://demo.superx-testserver.de/superx/ds/api/

Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.

Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.


Einrichtung und Voraussetzungen

Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.

Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:

  • die SuperX-Webapp ist über Tomcat erreichbar,
  • die Datenbankverbindung funktioniert,
  • ein aktueller Kernstand ist installiert,
  • die benötigten Modulverzeichnisse sind eingebunden,
  • die ETL- und Jobdefinitionen wurden eingelesen.

Aktuelles Kernpaket verwenden

Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.

Beispiel: 

wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz

Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in WEB-INF/lib liegen bleiben.

Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.

Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden: 

WEB-INF/classes/spring-batch.properties
WEB-INF/classes/hikari.properties
WEB-INF/classes/quartz.properties

Datenbankverbindung prüfen

Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der dbforms-config.xml sollte der SpringBeanConnectionProvider verwendet werden: 

<dbconnection connectionProviderClass="de.superx.db.SpringBeanConnectionProvider"
              default="true"
              id="datasourceBean"
              isJndi="false"
              isPow2="true"/>

Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.

module_ignore.properties prüfen

Für die Komponentenverwaltung muss folgende Datei vorhanden sein: 

WEB-INF/conf/edustore/db/module/module_ignore.properties

Beispielinhalt: 

ignore.modules=kennx,gxstage,bil

Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.

Modulverzeichnisse bereitstellen

Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus: 

WEB-INF/conf/edustore/db/module

Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.

Beispiel: 

cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .

Zusätzliche Kern-ETL-Dateien prüfen

Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.

Quellverzeichnis im SuperX-Git: 

SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update

Zielverzeichnis in der Webapp: 

$WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update

Benötigte Dateien:

  • edustore_kern_man_unload_config_ids.xml
  • edustore_kern_man_unload_config_pg.xml
  • edustore_kern_man_upload_config_ids.xml
  • edustore_kern_man_upload_config_pg.xml

Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.

ETL-Steuerdaten einlesen

Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.

Beispiel: 

cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
  "de.superx.bin.ComponentAdminCLI" -r

Der Parameter -r liest die Komponenten- und Jobdefinitionen neu ein.

Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden: 

https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb

Einzelnen Job über die CLI testen

Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.

Beispiel: 

cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
  "de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform

Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.

Tomcat neu starten

Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.

Beispiel: 

systemctl restart tomcat10

Je nach Installation kann der Dienst auch anders heißen.

REST-Schnittstelle prüfen

Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden: 

https://demo.superx-testserver.de/superx/ds/api/etl/list

https://demo.superx-testserver.de/superx/ds/api/etl/job/list

Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.

Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden: 

https://demo.superx-testserver.de/superx/ds/api/form/71030

Fehlersuche bei der Einrichtung

Bei Problemen sollten insbesondere folgende Punkte geprüft werden:

Problem Prüfung
REST-Endpunkt liefert HTTP 500 Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren.
Komponentenliste ist leer oder fehlerhaft Modulverzeichnis und module_ignore.properties prüfen.
Jobs fehlen ETL-Steuerdaten mit ComponentAdminCLI -r oder über /etl/job/writeJobsToDb neu einlesen.
Job funktioniert über REST nicht Denselben Job testweise über die CLI starten und Tomcat-Log prüfen.
Spezialjobs fehlen Zusätzliche ETL-XML-Dateien im Verzeichnis edustore_update prüfen.
REST-Aufruf funktioniert nach einem Upgrade nicht Bibliotheken in WEB-INF/lib sowie spring-batch.properties, hikari.properties und quartz.properties prüfen.
POST auf eine Maske liefert "Required request body is missing" Einen JSON-Body mitsenden, mindestens {}.
POST liefert "application/octet-stream is not supported" Header Content-Type: application/json setzen.

In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.


Komponentenverwaltung und ETL

Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.

Der Basis-Pfad lautet: 

https://demo.superx-testserver.de/superx/ds/api/etl


Übersicht der wichtigsten ETL-Aufrufe

Funktion Methode Beispiel Zweck
Komponenten anzeigen GET https://demo.superx-testserver.de/superx/ds/api/etl/list Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen.
Installierbare Komponenten GET https://demo.superx-testserver.de/superx/ds/api/etl/installables/list Zeigt Komponenten, die grundsätzlich installiert werden können.
Alle ETL-Jobs GET https://demo.superx-testserver.de/superx/ds/api/etl/job/list Liefert alle bekannten ETL- und Batch-Jobs.
Jobs einer Komponente GET https://demo.superx-testserver.de/superx/ds/api/etl/job/list/hrstage Zeigt nur die Jobs einer bestimmten Komponente.
Jobdetails GET https://demo.superx-testserver.de/superx/ds/api/etl/job/hrstage_load_and_transform Liefert technische Informationen zu einem bestimmten Job.
Jobdefinitionen neu einlesen GET https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein.
Job starten GET https://demo.superx-testserver.de/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform Startet einen bestimmten Job und liefert eine JobExecutionId zurück.
Installation starten GET https://demo.superx-testserver.de/superx/ds/api/etl/job/install/hrstage Startet die Installation einer Komponente.
Upgrade starten GET https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade/hrstage Startet ein Upgrade einer installierten Komponente.
Alle Upgrades starten GET https://demo.superx-testserver.de/superx/ds/api/etl/job/upgrade_all Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten.
Komponente deinstallieren GET https://demo.superx-testserver.de/superx/ds/api/etl/job/uninstall/hrstage Startet die Deinstallation einer Komponente.
Unload starten GET https://demo.superx-testserver.de/superx/ds/api/etl/unload/hrstage Startet den Unload einer Komponente.
Transform starten GET https://demo.superx-testserver.de/superx/ds/api/etl/transform/hrstage Startet die Transformation bereits vorhandener Daten.
Complete starten GET https://demo.superx-testserver.de/superx/ds/api/etl/complete/hrstage Startet modulabhängige Abschlussarbeiten.
Installationsfunktionen GET https://demo.superx-testserver.de/superx/ds/api/etl/installFunctions/hrstage Zeigt zusätzliche Installationsfunktionen einer Komponente.
Laufende Jobs GET https://demo.superx-testserver.de/superx/ds/api/etl/running Zeigt aktuell laufende Jobs.
Jobstatus GET https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionStatus/12345 Liefert den aktuellen Status einer Jobausführung.
Joblog GET https://demo.superx-testserver.de/superx/ds/api/etl/jobLog/12345 Liefert das Protokoll einer Jobausführung.
Jobausführungen GET https://demo.superx-testserver.de/superx/ds/api/etl/jobExecutionInfos Liefert Informationen zu Jobausführungen.
Job stoppen GET https://demo.superx-testserver.de/superx/ds/api/etl/stop/12345 Stoppt eine bestimmte Jobausführung.
Job starten oder fortsetzen GET https://demo.superx-testserver.de/superx/ds/api/etl/start/12345 Spricht eine vorhandene Jobausführung erneut an.
Alle Jobs stoppen GET https://demo.superx-testserver.de/superx/ds/api/etl/job/stopAll Stoppt alle laufenden Jobs.


Typischer ETL-Ablauf

Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.

Ein typischer Ablauf für ein Modulupdate ist: 

1. Komponenten laden
   /etl/list

2. Jobs des Moduls laden
   /etl/job/list/hrstage

3. Gewünschten Job starten
   /etl/job/execute/eduetl/hrstage_unload_load_transform

4. Jobstatus abfragen
   /etl/jobExecutionStatus/12345

5. Jobprotokoll anzeigen
   /etl/jobLog/12345

Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.

Spezialjobs wie beispielsweise 

kern_unload_config_special
kern_upload_config_special

können ebenfalls über den generischen Execute-Endpunkt gestartet werden.


SuperX-Masken und Berichte

Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.

Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.


Übersicht der wichtigsten Masken- und Berichtsaufrufe

Funktion Methode Beispiel Zweck
Maskenaufbau laden GET https://demo.superx-testserver.de/superx/ds/api/form/71030 Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften.
Abhängige Felder aktualisieren POST https://demo.superx-testserver.de/superx/ds/api/form/71030/inputupdate Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu.
Informationen zur Maske GET https://demo.superx-testserver.de/superx/ds/api/report?tid=71030 Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet.
Maske ausführen POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030 Führt die Maske aus und liefert die Ergebnistabelle als JSON.
Ergebnis-Stylesheets GET https://demo.superx-testserver.de/superx/ds/api/report/stylesheets?tid=71030 Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets.
Sichten eines Feldes GET https://demo.superx-testserver.de/superx/ds/api/report/views?tid=71030&fieldName=Institution Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes.
Inhalt einer Sicht GET https://demo.superx-testserver.de/superx/ds/api/report/view?tid=71030&fieldName=Institution&viewId=... Liefert den Inhalt einer bestimmten Sicht.
Bericht herunterladen POST https://demo.superx-testserver.de/superx/ds/api/report/download?tid=71030 Erzeugt einen Export des Berichtsergebnisses.
Themenbaum GET https://demo.superx-testserver.de/superx/ds/api/menu/tree Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum.
Teil des Themenbaums GET https://demo.superx-testserver.de/superx/ds/api/menu?tid=71030 Liefert einen bestimmten Bereich des Themenbaums.


Masken verwenden

Der Aufruf 

https://demo.superx-testserver.de/superx/ds/api/form/71030

liefert unter anderem:

  • Namen der Eingabefelder
  • Feldtypen
  • Beschriftungen
  • Pflichtfelder
  • Defaultwerte
  • Auswahllisten
  • Baum- beziehungsweise TreeSelect-Inhalte
  • verfügbare Stylesheets

Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.

Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet: 

POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030

Der Request benötigt: 

Content-Type: application/json

Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden: 

{}

Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.

Beispiel: 

{
  "Kennung": "admin",
  "Gruppe": "",
  "Name": "",
  "Institution": ""
}

Die Antwort enthält die Ergebnistabelle als JSON.


POST-Aufruf im Browser testen

GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.

Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:

  1. Entwicklertools mit F12 öffnen.
  2. Netzwerkanalyse auswählen.
  3. Einen REST-Aufruf markieren und Bearbeiten und erneut senden auswählen.
  4. Methode von GET auf POST ändern.
  5. Header ergänzen:
    Content-Type: application/json
  6. Unter Inhalt mindestens folgenden JSON-Body eintragen:
    {}
  7. Anfrage senden.

Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu: 

Content-Type: application/json
Content-Length: 2

Typische Fehler:

Fehler Ursache Lösung
Required request body is missing Der POST-Request enthält keinen Body. Mindestens {} als Inhalt mitsenden.
Content-Type 'application/octet-stream' is not supported Der Body wird ohne passenden Content-Type übertragen. Content-Type: application/json setzen.


Hinweise zur Verwendung

REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.

Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.

Für die Komponentenverwaltung sind insbesondere die Kombinationen aus 

/etl/list
/etl/job/list/{component}

und für Masken 

/form/{tid}
/report?tid={tid}

relevant.

Abgerufen von „https://superxhosting.de/wiki/index.php?title=SuperX_REST_Schnittstelle&oldid=16665“