Test Adapter webuntis2 version 0.3.x

Voodoo2man

Aktuelle Test Version	0.3.0
Veröffentlichungsdatum	02.11.2026
Github Link	https://github.com/Voodoo2man/ioBroker.webuntis2

ioBroker.webuntis2

WebUntis2 connects ioBroker with WebUntis. It retrieves timetables for a
student or family account and makes them available in ioBroker for
visualizations, notifications, and automations.

What the adapter provides

School search by school name, city, or address
Simple school selection during setup
Secure username and password configuration
A connection test before saving
Timetables for today, tomorrow, and the current week
Lesson details such as subject, teacher, room, class, time, and status, with available long names in additional states
Information about changes, substitutions, and cancelled lessons
Daily summaries with lesson counts, school times, subjects, and changes
Current and next lesson information, including the remaining time
Current and upcoming school holidays
Upcoming exams, including subject, date, and start and end times
Homework for reliably identified students, with due dates, completion status, and attachments
Student absences and excuse status, including unknown status values
Messages of the day, including subject, text, and attachment indicators
Timetables, holidays, inbox messages, messages of the day, homework, absences, and exams refresh every five minutes
Current and next lesson values refresh every minute

Installation and setup

Install WebUntis2 from the ioBroker adapter list.
Create a new webuntis2 instance.
Search for your school by entering part of its name or a city.
Select the matching school from the results.
Enter the WebUntis username and password.
Use Test connection and save the settings.

The adapter stores the selected school together with the information required
for the connection. No server address needs to be entered manually when it is
provided by the school search.

Admin configuration interface

The adapter uses a React-based Admin interface because setup includes two
interactive operations: searching WebUntis schools from a user-entered query
and displaying the returned schools for selection, and testing the entered
credentials against the selected school before saving. Both operations call
the adapter asynchronously and need to show loading, empty-result, and error
states in the same form. The standard jsonConfig controls do not provide
this complete query-and-result workflow on their own; reproducing it there
would require a custom component or equivalent custom UI code. React keeps
these setup interactions together while the adapter remains responsible for
WebUntis requests and validation.

Data in ioBroker

The instance tree has four top-level channels: students, holidays, inbox,
and info. The adapter reads the account type from WebUntis automatically and
reports it in the info.accountType state as Student, Parent, or Other.

Each student has a channel below students.<name>. The channel ID is
based on the student's name, normalized for ioBroker IDs; duplicate normalized
names are disambiguated with the WebUntis student ID. If WebUntis provides no
student name, the ID is used as a fallback. Timetables are available at
students.<name>.timetable.today,
students.<name>.timetable.tomorrow, and
students.<name>.timetable.week. Each lesson contains readable values
for the subject, teacher, room, class, start and end time, and lesson status.
Lesson startTime and endTime are strings with the time role.

Daily summaries show whether there is school, the number and duration of
lessons, the first and last lesson, the subjects in timetable order, and
changes or cancellations. Each day channel also contains a lessonComparison
JSON array with the lesson number, original and actual subject, teacher, room,
and status. The lesson number reflects the position in the daily list. Original
and actual start/end times are currently identical. The info section contains
connection status, account type, and update information. Holiday information
is available below holidays.

For a WebUntis parent account, WebUntis supplies each linked student's ID and
name; the adapter creates the same students.<name> structure
automatically. Each student's timetable includes lesson details, daily
summaries, and current/next lesson values. Exams are available under
students.<name>.exams, including a JSON array and numbered entry
channels. Holidays and messages remain account-level data because WebUntis does
not associate those responses with an individual student.

Messages are available directly below inbox.unread and inbox.read. Each
message has a numbered channel ordered by its arrival time. inbox.unread.count
gives the number of unread message channels. inbox.read.count gives the number
of read message channels. Message channels include the date/time, sender,
subject, content, and an attachment indicator. The adapter retrieves full content when the WebUntis
endpoint permits it and otherwise uses the available preview; the
contentIsPreview property distinguishes the two.

The Read (local or WebUntis) state is the effective status and is true when
a message was marked read locally or WebUntis reports it as read.
readInWebUntis contains only the status reported by WebUntis.

Press markAsUnread on a message in inbox.read to move it back to
inbox.unread when WebUntis still reports it as unread. Messages already read
in WebUntis remain in inbox.read.

The info.refresh button runs the complete startup refresh immediately:
timetable, inbox messages, messages of the day, homework, absences, exams,
holidays, cleanup, and derived current/next lesson states.

Messages of the day are available under newsOfDay.today. The date and
count states identify the date and number of messages. The json state at
newsOfDay.today.json contains the complete message list as a JSON array. Each
message also has a numbered channel (01, 02, ...) with id, subject,
text, and hasAttachments states. The list is refreshed every five minutes and through
info.refresh. A failed request preserves the last successful data, while a
successful empty response sets the count to zero and removes obsolete message
channels.

