A simple interface for accessing the webuntis API
-
create a new node.js project
npm init -
install the api
npm install --save untis-api -
write something like this in your main.js
const w = require("untis-api"); const e = w.entities; w.connect("username", "password", "school", "borys").then(() => { w.getTeachers().then(teachers => { console.log(teachers); }); w.logOut(); });
-
execute the main.js file
node main.js
A Promise that is either resolved if the connection was successful or rejected if it wasn't.
w.connect("username", "password", "school", "servername");- Username, Password, Schoolname and Servername as Strings
- An object containing the login information in the following structure
{ "schoolName": "school", "username": "username", "password": "password", "servername": "borys", }
Calls the logout method on the untis server to invalidate the connection
w.logout();Contains information about the currently logged in user and the session.
Will not work if w.connect() hasn't completed yet.
w.info;a Javascript Object containing said information
{
klasseId: 157,
personId: 238,
personType: 5,
sessionId: 'FD42A62B33A83B7C777200CBF62895C4'
}w.getTeachers().then(data => console.log(data));An Array of all teachers in the school
[{
"id": 1,
"name": "TEAC",
"foreName": "Bob",
"longName": "Teacher",
"title": "",
"active": true,
"dids": [
{
"id": 6
}
]
}]w.getClasses().then(data => console.log(data)); //or: w.getKlassen();An Array of all classes in the school
[{
"id": 1,
"name": "1AHIF",
"longName": "LongName",
"active": true,
"did": 6
}]w.getSubjects().then(data => console.log(data));An Array of all subjects
[{
"id": 1,
"name": "AC",
"longName": "Applied Chemistry",
"alternateName": "ACH",
"active": true
}]w.getRooms().then(data => console.log(data));An Array of all rooms
[{
"id": 1,
"name": "EDV1",
"longName": "EDV1",
"active": true,
"building": "main"
}]w.getDepartments().then(data => console.log(data));An Array of all departments
[{
"id": 1,
"name": "BE",
"longName": "Biomedical Engineering"
}]w.getHolidays().then(data => console.log(data));An Array of all rooms
[{
"id": 16,
"name": "Holidays_1",
"longName": "Christmas",
"startDate": 20161224,
"endDate": 20170108
}]w.getStatusData().then(data => console.log(data));A Javascript Object containing information about which color lesson types and codes should be displayed in
{
"lstypes": [
{
"ls": {
"foreColor": "000000",
"backColor": "f49f25"
}
}
],
"codes": [
{
"cancelled": {
"foreColor": "000000",
"backColor": "b1b3b4"
}
}
]
}w.getTimegridUnits().then(data => console.log(data));An Array of days that show when each lesson starts and ends
[{
"day": 2,
"timeUnits": [
{
"name": "1",
"startTime": 800,
"endTime": 850
},
{
"name": "2",
"startTime": 855,
"endTime": 945
},
{
"name": "3",
"startTime": 1000,
"endTime": 1050
}
]
}]w.getCurrentSchoolYear().then(data => console.log(data));A Javascript Object containing information about the current school year's start and end dates
{
"id": 2,
"name": "2016/2017",
"startDate": 20160912,
"endDate": 20170709
}Same as getCurrentSchoolYear but with an array instead of just a single Object
TimeTableEntity = require("untis-api").Entities.TimeTableEntity;
w.getTimetable(new TimeTableEntity(1, 5)).then(data => console.log(data));getTimetable(tte)
- tte: a TimeTableEntity containing the person whose timetable you want to watch's id and personType
A lot of data, better see for yourself...
TimeTableEntity = require("untis-api").Entities.TimeTableEntity;
w.getCustomTimetable(new TimeTableEntity(1, 5), {
showSubstText: true,
showLsText: true,
klasseFields: ["name"],
roomFields: ["name"],
subjectFields: ["name"]
}).then(data => console.log(data));getCustomTimetable(tte, paramsObject)
- tte: a TimeTableEntity containing the person whose timetable you want to watch's id and personType
- paramsObject: a Object with all custom parameters as properties of this object with their respective value
- startDate: number, format: YYYYMMDD, optional (default: monday of this week)
- endDate: number, format: YYYYMMDD, optional (default: friday of this week)
- showBooking: boolean, returns the period's booking info if available (default: false)
- showInfo: boolean, returns the period information if available (default: false)
- showSubstText: boolean, returns the Untis substitution text if available (default: false)
- showLsText: boolean, returns the text of the period's lesson (default: false)
- showLsNumber: boolean, returns the number of the period's lesson (default: false)
- showStudentgroup: boolean, returns the name(s) of the studentgroup(s) (default: false)
- klasseFields: array, optional, values: „id“, „name“, „longname“, „externalkey“
- roomFields: array, optional, values: „id“, „name“, „longname“, „externalkey“
- subjectFields: array, optional, values: „id“, „name“, „longname“, „externalkey“
- teacherFields: array, optional, values: „id“, „name“, „longname“, „externalkey“
If a Fields parameter (e.g. „teacherFields“) is not set explicitly, the return object will contain the internal id („keyType“: „id“) of the references (e.g. the teachers of a period) by default.
A lot of data, better see for yourself...
w.searchPerson(5, "firstName", "lastName", 0).then(data => console.log(data));searchPerson(<personType>, <firstName>, <lastName>, <dateOfBirth>)
- personType: type of the person:
2for teacher or5for pupil - firstName
- lastName
- dateOfBirth: dob of the person to search for, or
0if unknown
The id of the person if the search was successful.
If it wasn't, 0 is returned