Autor: A&B One Kommunikationsagentur GmbH
Version: 1.2 (aktuellste Version)
webadresse
muss mindestens einmal vorkommen.dozent
ist weggefallen.Feld | Beschreibung | Datentyp | Beispiel | |
---|---|---|---|---|
guid |
technische ID | Pflichtfeld, muss einmalig innerhalb des gesamten Datenexportes sein | xs:string maximal 255 Zeichen |
0F48F5A8-C22C-4AFF-B891-77095CD84029 VG5010105 |
nummer |
vhs-interne Nummer bzw. ID der Veranstaltung | Pflichtfeld | xs:string |
VG5010105 |
name |
Titel | Pflichtfeld | xs:string keine Zeilenumbrüche und keine HTML-Auszeichnung erlaubt |
Windows und Internet - Basiswissen Teil 1 |
untertitel |
Untertitel | optional, mehrfach | xs:string keine Zeilenumbrüche und keine HTML-Auszeichnung erlaubt |
Bildungsurlaub (2 Wochen halbtags) |
dvv_kategorie |
DVV-Kategorie | Pflichtfeld | xs:string |
5.01 |
dvv_kategorie/@version |
Version des DVV-Kategoriesystems zum aktuellen Zeitpunkt '1.0' oder '2.0' (präferiert) |
Pflichtfeld | xs:string |
2.0 |
merkmale/merkmal |
generisches Merkmal | optional, mehrfach | ||
merkmale/merkmal/name |
Name des Merkmals | Pflichtfeld | xs:string |
kursart_digital |
merkmale/merkmal/wert |
Wert des Merkmals | Pflichtfeld | xs:string |
true |
level |
Level | optional | xs:string |
Einsteiger A1 B1 B1.2 |
minimale_teilnehmerzahl |
minimale Teilnehmerzahl | optional | xs:integer >= 0 |
6 |
aktuelle_teilnehmerzahl |
aktuelle Teilnehmerzahl | optional | xs:integer >= 0 |
9 |
maximale_teilnehmerzahl |
maximale Teilnehmerzahl | optional | xs:integer >= 0 |
12 |
anzahl_termine |
Gesamtanzahl der Termine | optional | xs:integer >= 0 |
5 |
beginn_datum |
Datum des ersten Termins | Pflichtfeld | xs:date |
2013-09-03 |
dauer |
Gesamtdauer aller Termine (Unterrichtseinheiten) | optional | xs:decimal >= 0 |
30.0 |
ende_datum |
Datum des letzten Termins | optional | xs:date |
2013-10-01 |
wochentag |
Wochentag(e) der Termine (wird nicht benötigt, wenn alle konkreten Termine angegeben sind) | optional, mehrfach | xs:string aus xs:enumeration |
Samstag Sonntag |
zielgruppe |
Zielgruppe(n) | optional, mehrfach | xs:string |
Lehrer/innen Erzieher/innen Betreuer/innen |
schlagwort |
Schlagwort(e) | optional, mehrfach | xs:string |
Betriebssystem Windows 7 PC Internet |
zertifikat |
Zertifikat/Abschluss der Veranstaltung | optional, mehrfach | ||
zertifikat/name |
Name des Zertifikates/Abschlusses | Pflichtfeld | xs:string |
TS59.P33B |
zertifikat/text |
Beschreibung des Zertifikates/Abschlusses | optional | xs:string Zeilenumbrüche und HTML-Auszeichnung erlaubt |
Prüfung X-pert CMS Online Designer Modul IIIa- CMS Joomla |
text |
Erläuterungstext(e) | optional, mehrfach | ||
text/eigenschaft |
Art des Erläuterungstextes | Pflichtfeld | xs:string |
text |
text/text |
Erläuterungstext | Pflichtfeld | xs:string Zeilenumbrüche und HTML-Auszeichnung erlaubt |
|
veranstaltungsort |
Hauptveranstaltungsort (benötigt für Geokodierung) | Pflichtfeld | ||
veranstaltungsort/name |
Name des Veranstaltungsortes | optional | xs:string |
Eduard-Stieler-Campus |
veranstaltungsort/adresse/land |
Land des Veranstaltungsortes | Pflichtfeld | xs:string |
Deutschland |
veranstaltungsort/adresse/plz |
Postleitzahl des Veranstaltungsortes | Pflichtfeld | xs:string |
36037 |
veranstaltungsort/adresse/ort |
Ort des Veranstaltungsortes | Pflichtfeld | xs:string |
Fulda |
veranstaltungsort/adresse/ortsteil |
Ortsteil des Veranstaltungsortes | optional | xs:string |
|
veranstaltungsort/adresse/strasse |
Straße des Veranstaltungsortes | Pflichtfeld | xs:string |
Brüder-Grimm-Str. 5 |
veranstaltungsort/barrierefrei |
Flag für barrierefreien Zugang zum Veranstaltungsort Element entfällt, wenn Status der Barrierefreiheit nicht bekannt ist |
optional | xs:boolean |
true |
termin |
konkreter Termin | optional, mehrfach | ||
termin/beginn_datum |
Datum des Termins | Pflichtfeld | xs:date |
2013-09-03 |
termin/beginn_uhrzeit |
Beginn des Termins (Uhrzeit) | optional | xs:time |
18:30:00+02:00 18:30:00 |
termin/ende_uhrzeit |
Ende des Termins (Uhrzeit) | optional | xs:time |
21:00:00+02:00 21:00:00 |
preis |
Preisangaben zur Veranstaltung | optional | ||
preis/betrag |
Standardpreis | Pflichtfeld | xs:decimal
>= 0 |
82.8 |
preis/rabatt_moeglich |
Flag für mögliche Ermäßigungen Element entfällt, wenn Status der Ermäßigungen nicht bekannt ist |
optional | xs:boolean |
true |
preis/zusatz |
Zusätzliche Anmerkung zu den Preisangaben | optional, mehrfach | xs:string keine Zeilenumbrüche und keine HTML-Auszeichnung erlaubt |
zzgl. ca. 5 € für Unterrichtsmaterial |
webadresse |
zugehörige Webadressen, z. B. Detailseite im Portal des Veranstalters | Pflichtfeld, optional mehrfach | ||
webadresse/typ |
Art der Webadresse | Pflichtfeld | xs:string aus xs:enumeration |
website website_mobile attachment picture video |
webadresse/name |
Bezeichnung der Webadresse | optional | xs:string |
Kursdetails Ablaufplan (Stand 23.05.2013) |
webadresse/uri |
URI der Webadresse | Pflichtfeld | xs:string |
http://vhs-fulda.de/index.php?id=22&athaupt=11&knr=VG5010105&kursname=Windows+und+Internet+-+Basiswissen+Teil+1 |
Nur ausgewählte Textfelder dürfen HTML-Auszeichnungen und Zeilenumbrüche enthalten.
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.
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.
termin/beginn_uhrzeit
und termin/ende_uhrzeit
Bei Uhrzeiten ohne explizite Angabe der Zeitzone wird die „lokale“ Zeitzone angenommen.
preis/betrag
Ist eine Veranstaltung kostenlos, so soll in preis/betrag
der Wert 0
übergeben werden.
Die nachfolgende XML-Datei enthält Beispieldatensätze mit exemplarischem Umfang:
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).
Mittels der Schnittstelle übertragen teilnehmende Datenlieferanten ihren aktuellen Datenbestand an die vhs-Kursfinder-Datenbank.
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.
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.
Der exportierte Datenbestand soll alle (auch bereits beendete) Veranstaltungen des laufenden sowie (falls bereits vorhanden) des kommenden Semesters enthalten.
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 vhs-Kursfinder-Datenbank übertragen werden.
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>
Der API-Endpoint des Produktivsystems lautet:
https://api.volkshochschule.de/1/upload
Hinweis:
Das Access-Token dient zur Authentifizierung eines Datenlieferanten. Ohne Access-Token ist kein Upload möglich.
Ein Datenlieferant bekommt sein Access-Token zugeteilt.