Call:
liss.getStudents(auth : authenticationObject, asAtDate : timestamp)
Parameters
auth: See section 3.3
asAtDate: Return all students enrolled as at this date. In the case of XmlRpc, the format is XmlRpc date/time. In the case of JsonRpc, it's an ISO8601 format, e.g. "20181130T00:00:00". If the SIS chooses to send the "startDate" and "endDate" fields then they can ignore the "asAtDate" but they should check that the TS in question has implemented "startDate" and "endDate" because earlier versions of LISS didn't have this.
Returns:
An array of struct’s. Each struct is defined as follows:
Semantics:
· Each call to liss.getStudents() will return the full database of students enrolled at the requested date. Therefore the satellite system should delete from its database any student which is not found in the returned array.
· Satellite system vendors should consider whether they should disable the creation or deletion of students in their own screens in installations which are using LISS.
This call is used less frequently than 'liss.getStudents()'. The reason is that typically, the server is the source of truth for student data, not the satellite system. However, if the SIS is installed in the school and is contacting a web-based satellite system outside the school, then you'd typically want to push the students rather than pull them.
Call:
liss.publishStudents(auth : AuthorisationObject, asAtDate : timestamp, students : array of student objects)
Parameters:
auth: See section 3.3
asAtDate: Self explanatory
students: an array of 'student' object as defined above.
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Call:
liss.getTeachers(auth : AuthorisationObject, asAtDate : timestamp)
Parameters:
auth: See section 3.3
asAtDate: Self explanatory.
Returns:
An array of struct’s. Each struct is defined as follows:
Semantics:
TeacherId is the primary key – that is, it is mandatory and unique. If a record arrives where the TeacherId matches a record in the timetabling system but the MnemonicCode is different, then the MnemonicCode will be updated in the timetabling system to the value given in this call.
· Each call to liss.getTeachers() will return the full database of teachers employed by the school at the requested date. Therefore the satellite system should delete from its database any teacher which is not found in the returned array.
· Satellite system vendors should consider whether they should disable the creation or deletion of teachers in their own screens in installations which are using LISS.
Call:
liss.publishTeachers(auth : AuthorisationObject, asAtDate : timestamp, data : array of teacher objects)
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
This is a 'push' version of the above. Each element of 'data' is a struct with the same definition as above. This method is less commonly used than 'getTeachers()' because it's more common for the TS to be requesting teacher data from the SIS.
Call:
get Rooms(auth : AuthorisationObject)
Params:
auth: See section 3.3
Returns:
An array of struct’s. Each struct is defined as follows:
Semantics:
Both RoomId and RoomCode must be unique.
RoomId is the primary key – that is, it is mandatory and unique. If a record arrives where the RoomId matches a record in the satellite system but the RoomCode is different, then the RoomCode will be updated in the satellite system to the value given in this call.
· Each call to liss.getTeachers() will return the full database of teachers employed by the school at the requested date. Therefore the satellite system should delete from its database any teacher which is not found in the returned array.
· Timetabling system vendors should consider whether they should disable the creation or deletion of rooms in their own screens in installations which are using LISS.
Call:
liss.publishRooms(auth : AuthorisationObject, asAtDate : timestamp, data : array of room objects)
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
This is a 'push' version of the above. Each element of 'data' is a struct with the same definition as above. This method is less commonly used than 'getRooms()' because it's more common for the TS to be requesting room data from the SIS.
Call:
liss.publishClassMemberships(auth : AuthorisationObject, membership : struct, asAtDate : timestamp)
Parameters:
auth: See section 3.3
membership : an array of struct’s defined as follows:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
Some SIS’s and timetabling systems have a concept whereby class membership is defined at the level of a group of classes, e.g. 7HIS1 and 7GEO1 share the same class lists. This structure is not defined in LISS, and therefore in such cases, the class membership should be expanded so that the array contains entries for all classes.
Call:
liss.getClassMemberships(auth : AuthorisationObject, asAtDate : timestamp)
Parameters:
auth: See section 3.3
asAtDate : self-explanatory
Returns:
An array of struct’s as used in liss.publishClassMemberships.
Semantics:
· Each call to liss.getClassMemberships() will return the full database of class memberships at the requested date. Therefore the satellite system should delete from its database any class membership which is not found in the returned array.
· Some SIS’s and timetabling systems have a concept whereby class membership is defined at the level of a group of classes, e.g. 7HIS1 and 7GEO1 share the same class lists. This structure is not defined in LISS, and therefore in such cases, the class membership will be expanded so that the array contains entries for all classes.
See the “Data Elements” section above for an explanation of the difference between classes and courses.
Call:
liss.publishClasses(auth : AuthorisationObject, academicYear : integer, classes : array)
Parameters:
auth: See section 2
‘academicYear’: a 4-digit year, e.g. 2012. A northern hemisphere school would use e.g. “2012” to refer to the 2012/2013 year.
‘classes’ is an array of structs defined as follows:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
· The SIS may choose to store class objects which do not represent classes managed by the satellite system. These objects typically represent extra-curricular activities such as “Choir”. Conversely the satellite system may store class objects which it does not publish to the SIS, e.g. “helper” classes designed to enforce the correct timetable structure. Each system must have a way to distinguish between classes which are shared versus internal class objects.
· Each call to liss.publishClasses() will publish the full database of shared classes at the requested date. Therefore the SIS should (a) mark as inactive or (b) terminate the date-range of, or (c) delete from its database, any class which is not found in the returned array.
· There is no DefaultRoom field, because typically, rooms change from period to period.
Some SIS’s and timetabling systems divide cyclical lessons into multiple data-sets called ‘Timetable structures’. For example, the K-6 school and the 7-12 school might be in different timetable structures, or the International Baccalaureate students might be in a different timetable structure to the other Yr11/12 students. These ‘timetable structures’ are created for various reasons, for example because different bell times apply to different groups of students, or because the data-sets largely involve separate groups of teachers/rooms/students with just very minimal interaction between them.
This call pulls down the timetable structure as set up in the SIS. The satellite system needs to get these identifiers in order to attach to the cyclical lessons in liss.publishTimetable().
Call:
getTimetableStructures(auth : AuthorisationObject, asAtDate : timestamp)
Parameters:
auth: See section 3.3
Returns:
An array of structs. Each struct has these members:
Term objects:
This function is for a timetabling system to publish a cyclical timetable to the SIS.
Call:
liss.publishTimetable(auth : AuthorisationObject,
timetable : array, academicYear : integer, timetableId : integer,
termId : integer, startDate : timestamp, endDate : timestamp,
createClassesFlag : boolean)
Parameters:
auth: See section 2
createClassesFlag : If true, then the SIS will create classes whenever it receives a class code which is not already in its database. However, the ‘course’ must already exist.
*** Tim: Isn’t it for the SIS to decide whether to create classes or not? Perhaps remove this parameter, forbid the SIS to create classes in this call, and instead require ‘liss.publishClasses()’ to be run when new classes are created. Or remove the parameter and have it as a requirement that the SIS creates classes where necessary in this fn.
*** David: Yes… but. The decision to create classes or not seems to change from moment to moment at the same school (ie it’s a decision of the moment rather than a setting)
Since the action is initiated from within the TTS then it makes sense to be here
timetable : An array of structs, where each struct represents a single cyclical lesson. Each struct has the following members:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
· Double-periods will require 2 rows to be sent, one for each of the 2 periods. This is because of the possibility that the 2nd half of the lesson will be in a different room or with a different teacher.
· Some SIS’s will require that each course referenced in each class code must already exist in their database, created outside LISS. These SIS’s will return an error if the course does not exist. Other SIS’s may choose to create course records on-the-fly as received through LISS.
· Each call to liss.publishTimetable() will send the full timetable. Therefore the SIS should delete from its database any cyclical lesson which is not found in the passed array. Any lesson that exists in the SIS but does not exist in the data coming from the timetabling system will end one day before the Start Date of the timetable.
· Before the import is run, the data will be checked for…
· All room id’s in the file exist in the SIS
· All teacher id‘s in the file exist in the SIS
· If you have 2 or more teachers on the same cyclical lesson, (or 2 or more rooms on the same lesson), then the timetabling system will pass a separate record for each teacher. These duplicate records will contain all the same fields except for TeacherId and/or RoomId.
· If there are errors in the import, e.g. the timetable refers to teachers or rooms which do not exist, then it is the SIS’s choice as to whether the whole call will be aborted or whether those rows already processed are retained.
4.12.1 Dealing with duty objects
Some timetabling systems deal with duty rosters, such as yard duties.
If duties are to be synchronised using LISS, then they will be synchronised using the same calls and fields as teaching lessons, i.e. with liss.publishTimetable() and liss.publishDailyData(). LISS recommends that a course-code of “DUTY” be used and that the class-identifier be a short code of mnemonic value, representing the area of the yard duty. For example,
ClassCode = “DUTY BusLinesPm”
It is more common that the client calls liss.publishTimetable() than liss.getTimetable(). liss.getTimetable enables an SIS to pull the timetable out of a web-based timetabling system, or enables a timetabling application to pull an existing timetable out of an SIS as part of an initial migration process.
Call:
liss.getTimetable(auth : AuthorisationObject,
academicYearId : integer, startDate : timestamp, endDate : timestamp)
Parameters:
auth: See section 2
academicYearId : e.g. 2012. For northern hemisphere schools, the academic year will be encoded according to when it starts, e.g. 2012/13 will be encoded as 2012.
Returns:
An array of structs, where each struct represents a single cyclical lesson. See liss.publishTimetable, because the structs will share the exact same format as that call.
This call is for a timetabling system to publish a date-based timetable to an SIS. The date-based timetable is the data covering: (a) the cyclical timetable, (b) excursions & other events, (c) once-off room swaps and (d) staff absences/covers. The SIS may choose to not implement this function, e.g. because it manages the daily data itself.
In many cases, this function can be used as a complete replacement for “liss.publishTimetable()”, because the cyclical timetable is roughly speaking a subset of the data sent by this function. The date-based data, which is sometimes also called “daily variations”, consists of both additions to and subtractions from the cyclical timetable. If we did not include the cyclical timetable in this function, then SIS implementors would need to implement a lot of complex logic to determine (a) what calendar dates correspond with which cyclical dates, and (b) what changes take precedence. Therefore the cyclical timetable is included in “liss.publishDailyData()”.
Call:
liss.publishDailyData(auth : AuthorisationObject,
startDate : timestamp, endDate : timestamp,
timetable : array
)
Parameters:
auth: See section 3.3
timetable : An array of structs, where each struct represents a single lesson or event. Each struct has the following members:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
· Double-periods will require 2 rows to be sent, one for each of the 2 periods. This is because of the possibility that the 2nd half of the lesson will be in a different room or with a different teacher.
· For once-off events which span more than one period, TS's may send this as one object or multiple objects, broken down by period. Breaking it down by period will be the only way to send information about different teachers taking different portions of the event, which is common with exam supervision and supervision of kids not going on excursions. SIS's which wish to view the event as a single object will need to group the relevant rows together, e.g. matching on "ClassCode". A future version of LISS will likely follow the SIF "ScheduledActivity" pattern, whereby the teacher cover objects are sub-objects of the event.
· Data outside the given date-range is obviously retained; data within the date-range is overwritten. In other words, you can delete a lesson by doing an upload which omits the lesson.
· In each row, you must give either “Period” or (both “StartTime” and “EndTime”). It is recommended you give both, where possible. An example of where “Period” is missing is where an excursion or exam starts halfway through another period. An example of where “StartTime” and “EndTime” might be missing is where a TTS does not have a feature to define bell times (a rare occurrence).
· There is some debate about whether On-call periods should be included in “liss.publishDailyData()” or not. The argument to exclude them is: "An on-call period is really just an instruction to the TTS to be more likely to assign this teacher a cover on this particular period. If a cover was assigned, then this information will appear, and if a cover was not assigned then it’s irrelevant whether the period was an on-call or not." The argument to include them is: "Teachers need to know ahead of time that they may be required in those slots at short notice". For now, the SIS and TS should negotiate on whether to include them or not.
This call publishes the structure of the teaching cycle, including what the bell times are on each cyclical day, how many days in the cycle, what is the name of each teaching period and where do the non-teaching timeslots appear.
Call:
liss.publishBellTimes(auth : AuthorisationObject, TtStructure : string, periods : array)
Parameters:
auth: See section 3.3
TtStructure : Obsolete. (The 'TtStructure' is now sent as a property on rows). Please send an empty string.
periods : An array of structs, as defined below. Each struct represents a single ‘cyclical timeslot’, where a cyclical timeslot can be a teaching period such as "Mon Week A period 1" or something else such as recess or lunch or roll-call or “a before-school teaching period”, and so on:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
· Each call to this function will delete whatever bell-times data previously existed.
This call queries the SIS to get the structure of the teaching cycle, including what the bell times are on each cyclical day, how many days in the cycle, what is the name of each teaching period and where do the non-teaching timeslots appear.
Call:
liss.getBellTimes(auth : AuthorisationObject, TtStructure : string)
Parameters:
auth: See section 3.3
TtStructure : An identifier of a TimetablingStructure object. See liss.getTimetableStructures.
Returns: An array of structs in the same format as liss.publishBellTimes, or an error message.
This call publishes the date à cycle day mapping. Note that many SIS’s have no use for this function and you should not rely on this data for building timetable displays, because instead you should be using “liss.publishDailyData()”. The “liss.publishDailyData()” function combines the date à cycle day mapping with the cyclical timetable but also includes information about daily variations, i.e. excursions/room swaps/teacher covers, which the timetable displays will need. Conversely, if the SIS is responsible for daily timetabling then the SIS will be the originator of the date à cycle information and again there is no need to use liss.publishCalendar().
Call:
liss.publishCalendar(auth : AuthorisationObject, D : array)
Parameters:
auth: See section 2
D : An array of objects as defined below.
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Semantics:
· Each call to this function will overwrite whatever mapping previously existed for the dates supplied.
This call queries the SIS to get the date à cycle day mapping for a particular date-range.
Call:
liss.getCalendar(auth : AuthorisationObject, date1 : timestamp, date2 : timestamp)
Parameters:
auth: See section 3.3
Returns: An array of structs in the same format as liss.publishCalendar, or an error message.
This call is for the Timetabling app to publish incremental class membership changes to the SIS. Unlike most LISS calls, this call is not paired with a “get data” call, because that would not make sense for incremental changes, unless we implemented a “subscribe to changes” mechanism, which is getting too complicated.
Call:
liss.changeClassMembership (auth : AuthorisationObject, studentId : string, date : timestamp, outOfClasses : array of strings, intoClasses : array of strings)
Parameters:
Returns:
Nothing - an empty string. If anything other than an error is returned it should be ignored. For error reporting see section 3.7.
Note that there was discussion over whether to have the "outOf/into" system versus repeating the full list of classes for this student. The advantage of the full list would be that errors, i.e. situations where the 2 systems have different class memberships, will be automatically corrected for the student in question. The disadvantage is that it creates possible confusion if the timetabling system maintains private class-like objects that it doesn't (always) send to the SIS, or vice versa: i.e. if a class does not appear in the list, is this because the student left the class or because the class was marked "don't export"? The consensus is that both systems would work, but we decided on the "outOf/into" system.
This call mirrors "liss.publishClasses()".
Call:
liss.getClasses(auth : AuthorisationObject)
Parameters:
auth: See section 3.3
Returns: An array of structs in the same format as liss.publishClasses, or an error message.