Upcoming exams are available below each student's exams channel.
students.<name>.exams.count gives the number of exams announced in the
requested date window, students.<name>.exams.upcoming contains a JSON
array, and students.<name>.exams.upcomingText joins the display text
for that student's exams with newlines. Each exam also has a sequentially
numbered channel such as students.<name>.exams.entries.01 or
students.<name>.exams.entries.02. Exams are ordered by date, start time,
then WebUntis ID, so multiple exams on the same date or in the same subject
remain separate. The channel numbers can change when the ordered exam list
changes; use the id field to identify an exam across updates. The array
contains the following fields:

[
	{
		"id": 4102,
		"displayText": "05.11.2026 · 08:00–09:30 · Mathematik · Kapitel 4, Aufgaben 1–6"
	},
	{
		"subject": "Englisch",
		"date": "2026-11-05",
		"startTime": "10:00",
		"text": "Unit 3",
		"displayText": "05.11.2026 · 10:00–10:45 · Englisch · Unit 3"
	}
]

The individual entries.<NN> channels expose id as a number.
Availability depends on the WebUntis account's school permissions and API
scope. A failed or forbidden request leaves the last successful exam data in
place; a successful response with no exams clears stale entries. Exam data
does not include grades or student personal details. If the cookie-authenticated
exam request is forbidden, the adapter retries it once with its REST token.
For parent accounts, the adapter loads the linked students from WebUntis app
data and reads each student's timetable, so identical exams remain separate
and are attributed to the correct child. School permissions can still deny
access to one or more child timetables; a failed refresh preserves the last
successful data.

Homework and absences

Homework and absences are refreshed at startup and with the regular refresh cycle.
They are also included when info.refresh is triggered. Their data is kept under
students.<student> so linked students in parent accounts remain separate. The
adapter uses the account's own student ID for student accounts and the linked
student IDs returned by WebUntis for parent accounts.

students.<student>.homework contains count, openCount,
completedCount and unknownCount, followed by numbered entries with the
homework ID, linked lesson ID, subject and teacher when available, date, due
date, text, remark, completion status and attachment indicator.
homework.unassigned contains account-level homework that cannot be linked to
a student. Homework without an explicit student reference is assigned only when
exactly one student identity is known; with none or multiple known students, it
remains unassigned. The adapter does not guess by matching subject or teacher
names; the channel has the same count fields as student homework channels.
students.<student>.absences is a channel containing numbered absence
channels (01, 02, and so on). Each record has exactly these nine read-only
states: startDate, endDate, startTime, endTime, reason,
excuseStatus, excuseStatusKnown, excuseText, and isExcused.
students.<student>.absences.json contains the same records as a JSON array.
Every record object has exactly the nine keys listed above. An unclear excuse
status is represented as unknown and is never inferred as unexcused.

These areas are read-only. Access depends on the school's WebUntis permissions.
A failed or forbidden request preserves the last successful data, while a valid
empty result clears stale entries. The homework endpoint may be scoped to the
school year bound to the current WebUntis session; the adapter does not change
that shared session's school year.

Requirements and notes

Node.js 22.19 or newer, js-controller 7.2.2 or newer, and Admin 8.2.0 or newer are required.
A WebUntis account with access to the selected school is required.
Username-and-password login is supported.
QR-code, Microsoft 365, SAML, and OAuth login are not supported.
Homework is read from WebUntis for the active session school year. The adapter does not switch the shared session to another school year; if that context cannot be validated, it preserves the previous homework data.
WebUntis is an external service. This project is
independent and is not affiliated with Untis GmbH.

Privacy and security

The password is stored using ioBroker's protected configuration mechanism.
Credentials, cookies, and session information are not shown in logs or
published as states. Do not share login details or personal student information
in issues or support requests.

Support

If the connection does not work, check the selected school and WebUntis login
in a browser first. Then run the connection test in the adapter configuration
and include only relevant, non-sensitive log messages when asking for help.

Changelog

0.3.0 (2026-11-02)

(Voodoo2man) Added messages of the day
(Voodoo2man) Added homework data
(Voodoo2man) Added absence records

0.2.2 (2026-11-02)

(Voodoo2man) Added support for Node.js 22.19 and newer while retaining Node.js 24 and 26 CI coverage.
(Voodoo2man) Resolved the reported qs and minimatch development-dependency alerts.

0.2.1 (2026-10-28)

(Voodoo2man) Moved read and unread messages directly under inbox, renamed the unread count state to inbox.unread.count, and removed the redundant JSON state.
(Voodoo2man) Kept inbox refresh independent of timetable failures and replaced the local read toggle with a mark-as-unread button.

0.2.0 (2026-10-25)

(Voodoo2man) Raised the minimum Node.js, js-controller, and Admin requirements.
(Voodoo2man) Added the Ukrainian Admin translation.
(Voodoo2man) Added multi Student support and structure.
(Voodoo2man) Added upcoming exams
(Voodoo2man) Added read and unread inbox messages
(Voodoo2man) Added a manual full refresh button
(Voodoo2man) Improved timetable details
(Voodoo2man) Removed duplicate date states.

0.1.10 (2026-10-18)

