WebUntisAPI for Java

This is a simlpe Java Library/API to access the RESTful JSON RCP WebService from Untis.

The jars in the 'builds' folder contain method and class documentation, which should be shown by your IDE after adding it to the classpath.

1. Installation

   • download latest build from builds folder / build latest version yourself
   • download JSON library http://jcenter.bintray.com/org/json/json/20151123/json-20151123.jar
   • add both .jar files to the build path of your project

2. Quick Use

   The usage of the library is based on the WebUntisConnection class. Note that it is abstract and must be extended by the user to be used properly. That is because method results of the API differ between customers of Untis and can therefore not be generalized. But I created a class that can be used as a template, it already implements certain methods of the Untis API. Note: these might not work for you instantly and requires further adaption.

   ApplicableWebUntisConnection connection = new ApplicableWebUntisConnection("school-sch", "poly", "username", "password");

   Note: The prefix (2. parameter) of the constructor is the sub-url you see in your browser when logging into the web interface of Untis. For example: https://poly.webuntis.com derives to "poly" as the desired prefix. This can change due to changes by Untis and also may vary between customers. After the creation of a WebUntisConnection instance, you may now call the WebUntisConnection#login() method to connect to the server:

   if(connection.login()) { System.out.println("Login successful!"); }

   Btw: It is recommended to create a single account with a simple password and read only permissions for use in this library, as sensitive data or passwords may be obtained by third parties through decompilation etc!

   One of the implemented methods in the ApplicableWebUntisConnection is the 'getTeachers' method. So let's invoke it. ArrayList<> teachers = connection.getTeachers(); The result can now be processed in any way you want.

   You should always call connection.logout() when you are finished calling methods to free server resources (as stated in the official WebUntis documentation).

3. Exception Handling

   When calling methods of the library, following exceptions may be thrown:

   WebUntisConnectionErrorException: Thrown when the server responded an error. #getCode(),#getErrorMessage(),#getError() may be used to get detailed information about the error.

   WebUntisConnectionFailureException: Thrown when there has been a problem connecting to the server

   WebUntisConnectionInvalidIDException: Thrown when a result-id does not match up with a request-id (should never happen)

   WebUntisConnectionResultException: Thrown when theres a problem with correctly parsing the result with the JSON library. This might be the case when Untis changed something in their WebAPI

   Code example:

    ApplicableWebUntisConnection connection = new ApplicableWebUntisConnection("school-sch", "poly", "username", "******");
    
    try
    {
    	if(connection.login())
    		System.out.println("Login Successful");
   
    	connection.getSubstitutions("20180212", "20181230");
    	
    	connection.logout();
    }catch(WebUntisConnectionErrorException e)
    {
    	if(e.getError() == WebUntisError.NO_RIGHT_FOR_METHOD)
    	{
    		System.out.println("Permissions need adjustment: " + e.getErrorMessage() + "(" + e.getCode() + ")");
    	}
    	else if(e.getError() == WebUntisError.METHOD_NOT_FOUND)
    	{
    		System.out.println("Seems like the API has changed!");
    	}
    }
   

4. Implementing own methods

   You might be interested to implement certain methods yourself, because the results differ to my implementation or I did not even implement that method yet. For that you need to extend the WebUntisConnection class:

    public class MyWebUntisConnection extends WebUntisConnection {
   
    public MyWebUntisConnection(String school, String prefix, String user, String password) {
    	super(school, prefix, user, password);
    }
   
    public ArrayList<Student> getStudents()
    {
    	String requestID = Utils.getRandomId(); //generate random id for the request
    	String result = getConnection().executeRequest("{\"id\":\""+requestID+"\",\"method\":\"getStudents\",\"params\":{},\"jsonrpc\":\"2.0\"}");
   
    	JSONObject resultData = preProcess(result, requestID); //handle common issues and catch result as JSONObject
   
    	ArrayList<Student> resultList = new ArrayList<Student>(); //ArrayList to accumulate the resulting student objects
   
    	JSONArray students = resultData.getJSONArray("result"); //grab JSONArray out of server result
    	for(int i = 0; i < students.length(); i++) //iterate through JSONArray
    	{
    		JSONObject student = students.getJSONObject(i); //fetch current student as JSONObject
    		resultList.add(new Student(student.getInt("id"), student.getString("name"), student.getString("foreName"), student.getString("longName"), Gender.valueOf(student.getString("gender").toUpperCase())));
    	}
    	return resultList;
    }
    }
   

   This is the basic structure of a method. You need a requestID by calling Utils.getRandomId(), then you can access the connection by calling getConnection() and execute requests with WebUntisHTTPConnector#executeRequest(String request). The result of an execution should be pre-processed by calling preProcess(String result, String requestID) with the used requestID. This method will handle common exception cases and return a JSONObject that can now be used to gather required information. The rest is up to you, depending on the method and your needs.

5. Feedback

   If you have any wishes/issues/difficulties, tell me!

6. License

   You are allowed to use this library to your needs. You can rebuild it for yourself or use one of the pre-builds. Commericial use is also allowed.