Resource Schools

The Schools resource is represented in the LDAP tree as an OU.

To list those LDAP objects run:

$ univention-ldapsearch -LLL "objectClass=ucsschoolOrganizationalUnit"

UCS@school uses the UDM REST API which in turn uses UDM to access LDAP. UDM properties have different names than their associated LDAP attributes. Their values may also differ. To list the same UDM objects run:

$ udm container/ou list --filter "objectClass=ucsschoolOrganizationalUnit"

All UCS@school objects exist below an OU and have that OUs name as the school attributes value. Staff, students and teachers may attend or work at multiple schools. So User objects have an additional schools attribute, that is a list of all schools a user belongs to.

Currently the Schools resource does only support listing and creating objects. It does not yet support modifying or deleting OUs.

Resource representation

The following JSON is an example Schools resource in the UCS@school Kelvin REST API:

{
    "dn": "ou=test,dc=uni,dc=ven",
    "url": "https://<fqdn>/ucsschool/kelvin/v1/schools/test",
    "ucsschool_roles": ["school:school:test"],
    "name": "test",
    "display_name": "Test School",
    "educational_servers": ["dctest-01"],
    "administrative_servers": [],
    "class_share_file_server": "dctest-01",
    "home_share_file_server": "dctest-01",
    "udm_properties": {}
}
Property description
name value Description Notes
dn string The DN of the OU in LDAP. read only
url URL The URL of the role object in the UCS@school Kelvin API. read only
ucsschool_roles list List of roles the OU has. Format is ROLE:CONTEXT_TYPE:CONTEXT, for example: ["school:school:gym1"]. auto-managed by system, setting and changing discouraged
name string The name of the school (technically: the name of the OU). read only
display_name string The name of the school (for views).  
educational_servers list List of server host names for the educational school network. (*)
administrative_servers list List of server host names for the administrative school network. (*)
class_share_file_server string Host name of server with the class shares. if unset: the schools educational server, (*)
home_share_file_server string Host name of server with the home shares. if unset: the schools educational server, (*)
udm_properties nested object Object with UDM properties. For example: {"description": "Gymnasium"} Must be configured, see below.

(*) API CHANGE: before version 1.4.0 this was a DN or list of DNs

udm_properties

The attribute udm_properties is an object that can contain arbitrary UDM properties. It must be configured in the file /etc/ucsschool/kelvin/mapped_udm_properties.json, see UDM Properties.

Attention: Due to the technical way schools are created, udm_properties are set after the initial creation of the school. This can lead to a school being created with an error following the subsequent alteration. In this case the Kelvin API returns a 500 status code, but the school was created anyways.

Retrieve

Example curl command to retrieve a single school (OU):

$ curl -X GET "https://<fqdn>/ucsschool/kelvin/v1/schools/demoschool" \
    -H "accept: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...."

With the search being case-insensitive, this matches an OU named DEMOSCHOOL. The response body will be the first element of the list in the search example above.

Create

Since version 1.4.0 of the UCS@school Kelvin REST API app it is possible to create school objects (OUs).

When creating a school, two attributes must be set:

  • name
  • display_name

As an example, with the following being the content of /tmp/create_ou.json:

{
    "name": "example",
    "display_name": "Example School"
}

This curl command will create a school from the above data:

$ curl -i -k -X POST "https://<fqdn>/ucsschool/kelvin/v1/schools/" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...." \
    -d "$(</tmp/create_ou.json)"

Response headers:

HTTP/1.1 201 Created
Date: Mon, 26 Mar 2021 13:10:00 GMT
Server: uvicorn
content-length: 335
content-type: application/json
Via: 1.1 <fqdn>

Response body:

{
    "dn": "ou=Example,dc=uni,dc=ven",
    "url": "https://<fqdn>/ucsschool/kelvin/v1/schools/Example",
    "ucsschool_roles": ["school:school:Example"],
    "name": "Example",
    "display_name": "Example School",
    "educational_servers": ["dcExample"],
    "administrative_servers": [],
    "class_share_file_server": "dcExample",
    "home_share_file_server": "dcExample"
}

Modify / Move

Currently not supported.

Delete

Currently not supported.