untis-api v0.1.3

Untis-API

A simple interface for accessing the webuntis API

Setup

• 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

API Methods

connect

Returns

A Promise that is either resolved if the connection was successful or rejected if it wasn't.

Usage

w.connect("username", "password", "school", "servername");

Parameters

• 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",
  }

logout

Calls the logout method on the untis server to invalidate the connection

Usage

w.logout();

info

Contains information about the currently logged in user and the session.

Will not work if w.connect() hasn't completed yet.

Usage

w.info;

Returns

a Javascript Object containing said information

{
  klasseId: 157,
  personId: 238,
  personType: 5,
  sessionId: 'FD42A62B33A83B7C777200CBF62895C4'
}

getTeachers

Usage

w.getTeachers().then(data => console.log(data));

Returns

An Array of all teachers in the school

[{
  "id": 1,
  "name": "TEAC",
  "foreName": "Bob",
  "longName": "Teacher",
  "title": "",
  "active": true,
  "dids": [
    {
      "id": 6
    }
  ]
}]

getClasses

Usage

w.getClasses().then(data => console.log(data)); //or: w.getKlassen();

Returns

An Array of all classes in the school

[{
  "id": 1,
  "name": "1AHIF",
  "longName": "LongName",
  "active": true,
  "did": 6
}]

getSubjects

Usage

w.getSubjects().then(data => console.log(data));

Returns

An Array of all subjects

[{
  "id": 1,
  "name": "AC",
  "longName": "Applied Chemistry",
  "alternateName": "ACH",
  "active": true
}]

getRooms

Usage

w.getRooms().then(data => console.log(data));

Returns

An Array of all rooms

[{
  "id": 1,
  "name": "EDV1",
  "longName": "EDV1",
  "active": true,
  "building": "main"
}]

getDepartments

Usage

w.getDepartments().then(data => console.log(data));

Returns

An Array of all departments

[{
  "id": 1,
  "name": "BE",
  "longName": "Biomedical Engineering"
}]

getHolidays

Usage

w.getHolidays().then(data => console.log(data));

Returns

An Array of all rooms

[{
  "id": 16,
  "name": "Holidays_1",
  "longName": "Christmas",
  "startDate": 20161224,
  "endDate": 20170108
}]

getStatusData

Usage

w.getStatusData().then(data => console.log(data));

Returns

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"
      }
    }
  ]
}

getTimegridUnits

Usage

w.getTimegridUnits().then(data => console.log(data));

Returns

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
    }
  ]
}]

getCurrentSchoolYear

Usage

w.getCurrentSchoolYear().then(data => console.log(data));

Returns

A Javascript Object containing information about the current school year's start and end dates

{
  "id": 2,
  "name": "2016/2017",
  "startDate": 20160912,
  "endDate": 20170709
}

getSchoolYears

Same as getCurrentSchoolYear but with an array instead of just a single Object

getTimetable

Usage

TimeTableEntity = require("untis-api").Entities.TimeTableEntity;

w.getTimetable(new TimeTableEntity(1, 5)).then(data => console.log(data));

Parameters

getTimetable(tte)

• tte: a TimeTableEntity containing the person whose timetable you want to watch's id and personType

Returns

A lot of data, better see for yourself...

getCustomTimetable

Usage

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));

Parameters

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

Valid properties:

• 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.

Returns

A lot of data, better see for yourself...

searchPerson

Usage

w.searchPerson(5, "firstName", "lastName", 0).then(data => console.log(data));

Parameters

searchPerson(<personType>, <firstName>, <lastName>, <dateOfBirth>)

• personType: type of the person: 2for teacher or 5for pupil
• firstName
• lastName
• dateOfBirth: dob of the person to search for, or 0 if unknown

Returns

The id of the person if the search was successful.

If it wasn't, 0 is returned