Schnittstelle für den Upload aus Programmen für Vertretungsplänen

Die folgende Anleitung ist nicht für Schulen sondern für Anbieter entsprechender Vertretungsplan- bzw. Stundenplansoftware gedacht.

Grundlagen

• Schulen sollen die Hoheit darüber behalten, wann der Vertretungsplan veröffentlich wird. Daher soll der Upload zu uns nicht automatisch passieren, sondern durch eine aktive Aktion des Benutzers ausgelöst werden (bspw. Klick auf einen gut platzierten Button).
• Pro Tag sind maximal 50 Uploads möglich.
• Es können immer nur vollständige Pläne und nicht nur Änderungen übertragen werden.
• Die Schulen müssen einstellen können, was veröffentlicht werden soll: Alle bereits schon eingetragenen zukünftigen Vertretungen, nur heute und morgen, die nächsten drei Tage, etc..
• Jede Schule hat eine Schulnummer und einen Uploadkey. Dieser stellt den Schlüssel dar, um einen Upload für diese Schule überhaupt vornehmen zu können. Daher sollte dieser besonders geschützt gespeichert werden (gleichzeitig bedeutet dies aber auch, dass jede Schule ihre Schulnummer und diesen Uploadkey in den Einstellungen hinterlegen können muss).
• Wir empfehlen auch die URL für den Upload durch den Anwender einstellbar zu machen, um auf mögliche zukünftige Änderungen schnell reagieren zu können (aktuell: "https://start.schulportal.hessen.de/vertretungsplan.php").

Ablauf

• Der Vertretungsplan wird in drei Schritten hochgeladen:

1. Sperrung des Planes für den neuen Upload
2. Übertragung der Daten
3. Beendigung des Uploads und Freigabe des Planes

Prinzipiell stehen verschiedene Uploadformate zur Verfügung, mit denen wir serverseitig umgehen können. Wir empfehlen die Umsetzung als CSV-Datei mit Lehrerkürzeln (Beispieldatei und weitere Erläuterungen in → ID 477). Die im Folgenden zu benutzende Art ist dann "csv-Kuerzel". Sperrung des Planes für neuen Upload per POST-Aufruf der URL mit den Parametern:

• i=Schulnummer
• c=Uploadkey
• a=Art
• upload=1
• reset=1

Übertragung der Daten per POST-Aufruf der URL mit den Parametern:

• i=Schulnummer

• c=Uploadkey
• a=Art
• upload=1
• d=CSV-Datei (codiert wie bei Absendung einer Form in HTML)

Sollen mehrere Dateien für eine Schule übertragen werden, so kann der letzte Aufruf auch mehrfach durchgeführt werden. Nachdem alle Dateien hochgeladen wurden: Beendigung des Uploads und Freigabe des Plans per POST-Aufruf der URL mit den Parametern:

• i=Schulnummer

• c=Uploadkey
• a=Art
• upload=1
• unlock=1

Bei Schwierigkeiten und Rückfragen stehen wir gerne zur Verfügung.