69_Webuntis: Beta-Modul zum Auslesen von Webuntis Stundenplänen

[KernSani]

Hallo liebe Gemeinde,
ich habe mal wieder gebastelt... Da beide Schulen meiner Kinder mittlerweile Webuntis zur Stundenplanverwaltung nutzen, habe ich ein rudimentäres Modul gebastelt, das die Stundenpläne ausliest und (insbesondere) Vertretungen/Entfall u.ä. darstellt. Das Modul läuft bei mir produktiv, ist aber sicher noch "early beta".

Kurzanleitung
mit

Code Auswählen Erweitern

define <meinWebuntis> Webuntis wird ein Device erstellt. Danach erstmal mit "set password" das Passwort deines Webuntis-Zugangs setzen und die Attribute server (über den du dich bei Webuntis einloggst, normalerweise sowas wie https://<griechischer Gott>.webuntis.com), school (steht auf der Login-Seite im URL-Paramter "?school=") und user (vermutlich deine EMail-Adresse) setzen.

Danach kann man mit 'get  retrieveClasses' alle Schulklassen der Schule einlesen und sie sich mit 'get Classes' anzeigen lassen. Die Schulklasse deines Kindes trägst du dann im Attribut "class" ein. Ein 'get timetable' holt dann die Daten für die kommenden 7 Tage, davon sieht mal allerdings noch nicht viel...
Der komplette Stundenplan ist i.d.r. uninteressant, was interessiert sind die Abweichungen vom normalen Stundenplan, daher werden nur readings erzeugt, wenn in einem der unter "exceptionIndicators" aufgeführten Felder ein Wert steht. Als default sollten alle (meiner Meinung nach) sinnvollen Felder bereits gepflegt sein.
Wenn da zuviel unnötiger Kram kommt kann man noch bestimmte Werte über das Attribut "exceptionFilter" rausfiltern, Das Attribut erwartet space-separierte key=value Paare, wobei "key" eines der Felder aus der exceptionIndicator-Liste ist und value eine regex. Bei mir steht da z.B.:

Code Auswählen Erweitern

lstext="2.HJ|1.HJ, 2.HJ"
Als Ergebnis sollte man readings e_01 - e_nn erhalten, die Abweichungen vom normalen Stundenplan enthalten. Pro Reading wieder alle enthaltenen Felder als key=value Paare. In den readings exceptionToday und exceptionTomorrow sind nochmal die Readingnamen der Exceptions für den jeweiligen Tag (also heute bzw. morgen) aufgeführt.

Zusätzlich gibt es noch eine "simpleTable" Funktion, mit der z.B. das Ergebnis in einem weblink dargestellt werden kann:

Code Auswählen Erweitern

FHEM::Webuntis::simpleTable("<Webuntis Device>") stellt alle Felder dar,
mit (beispielsweise)

Code Auswählen Erweitern

FHEM::Webuntis::simpleTable("<Webuntis device>","date,startTime,su:name,te:name,code,info,substText,lstype,lstext") werden nur die übergebenen Felder dargestellt.

Hinweis
Das Modul ist noch ziemlich neu und bestimmt nicht bugfree - vielleicht erstmal auf einem Testsystem damit spielen.

Hinweis 2
Die Erfahrung mit nur zwei Schulen zeigt, dass die Schulen Webuntis sehr unterschiedlich nutzen und die Ergebnisse und Inhalte dessen, was im Device und den Readings ankommt sehr unterschiedlich sein kann. Theoretisch kann Webuntis auch Klassenarbeiten, Hausaufgaben etc.. Ich bekomme dort aber bei keiner meiner Testschulen Ergebnisse - entweder weil sie nicht gepflegt sind, oder weil ich (über die öffentliche API) keine Berechtigung habe. Ich bin da noch am Forschen
Erfahrungen, Hinweise, Erweiterungswünsche etc... werden gerne angenommen.

Todo
* Darstellung des Ergebnisses verbessern
* Commandref überarbeiten
* Logging einbauen
* Plausi-/Syntaxprüfungen bei der Attributpflege

Updates
* 27.10.2023: Einige Bugfixes und neues Attribut "Exclude Subjects" um einzelne Fächer auszuschliessen (mich interessiert Französisch nicht, da mein Sohn Latein hat)

[slor]

Top! Nutzt die Schule meiner Tochter auch. Die mobile App ist auch eher mittelmäßig.
Mal sehen, was ich da rauskriege.
Wie schnell ist denn die Api bei Ausfällen? Kommt das in Echtzeit?

[KernSani]

Wie schnell ist denn die Api bei Ausfällen? Kommt das in Echtzeit?

Ich denke das kommt eher auf die Schule an, wie schnell die das pflegen Defaultmäßig ruft das Modul die Daten stündlich ab (kann über das "interval" Attribut angepasst werden).

[enno]

Moin KernSani,

Super Sache, ich bin dabei. Zwei Schulen mit drei Usern. Ich werde berichten

Nach einem Neustart von FHEM bekomme ich diesen Fehler:

Code Auswählen Erweitern

no such element elementId:null, elementType:1 nach manuellen  get "retrieveClasses" und  "timetable" ist wieder alles schön.

Gruss
  Enno

[CQuadrat]

Vielen Dank für das Modul!

Das Einrichten hat erstmal geklappt. 

Geht auch das Abfragen der Mitteilungen und der Klassenbucheinträge 

[enno]

* Darstellung des Ergebnisses verbessern

ist damit gedacht, auch auf mehrere Readings zu verteilen? Zur Zeit sieht das bei mir so aus:

Code Auswählen Erweitern

e_01  date="20230306" startTime="800" endTime="845" substText="Lesung" activityType="Unterricht" ro:longname="Klassenraum" ro:name="X3" su:longname="INFORMATIK" su:name="IT" te:longname="Einstein" te:name="AE"

Ich könnte mir das jetzt mit Userreadings umbauen, aber wenn du das schon in Planung hast, halte ich die Füsse still.

Code Auswählen Erweitern

e_01_date="20230306"
e_01_startTime="800"
e_01_endTime="845"
e_01_substText="Lesung"
e_01_activityType="Unterricht"
e_01_ro:longname="Klassenraum"
e_01_ro:name="X3"
e_01_su:longname="INFORMATIK"
e_01_su:name="IT"
e_01_te:longname="Einstein"
e_01_te:name="AE"

[Sailor]

Moinsen

Habe gerade einen Versuch gestartet und hat Prompt mein fhem-Server zum Absturz gebracht
Ich vermute "400 Bad Request" wird nicht vernünftig abgefangen und fuehrt somit zum Absturz.

Gruß
    Sailor

Code Auswählen Erweitern


2023.02.27 16:57:14.731 1: [UI_Webuntis] - Received invalid JSON: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "<html>\r\n<head><tit...") at .//FHEM/69_Webuntis.pm line 776.
$VAR1 = '<html>
<head><title>400 Bad Request</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<hr><center>nginx</center>
</body>
</html>
';

