Publish timetable

This function is for a timetabling system to publish a cyclical timetable to the SIS.

Call

liss.publishTimetable(auth, timetable, academicYear, timetableId, termId, startDate, endDate, createClassesFlag)

Parameters

auth: See authentication

timetable: see below

academicYear: integer. 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.

timetableId: integer (obsolete - superseeded by TtStructure below)

termId: integer (obsolete - superseeded by TtStructure below)

startDate: See get students

endDate: See get students

createClassesFlag: boolean - 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:

Field	Type	Notes	Example
`DayNumber`	integer mandatory	The day in the cycle. Starts at `1`. A two week timetable would be day `1` to `10`.	`10`
`Period`	string mandatory	The shortname of the period. Eg `1`, or `L2`. Typically, teaching periods have numeric identifiers and recess/ Lunch 1/ Lunch 2/Before school/After school periods have alphanumeric identifiers. Maximum 20 chars.	`1` `L2` `6`
`ClassCode`	string mandatory	The class code – see “Classes and courses”. Maximum 20 chars.	`7MAT 1`
`TeacherId`	string	The teacher id (not the mnemonic code). If this field is absent or is an empty string `""` then it means there is no teacher associated with this cyclical lesson. Maximum 20 chars.	`712611G`
`RoomId`	string	The room id (not the mnemonic code). A TS program should send either RoomId or RoomCode, but preferably a RoomId, in case the SIS does not maintain mnemonic codes. If the SIS sees a `RoomCode` but requires a `RoomId`, it can use the `RoomCode` as a `RoomId`. If both `RoomId` and `RoomCode` are absent or are empty strings, then it means there is no room associated with this cyclical lesson.	`651541`
`RoomCode`	string	The room code (mnemonic). See above. Maximum 20 chars.	`S19`
`TtStructure`	string	see: `liss.publishClasses()` If this field is missing but the SIS requires this type of information, then the SIS will have the job of deciding what TtStructure to associate this lesson with.

Returns

Nothing - an empty string "". If anything other than an error is returned it should be ignored. For error reporting see fault codes.

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.

Dealing with duty objects

Example duty

{
    "DayNumber": 4,
    "Period": "10",
    "ClassCode": "DUTY BusLinesPm",
    "TeacherId": "65611G",
    "TtStructure": "2012Junior"
}

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.

Example

Send

{
    "method": "liss.publishTimetable",
    "params": [
        {
            "School": "03014",
            "UserName": "Jsmith",
            "Password": "Password1",
            "LissVersion": 10002,
            "UserAgent": "Edval"
        },
        [
            {
                "DayNumber": 10,
                "Period": "L2",
                "ClassCode": "7MAT 1",
                "TeacherId": "712611G",
                "RoomId": "651541",
                "RoomCode": "S19",
                "TtStructure": "2012Junior"
            }
        ],
        2019,
        2,
        4,
        "20201031T00:00:00",
        "20201214T00:00:00"
    ],
    "id": 0
}

Return

{
    "result": "",
    "id": 0
}

Call​

Parameters​

Returns​

Semantics​

Dealing with duty objects​

Example​