Publish daily data

This call is for a timetabling system to publish a date-based timetable to an SIS. The date-based timetable is the data covering:

1. the cyclical timetable,
2. excursions & other events,
3. once-off room swaps and
4. 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

1. what calendar dates correspond with which cyclical dates, and
2. what changes take precedence.

Therefore the cyclical timetable is included in liss.publishDailyData().

Call

liss.publishDailyData(auth, startDate, endDate, timetable)

Parameters

auth: See authentication

startDate: See get students

endDate: See get students

timetable: An array of structs, where each struct represents a single lesson or event. Each struct has the following members:

Field	Type	Notes	Example
Date	timestamp mandatory	The date.	20120630T00:00:00
Period	string	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. (Double periods will require that 2 rows be sent.)	1 L2 6
StartTime	string recommended	If you provide a Period, then this field is optional. Start time of the event in HH:MM format.	9:30
EndTime	string recommended	If you provide a Period, then this field is optional. End time of the event in HH:MM format.	15:30
ClassCode	string mandatory	The class code. If it’s an event, then some suitable identifier for the event. Event names must be unique within a date but not necessarily across dates. Maximum 20 chars.	7MAT 1 YR10 CAMP
ClassName	string	A description of the class. This will often be the CourseName of the class if it’s a cyclical class, but for one-off events this will be the event name.
Type	string	This field is provided to distinguish between teaching lessons, yard duties, study periods, staff meetings, excursions, incursions, exams, and so on. The allowable values here form a superset of the Type field in liss.publishClasses(). One of the following strings: <blank> or omitted field: A normal teaching class. Duty: A yard duty or other duty. Study: A study period, (for students with gaps in their timetable). RollClass: Also known as HomeGroup, RollCall, etc. RTO: Rostered Time Off StaffMeeting: Staff meeting. ExtraCurricular: e.g. sports. Excursion: excursion. Exam: exam. Incursion: incursion. Event: any event which does not fall into the above categories. A SIS/TTS pair may negotiate between themselves to support additional values for this field.
TeacherIds	string	A comma-separated list of teacher id's. There's usually just one teacher per class but can be more, especially with e.g. excursions. If this field is absent then it means there are no teachers associated with this lesson.	6123429A 6123429A,9725731B
TeacherCodes	string discouraged	Usually, the TS will send TeacherIds. However, if for any reason the TS has mnemonic codes but not id's then it can send mnemonic codes instead. This field would then have the teacher’s mnemonic code, or a comma-separated list of codes. If this field is absent then it means there is no teacher associated with this lesson.	JCO JCO,CCH,ASM
Rooms	string	The room code, or a comma-separated list of codes. If this field is absent then it means there is no room associated with this lesson.	C3 C3,LAB1
Students	string mandatory	A comma-separated list of student codes. If this field is omitted, then the class-list will be taken from the class object’s permanent class-list. Otherwise it is repeated here. This field is useful for: a. excursions and events, where there is no class object in the server to provide it with a class list, b. study classes, where the class-list can be different each period and even within a period the class-list can change frequently as class membership of other classes changes, c. for attendance systems to communicate pre-arranged absences to the server. It would be more conventional to encode this field as an array. However, since many early users of LISS uses XmlRpc, and XmlRpc is an inefficient encoding and these fields could constitute the bulk of this message, we have chosen to use a comma-separated list instead.	652129,34611,24617,12172
Guid	32 char hexadecimal string	A "globally unique identifier" aka UUID. These are generated by the Timetabling software. These allow users of the timetabling software to change class codes and have the SIS still maintain a continuity of identity of the class.GUID's should be sent free of punctuation, i.e. the plain hexadecimal characters without any dashes.	34CBF4DCED74B20122414F16614D1253
Details	string	A free-text string.	Students need to bring sun-block.
Replacing	string	Usually this will be blank. If the teacher is different to the usual teacher for this lesson, then you'll see here the TeacherId of the regular teacher who can't make this lesson.	54126677
TtStructure	string	This string has either 1 or 2 parts. The first element is a TimetableStructure id. The next element is optional – if it exists, then a space is used to separate it from the TimetableStructure id. It is a set of terms as a comma-separated list. Maximum 20 chars.	2012 2012Junior 2012Junior 3,4

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.
• 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.

Example

Send

{
    "method": "liss.publishDailyData",
    "params": [
        {
            "School": "03014",
            "UserName": "Jsmith",
            "Password": "Password1",
            "LissVersion": 10002,
            "UserAgent": "Edval"
        },
        "20201031T00:00:00",
        "20201214T00:00:00",
        [
            {
                "Date": "20120630T00:00:00",
                "Period": "6",
                "StartTime": "9:30",
                "EndTime": "10:30",
                "ClassCode": "7MAT 1",
                "ClassName": "Mathematics",
                "Type": "StaffMeeting",
                "TeacherIds": "6123429A,9725731B",
                "Rooms": "C3,LAB1",
                "Students": "652129,34611,24617,12172",
                "Guid": "34CBF4DCED74B20122414F16614D1253",
                "Details": "Students need to bring sun-block.",
                "Replacing": "54126677"
            }
        ]
    ],
    "id": 0
}

Return

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