2023.02.27 16:57:14.793 1: PERL WARNING: Use of uninitialized value $v in pattern match (m//) at FHEM/HttpUtils.pm line 663.
2023.02.27 16:57:14.794 1: PERL WARNING: Use of uninitialized value $v in concatenation (.) or string at FHEM/HttpUtils.pm line 667.
2023.02.27 16:57:14.843 1: [UI_Webuntis] - Received invalid JSON: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "<html>\r\n<head><tit...") at .//FHEM/69_Webuntis.pm line 776.
$VAR1 = '<html>
<head><title>400 Bad Request</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<hr><center>nginx</center>
</body>
</html>
';

Can't use an undefined value as an ARRAY reference at .//FHEM/69_Webuntis.pm line 538.



[CQuadrat]

Kann man in dem Attribut class mehrere Klassen eintragen oder ist hier vorgesehen, dass jeweils ein Device angelegt wird?

[KernSani]

Ui, da sind ja gleich eine ganze Menge Leute dabei :-O

Nach einem Neustart von FHEM bekomme ich diesen Fehler:

Code Auswählen Erweitern

no such element elementId:null, elementType:1 nach manuellen  get "retrieveClasses" und  "timetable" ist wieder alles schön.

Ja, aktuell werden die Klassen nur in einem Hash vorgehalten, das wollte ich noch ändern

Geht auch das Abfragen der Mitteilungen und der Klassenbucheinträge 

Theoretisch kann ich das mit einbauen, kann es aber nicht vernünftig testen, weil da von meinen zwei Schulen nichts kommt...

ist damit gedacht, auch auf mehrere Readings zu verteilen? Zur Zeit sieht das bei mir so aus:

Code Auswählen Erweitern

e_01  date="20230306" startTime="800" endTime="845" substText="Lesung" activityType="Unterricht" ro:longname="Klassenraum" ro:name="X3" su:longname="INFORMATIK" su:name="IT" te:longname="Einstein" te:name="AE"

Ich könnte mir das jetzt mit Userreadings umbauen, aber wenn du das schon in Planung hast, halte ich die Füsse still.

Eigentlich wollte ich nicht von einer Unmenge an Readings erschlagen werden, wenn aber der generelle Wunsch ist, das so zu machen, dann baue ich das um (oder mache es per Attribut schaltbar) 

Habe gerade einen Versuch gestartet und hat Prompt mein fhem-Server zum Absturz gebracht
Ich vermute "400 Bad Request" wird nicht vernünftig abgefangen und fuehrt somit zum Absturz.

Huch, wie hast du denn das geschafft? EIgentlich wird abgefangen, wenn der BlockingCall einen Fehler zurück gibt... Schau ich mir nochmal an

Kann man in dem Attribut class mehrere Klassen eintragen oder ist hier vorgesehen, dass jeweils ein Device angelegt wird?

Je ein Device.

[Sailor]

Hallo KernSani

Entwickelst Du noch weiter.
Ich komme immer noch nicht weiter was das einloggen betrifft.

Code Auswählen Erweitern

