Open-VHS – Datenformat und Schnittstelle

Autor: A&B One Digital GmbH
Version: 0.9.1 (veraltete Version)
Stand: 18.10.2013

Historie

Bitte verwenden Sie die aktuelle Version 1.2.

Datenformat

Typ „Veranstaltung“

Betriebssystem Windows 7
Kursinhalt:
Aufbau eines typischen PC-Systems, Bedienung und individuelle …

Erläuterungen

Allgemeines

Nur ausgewählte Textfelder dürfen HTML-Auszeichnungen und Zeilenumbrüche enthalten.

Feld guid

Werte in diesem Feld müssen innerhalb des gesamten Datenexportes einmalig sein. guid wird für Updates der aktuellen Teilnehmerzahl benötigt.

An dieser Stelle kann auch die VHS-interne Nummer bzw. ID der Veranstaltung verwendet werden.

Felder wochentag und termin

Idealerweise werden sämtliche Termine der Veranstaltung als Element termin exportiert. Falls dies nicht möglich ist, können alternativ die Wochentage über das Feld wochentag angegeben werden.

Es ist nicht notwendig, wochentag zu befüllen, wenn termin verwendet wird.

Felder termin/beginn_uhrzeit und termin/ende_uhrzeit

Bei Uhrzeiten ohne explizite Angabe der Zeitzone wird die „lokale“ Zeitzone angenommen.

Feld preis/betrag

Ist eine Veranstaltung kostenlos, so soll in preis/betrag der Wert 0 übergeben werden.

XML-Schema

• openvhs-0.9.1.xsd

Ältere Version

• openvhs-0.9.xsd
• openvhs-0.2.xsd

Beispieldaten

Die nachfolgende XML-Datei enthält Beispieldatensätze mit exemplarischem Umfang:

• openvhs-0.9.1.xml

Ältere Version

• openvhs-0.9.xml
• openvhs-0.2.xml

Belegungsstatus

Für die Übermittlung des Belegungsstatus kann ein vereinfachtes XML-Format verwendet werden, um den Traffic zu reduzieren. Dieses Format enthält nur guid, minimale_teilnehmerzahl, aktuelle_teilnehmerzahl und maximale_teilnehmerzahl.

Im Gegensatz zu den Stammdaten müssen nicht sämtliche Datensätze übertragen werden. Sofern es technisch möglich ist, genügt die Übertragung der jeweils geänderten Werte.

Beispiel 1: Die Aktualisierung der Stammdaten erfolgt alle 24 Stunden mit dem kompletten Datenbestand, der Belegungsstatus aller Veranstaltungen wird stündlich hochgeladen.

Beispiel 2: Die Aktualisierung der Stammdaten erfolgt alle 24 Stunden mit dem kompletten Datenbestand, der Belegungsstatus wird stündlich nur für geänderte Veranstaltungen hochgeladen.

Beispiel 3: Die Aktualisierung der Stammdaten erfolgt alle 24 Stunden mit dem kompletten Datenbestand, der Belegungsstatus wird immer dann hochgeladen, wenn sich eine Veranstaltung ändert (Echtzeit-Aktualisierung).

XML-Schema

• openvhs-belegungsstatus-0.9.1.xsd

Beispieldaten

• openvhs-belegungsstatus-0.9.1.xml

Schnittstelle

Grundsätzliches

Mittels der Schnittstelle übertragen teilnehmende Datenlieferanten ihren aktuellen Datenbestand an die Kursdatenbank.

Bei jeder Übertragung von Stammdaten muss der gesamte Datenbestand geliefert werden, differentielle Updates sind nicht möglich. Ist der zugelieferte Datenbestand gültig, werden die bisher für diesen Datenlieferanten gespeicherten Veranstaltungen gelöscht und durch die neuen Daten ersetzt.

Die Übertragung des Belegungsstatus kann dagegen differentiell erfolgen.

Datenlieferant

Unter Datenlieferant verstehen wir eine konkrete Volkshochschule. Jede Volkshochschule bzw. jeder Veranstalter muss den Datenbestand in einer eigenen Datei übertragen.

Die Identifikation des Datenlieferanten erfolgt über das XML-Element export/ersteller in der hochgeladenen Datei sowie das verwendete Access-Token. Die guid wird dem Datenlieferanten zugeteilt.

Datenumfang

Der exportierte Datenbestand soll alle (auch bereits beendete) Veranstaltungen des laufenden sowie (falls bereits vorhanden) des kommenden Semesters enthalten.

Intervall

Der Datenbestand soll im Normalfall täglich übertragen werden, sofern Änderungen vorgenommen wurden oder wahrscheinlich sind.

Es ist nicht notwendig, identische Datenbestände mehrfach zu übertragen, um ein bestimmtes Intervall einzuhalten. Umgekehrt müssen die Daten aber auch nicht auf Veränderungen überprüft werden, sondern können automatisch zu einem festgelegten Zeitpunkt hochgeladen werden.

Jeder Datenlieferant kann entscheiden, welche Vorgehensweise passend ist: Automatischer täglicher Upload unabhängig von Änderungen am Datenbestand oder Upload nur dann, wenn Änderungen vorgenommen wurden.

Bei Bedarf (z. B. gravierender Fehler im Datenbestand) kann zusätzlich zum Automatismus jederzeit ein manueller Upload erfolgen.

Kann ein Datenlieferant den Belegungsstatus der Veranstaltungen liefern, so sollen diese Informationen möglichst stündlich an die Kursdatenbank übertragen werden.

Upload

Der Upload erfolgt als HTTP-POST mit multipart/form-data gegen die API. Dabei muss das Access-Token des Datenlieferanten mitgeschickt werden. Dieses muss zum XML-Element export/ersteller in der hochgeladenen Datei passen.

Beispiel per cURL:

curl -F file=@datenbestand.openvhs.xml \
     -F access_token={Access-Token} \
     {API-Endpoint}

Beispiel per HTML-Formular:

<form action="{API-Endpoint}" method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="text" name="access_token" value="{Access-Token}" />
    <input type="submit" name="submit" value="Upload" />
</form>

Hinweise:

• Der API-Endpoint steht noch nicht endgültig fest.
• Eine Übertragung per HTTPS muss möglich sein.

Access-Token

Das Access-Token dient zur Authentifizierung eines Datenlieferanten. Ohne Access-Token ist kein Upload möglich.

Ein Datenlieferant bekommt sein Access-Token zugeteilt.