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

1. Install WebUntis2 from the ioBroker adapter list.
2. Create a new webuntis2 instance.
3. Search for your school by entering part of its name or a city.
4. Select the matching school from the results.
5. Enter the WebUntis username and password.
6. 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.