2023.05.10 15:00:54.111 1: [UI_Webuntis_Leonardo] - Received invalid JSON: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "<html>\r\n<head><tit...") at .//FHEM/69_Webuntis.pm line 776.
$VAR1 = '<html>
<head><title>400 Bad Request</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<hr><center>nginx</center>
</body>
</html>
';

2023.05.10 15:00:54.328 1: PERL WARNING: Use of uninitialized value $v in pattern match (m//) at FHEM/HttpUtils.pm line 682.
2023.05.10 15:00:54.328 1: PERL WARNING: Use of uninitialized value $v in concatenation (.) or string at FHEM/HttpUtils.pm line 686.
2023.05.10 15:00:55.645 1: [UI_Webuntis_Leonardo] - Received invalid JSON: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "<html>\r\n<head><tit...") at .//FHEM/69_Webuntis.pm line 776.
$VAR1 = '<html>
<head><title>400 Bad Request</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<hr><center>nginx</center>
</body>
</html>
';

Can't use an undefined value as an ARRAY reference at .//FHEM/69_Webuntis.pm line 538.

Gruß
    Sailor

[eddy242]

Hallo KernSani,

unsere Schulen haben die Authentifizierung mit O365 aktiviert. Wenn man auf der Profilseite die Verknüpfung zur Mobile App aktiviert, wird ein QR Code angezeigt, darunter ein Alias-Benutzername und ein Schlüssel. Damit scheint sich die Mobile App am Webuntis Webserver zu authentifizieren (ohne den Umweg über die O365-Authentifizierung). Allerdings klappt das naheliegende leider nicht, also den angezeigten Usernamen und den Schlüssel in den Attributen Deines Moduls einzutragen. Bist Du darüber vielleicht schon gestolpert? Dr. Google zeigt ja eine Menge Doku zur Webuntis-3rd-Party API Integration an, das ist mir aber zu hoch, um durchzusteigen.

Danke & Grüße

[masterpete23]

Hi,

ich teste es gerade zum ersten Mal.

Kommt bei Server asopo.webuntis.com oder dann nur asopo rein?

Ich bekomme mit beiden Versionen einen Fehler. Auch bei School bin ich mir nicht sicher

die Url der Webseite ist : https://asopo.webuntis.com/WebUntis/?school=IGS+NAMEdesOrts#/basic/login

wie muss die school dann heißen? "IGS+NAMEdesOrts" oder "IGS NAMEdesOrts"?

Auch die E-Mail Adresse ist vorname.nachname@namederschule-gs.de

der Login auf der webuntis seite ist nur vorname.name ohne das @und dem dahinter

Code Auswählen Erweitern

error
asopo.webuntis.com/WebUntis/jsonrpc.do?school=IGS+NAMEdesOrts: malformed or unsupported URL
Leider mit allen Kombinationen nur Fehler.

[masterpete23]

Nachtrag. Lösung gefunden
Aber nachdem ich die class gesetzt habe und den Timetable ziehen wollte ist fhem abgestürzt:

Code Auswählen Erweitern

2023.09.21 16:58:49 1: [Webuntis] - Received invalid JSON: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "<html>\r\n<head><tit...") at ./FHEM/69_Webuntis.pm line 776.
$VAR1 = '<html>
<head><title>400 Bad Request</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<hr><center>nginx</center>
</body>
</html>
';

Can't use an undefined value as an ARRAY reference at ./FHEM/69_Webuntis.pm line 584.


[KernSani]

Hallo zusammen,
ich bin leider ein bisschen ins Frühlings- und Sommerloch gefallen, aber jetzt da die Tage kürzer und der Regen häufiger werden, werde ich hier mal wieder ein bisschen aktiv. Ich habe im letzten halben Jahr immer mal wieder für mich ein paar kleinere Bugs gefixt (z.B. die Geschichte, dass nach einem Neustart die Klassen weg waren und der Stundenplan nicht geladen werden konnte). Die aktuelle Version hängt jetzt am ersten Post. Ich hoffe, die behebt den größten Teil der gemeldeten Fehler. Wenn nicht, bitte hier melden, dann schaue ich mir das an.
Grüße,
Oli

[KernSani]

Da es noch Fragen zu Server, Anmeldung etc... gab.
Als Server ist der gesamte Servername anzugeben: https://<griechischer Gott>.webuntis.com
und da ein Bild mehr sagt als 1000 Worte: Das was unten in der roten Box steht ist der Schulname (da können auch url-encodete Sonderzeichen drinstehen).
Zumindest bei meiner Schule (da mittlerweile beide Kinder auf die selbe Schule gehen, habe ich nur noch eine "Testschule") wird als Login die komplette Email-Adresse verwendet (und ich habe die Auswahl zwischen Office365 und direktem Login - Office365 ist das was die Kinder verwenden, der Elternzugang ist ohne O365), das hängt aber vermutlich jeweils von der Schule ab. Da bräuchte ich dann ggf. mal per PM ein paar Details um mir das anzusehen...
Grüße,
Oli