Custom Room Availability

Purpose

When UniTime event management is not used, but information about room availability is needed for course and/or examination timetabling, a custom room availability interface can be used. It is based on a simple XML format (see request XML, response XML, DTD).

Details

When room availability is requested within UniTime (e.g., while input data are being loaded into the course or examination solver), a request XML file is generated. It contains information about the current academic session (year, term, and campus) and about a time frame of the requested availability (starting and end date, starting and end time). When the request XML file appears, an appropriate response XML should be generated by the external system. It contains information about all the relevant rooms and their events in the given time frame. The room availability can be cached for a certain time as well as asynchronously periodically refreshed so that UniTime does not need to wait for the external system every time a person opens a page that needs room availability (e.g., Class Assignment or Examination Assignment page).

Setup

Following application properties need to be set to enable this interface.

 # Custom room availability service (a class implementing org.unitime.timetable.interfaces.RoomAvailabilityInterface)
tmtbl.room.availability.class=org.unitime.timetable.util.RoomAvailabilityService

# Maximum age of the room availability (in seconds, defaults to 600)
tmtbl.room.availability.maxage=600
# Room availability refresh period (in seconds, defaults to 60)
tmtbl.room.availability.refresh=60
# Time to live for the cache (if no request is made for the room availability in this time, it will stop asking for
# an update, in seconds defaults to 3600)
tmtbl.room.availability.timetolive=3600
# Time limit for the response (in seconds, defaults to 60)
tmtbl.room.availability.timeout=60

# Request XML file (defaults to Tomcat/data/unitime/request.xml)
#tmtbl.room.availability.request=
# Response XML file (defaults to Tomcat/data/unitime/response.xml)
#tmtbl.room.availability.response=
# Delete the response file after the response is read
tmtbl.room.availability.delete=true

# Midterm exam event type (so that these can be ignored when room availability is used for evening examination)
tmtbl.room.availability.eventType.midtermExam=Midterm Examination Event
# Final exam event type
tmtbl.room.availability.eventType.finalExam=Final Examination Event
# Class event type
tmtbl.room.availability.eventType.class=Class Event

An alternative is the BlobRoomAvailabilityService, that stores and requests the XMLs as blobs in the database.

 # Custom room availability service (a class implementing org.unitime.timetable.interfaces.RoomAvailabilityInterface)
tmtbl.room.availability.class=org.unitime.timetable.util.BlobRoomAvailabilityService

# SQL query that passes the XML request as CLOB
tmtbl.room.availability.request={ call room_avail_interface.request(?) }
# SLQ query that reads the XML response as CLOB
tmtbl.room.availability.response={? = call room_avail_interface.response()}
The other parameters are the same as for the RoomAvailabilityService.

Implementation

Custom room availability is implemented by RoomAvailabilityService using RoomAvailability interface. Also, see the DefaultRoomAvailability that is used to get the room availability from the UniTime's event management (enabled by default).

Other customizations

There are many other customizations available, see application.properties for suggestions. Most of the settings can be seen and changed using Administration > Defaults > Configuration page. For instance, see Examination Naming Conventions or Customizations.