(Voodoo2man) Improved configuration feedback, holiday names, and connection status; reduced routine login log messages; verified Node.js 26 compatibility; and migrated Dependabot auto-merging to the pull_request event.

0.1.9 (2026-10-15)

(Voodoo2man) Improved timetable data and reliability with comparisons, long names, and automatic re-authentication for expired sessions
(Voodoo2man) Added an inbox for unread messages.

buflug453

@voodoo2man
Ich erhalte nach Update auf node.js 24 und 0.2.1 folgende Meldung:

error	startInstance webuntis2.0: cannot find start file!

mcm1957

@buflug453 said:

@voodoo2man
Ich erhalte nach Update auf node.js 24 und 0.2.1 folgende Meldung:
error	startInstance webuntis2.0: cannot find start file!

Bist du sicher dass du nicht versucht hast von Github zu installieren? Sieht für mich danach aus ...

Thomas Braun

@mcm1957

Vielleicht sollte 'die Katze' im Tierheim abgegeben werden...
Also aus dem Admin-GUI raus.

mcm1957

Na ja - mitten in der kalten Jahreszeit wär das tierfeindlich :-)

Außerdem - falls die Vermutung richtig is t- sollte der Adapter ger nicht via Katze installierbar sein, da er brac als nogit markiert ist. Über cli gehts aber immer, da dort (grob gesagt) nur die url an npm weitergereicht wird udn Prüfungen der adminUI naturgemäß nicht stattfinden. Siehe auch https://github.com/ioBroker/ioBroker.js-controller/issues/3119

mcm1957

Weiters hab ich angeregt die Fehlermeldung zu verbessern:
https://github.com/ioBroker/ioBroker.js-controller/issues/3575

mcm1957

Und ja - install from github könnte man im Katzenhome auch entfernen. Wer wirklich von Github installieren will, kann die url wohl auch ganz tippen. Und die Dropdownlist greift im worst case sogar in ein ganz anderes Repo als erwartet (z.B. weil ich einen Fork von GitHub installieren muss ...)

Voodoo2man

@buflug453 Hat die Installation jetzt funktioniert?

buflug453

@voodoo2man

Screenshot 2026-11-02 085727.png
In der Adapterliste taucht es bei mir nicht auf.
Ich hatte zuvor direkt über github installiert.

Voodoo2man

Der Adapter ist noch nicht im Stable.
Entweder über die iobroker Einstellungen auf Beta umstellen. Dann wird der Adapter gefunden.

,oder über npm installieren

buflug453

Danke, 0.3.0 wurde installiert. Werde weiter testen und berichten, falls mir etwas auffällt.
Vielen Dank für den Adapter und die Zeit, die du hier investierst.

mading

@voodooman wow, danke! Installation (über Benutzerdefiniert und webuntis2@latest) hat wunderbar funktioniert, die Daten kommen an. Ich hatte mich mit einem Webuntis Screenshot (sh. Webuntis Adapter Thread ) beholfen. Eine Frage: im alten Adapter wurden die Unterordner für die Stunden nur dann erstellt für den jeweiligen Tag, wenn eine Schulstunde existierte, d.h. wenn ich ein Blockly nutzen möchte, brauche ich ja eine Referenz (was nicht geht wenn der Ordner existiert). Hast du hier einen Tipp wie ich zb auch in einer Tabelle in vis die Daten anzeigen lasse (im worst case steht eine {…}-Referenz in der vis-Tabelle, was ja nicht so schön ist.

Danke nochmal, tolle Arbeit!

Voodoo2man

@mading
Die "lessons" Channels (Ordner) sind dynamisch und werden je nach Tag angelegt oder automatisch wieder gelöscht.
Die Anzahl Stunden pro Tag (was ja dann auch den Channels entspricht) bekommst du aus dem lessonCount Datenpunkt.
Daraus sollte sich was bauen lassen.
Gerne implementiere ich auch noch zusätzliche Datenpunkte wenn es hilfreich ist.

mading

Hi @voodoo2man,

danke! Geschickt wäre ein JSON je Tag, so dass auch optisch ersichtlich wird, wenn etwas ausfällt (entweder die Stunde dann leer oder ebenfalls durchgestrichen/ rot markiert?).

Auf Untis sieht es im Vergleich so aus:

Voodoo2man

@mading
Schau dir mal den Datenpunkt an:
webuntis2.x.students.xxx.timetable.today.lessonComparison
Darin hatte ich schon einen Vergleich eingebaut.
Falls der noch nicht passt, ändere ich ihn gerne nochmal.

mading

Hi Voodoo2man,

evtl. habe ich einen Denkfehler, ich kann aber mit einer json Tabelle nicht auf die Werte zugreifen. Füge ich zb actual.startTime in das Feld "Attribut in JSON [1], wird undefined angezeigt.

Das weitere Problem wird dann vermutlich sein, dass eine vis json Tabelle nur einen Wert je Zelle in der Tabelle anzeigen kann und es geschickt wäre (wie oben im Screenshot gezeigt), dass man optisch farblich markiert sieht was ausfällt und was neu ist.

Community Forum

NEWS