Specifications‎ > ‎

Core RPC calls

4.2      liss.getStudents()

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

 

Returns:

An array of struct’s.  Each struct is defined as follows:

Field

Type

Notes

Examples

StudentId

string (primary key, i.e. mandatory)

A unique alphanumeric identifier for that student.  Maximum 20 chars. NSW State schools often use the Enrollment Registration Number (ERN) here.

28722004

FirstName

string. Mandatory

 

John

Tse Hua

Surname

string. Mandatory

 

Brown

Ng

PreferredName

string

Used only when different from the FirstName, otherwise this field can be omitted.

Johnnie

Form

string. Mandatory

The form (or year-level) of the student. Anything other than empty string is allowed, but we recommend sticking to alphanumerics.

7

 

RollGroup

string

 

7A

House

string

 

Slitherin

Gender

string

The gender of the student:  ‘M’ or ‘F’.  Capitalisation ignored.

F

StatewideId

string

An alphanumeric identifier.  Used if there is a second student identifier in use by state bodies or district level bodies, e.g.  NSW Board of Studies (BOS) numbers.  Maximum 20 chars.

7219330187

Email

string

The student's email address. Only a single email address is allowed and it should conform to the rules for valid email addresses.

jimmy.smith@education.gov.nsw.au

Phone

string

The student's mobile phone number.  Can contain punctuation e.g. spaces or brackets, but with punctuation removed it should be a number that you can SMS to.

0418 123456

Guid

32 char hexadecimal string

A "Globally unique identifier" aka UUID. This allows users of the TT or SIS to change the student code and still maintain continuity of identity in the other system.  The GUID should be sent free of punctuation, i.e. just the hexadecimal characters, without dashes.

LISS does not specify which system(s) have the authority to create GUID's.

A2744A55ED7449A98BCE80703DECC9E4

  

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.

 

4.3 liss.publishStudents()

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: A string.  An empty string means success, otherwise it’s an error message. 


4.4      liss.getTeachers()

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:

Field

Type

Notes

Example

TeacherId

string (primary key)

Mandatory

A unique alphanumeric identifier.  Is not intended to be memorised by users.  Maximum 20 chars.

T621134

TeacherCode

string

A unique mnemonic code for the teacher.  Unlike ‘id’, this field is intended to be memorised by users.  Timetabling system users need very short, but still memorable identifiers for teachers. Timetabling systems often use the mnemonic codes as the main unique teacher identifier.

If you don’t have mnemonic codes, either omit this field or send a blank string.

Maximum 20 chars.

JCO

Title

string

Mr, Mrs etc.

Mr

FirstName

string. Mandatory

 

Collins, John

Surname

string. Mandatory

 

Collins

PreferredName

string

Used when different from the FirstName, otherwise this field can be omitted.

John

DisplayName

string

Usually omits the title.

John Collins

Faculty

string

The management group of the teacher

English

StaffType

string

One of these values:  Permanent, FullTime, Casual

FullTime

Gender

string

M or F

F

DaysAvailable

string

If this field is missing, then the teacher is assumed to be available all days.  Otherwise it’s a comma-separated string of 3-letter weekday names.  

Wed,Thu,Fri

Email

string

The teacher's email address. Only a single email address is allowed.

jane.price@redlands.nsw.edu.au

Phone

string

The teacher's mobile phone number. Can contain punctuation e.g. spaces or brackets, but with punctuation removed it should be a number that you can SMS to.

0418 123456

Guid

string

Teacher guid, also known as UUID.  32 hexadecimal characters. They might be uppercase or lowercase, but we require that they do not contain punctuation.

E523D....76348

 

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. 


4.5      liss.publishTeachers()

Call:

liss.publishTeachers(auth : AuthorisationObject, asAtDate : timestamp, data : array of teacher objects)

4.6      liss.getRooms()

Call:

get Rooms(auth : AuthorisationObject)

 

Params:

auth: See section 3.3

 

Returns:

An array of struct’s.  Each struct is defined as follows: 

Field

Type

Notes

Example

RoomId

string (primary key)

A unique alphanumeric identifier for the room. Maximum 20 chars.

46217

RoomCode

string (mandatory)

A unique mnemonic identifier for the room.  This is important because the ‘liss.publishTimetable’ call uses RoomCode’s rather than RoomId’s.

Maximum 20 chars.

C3

Name

string

The room’s name.  Usually identical to RoomCode.  If it is identical to RoomCode then RoomName can be omitted.

C3

Capacity

integer

The capacity of the room – the number of students able to be seated

29

Campus

string

 

Cremmorne

 

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.

  

4.7      liss.publishRooms()

4.8      liss.publishClassMemberships()

Call:

liss.publishClassMemberships(auth : AuthorisationObject, membership : struct, asAtDate : timestamp)

 

Parameters:

auth: See section 3.3

membership : an array of struct’s defined as follows: 

Field

Type

Notes

Example

StudentId

string (mandatory)

The alphanumeric student identifier (see ‘liss.getStudents()’.  Maximum 20 chars.

8722004A

ClassCode

string (mandatory)

The class code.  See “Classes and courses”. Maximum 20 chars.

7MAT 1

 StartDate  timestamp  The date/(time?) the class membership takes effect. This field and 'endDate' are only needed if the class membership is a subset of the 'startDate/endDate' date-range of the class.  20130203T0:00:00
 EndDate  timestamp  The date/(time?) the class membership terminates.  20130614T23:59:00

 

Returns: A string.  An empty string means success, otherwise it’s an error message. 

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.

 

4.9     liss.getClassMemberships()

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.

 

4.10      liss.publishClasses()

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:

Field

Type

Notes

Example

ClassCode

string, primary key i.e. mandatory

The class code. Must be in the format of <courseCode> and <class identifier> separated by a space, e.g “9MAT 1”, even if both SIS and satellite system use a different form of class codes.

Maximum 20 chars.

7MAT 1

CourseName

string

The name of the course. Eg “9 Mathematics”

7 Mathematics

DefaultTeacher

string

The teacher id for the default teacher.  The actual teacher assigned to each lesson in the cycle is specified in the liss.publishTimetable() call. The default teacher is responsible for report cards for that class.  Maximum 20 chars.  (The field is not mandatory because some non-teaching activities such as 'Duty' or 'StaffMeeting' may not have any teacher who can be meaningfully associated with it.)

Note that this field matches the "TeacherId" field found in other calls, and is not guarantee to match the "TeaccherCode" field.

762346J

Type

string

One of the following strings:

<blank> or omitted field:  A normal teaching class.

Duty : A yard duty or other duty

Study : A study period

RollClass : Also known as HomeGroup, RollCall, etc.

RTO : Rostered Time Off

StaffMeeting : Staff meeting

ExtraCurricular : e.g. sports

OnCall : On-call period (the teacher is free on this period unless they take a cover, and they’re encouraged to take covers during their on-call periods)

Duty

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

 StartDate  timestamp  The date the class first runs.  20130203T0:00:00
 EndDate  timestamp The date the class runs on.  Use time=23:59.  20130614T23:59:00
 Colour  string The colour assigned to the class by the satellite system, in hexadecimal notation: RRGGBB, like the HTML colour format but without the '#' prefix.  0000FF
 Form  string  The form (aka year-level) associated with the class. Some SIS's don't associate courses or classes with year-levels, in this case ignore this field.  6
 Faculty  string  The faculty (aka department) associated with the class.  Science

Rotations

integer

A bit-vector representing which rotations a class runs in.  A "rotation" is a Timetabling concept, a date-range which may correspond to terms, semesters or even arbitrary date ranges.  Rotation 1 is represented by bit 0, i.e. 1<<0, Rotation 2 is represented by bit 1 i.e. 1<<1, and so on.

To interpret rotations, you will need the "liss.publishCalendar()" call to provide you with a mapping from dates to rotations.

12   (represents rotations 3&4, which might mean semester 2)

 Composite string When a class is linked to another class as a composite, i.e. sharing the same teacher and same room, then this will point to the other class.  Typically these classes come in pairs, in which case you make one 'Composite' point to the other, but the reverse link should not appear.  'Composite' links involving 3 or more classes are allowed, provided there are no cycles   
 PriorityInClash integer If a student is "invited" to 2 classes at the same time, this number indicates which one they should go to. &nbsp;A lower number means high priority. If the numbers are equal then both classes should be displayed on the student's timetable.  9
 Guid string Class guid, also known as UUID.  32 hexadecimal characters. They might be uppercase or lowercase, but we require that they do not contain punctuation.  8BC9CEB....C91BC942

 

Returns: A string.  An empty string means success, otherwise it’s an error message. 

 

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 delete from its database any shared class which is not found in the returned array.

·       There is no DefaultRoom field, because typically, rooms change from period to period.

 


4.11      liss.getTimetableStructures ()

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:

Field

Type

Notes

Example

TtStructure

string

mandatory

Each cyclical lesson will have a TtStructure field, linking it to the object defined in this struct.  Maximum 20 chars.

2012

2012T4

2012VCE

AcademicYear

integer

The year as a 4-digit number.  In the case of Northern Hemisphere schools, 2011-2012 will be encoded as 2011.

2011

Terms

array of structs – see below

The set of terms comprising this timetable.  The terms do not have id’s because we automatically refer to the first array element as “term 1”, and so on.

 

 

Term objects:

Field

Type

Notes

Example

SemesterId

integer

mandatory

Which semester:  in most schools this will be either 1 or 2, but in LISS it can be any integer >= 1. 

2

Semester

string

mandatory

The name of the semester

Semester 1

TermId

integer

mandatory

The term number, Can be any integer >= 1

4

Term

string

mandatory

Term name

Term 4

StartDate

timestamp

mandatory

The start date for the term

20120201T00:00:00

EndDate

timestamp

mandatory

The end date for the term?

20120629T23:59:00

 

4.12      liss.publishTimetable()

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: 

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: A string.  An empty string means success, otherwise it’s an error message. 

 

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

 

4.13    liss.getTimetable()

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.


4.14     liss.publishDailyData()

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:

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

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.





 

Returns: A string.  An empty string means success, otherwise it’s an error message. 

 

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.

·       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).

·       On-call periods are not included in “liss.publishDailyData()” as such.  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.


4.15  liss.publishBellTimes

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:

Field

Type

Notes

Example

DayNumber

int

The index of the day in the cycle, starting at 1

1

DayName

string

The name of the day in the cycle

MonA

Period

string

The name 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

1

L2

6

TtStructure

string

This refers to a "period structure" object and matches the equivalent field in "liss.publishClasses". This field is often omitted because many schools only have a single period structure. (Old versions of one product used 'Campus' as an undocumented feature for the same concept).

Secondary

StartTime

string

The time the period starts in HH:MM format. Note – this is not an XmlRpc timestamp.

9:30

EndTime

string

The time the period starts in HH:MM format.

Note – this is not an XmlRpc timestamp.

10:55

Type

string

The type of period.  A single letter, one of:

 

T : Teaching period

L : recess or lunch

O : Out-of-timetable teaching period, i.e. before-school or after-school

R : Roll-call

S : Sport

X : Other

 

T

 

Returns:

A string.  An empty string means success, otherwise it’s an error message.

 

Semantics:

·       Each call to this function will delete whatever bell-times data previously existed.

 

4.16     liss.getBellTimes

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.


4.17     liss.publishCalendar

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.

Field

Type

Notes

Example

Date

Timestamp

mandatory

The date

20120630T00:00:00

DayName

string mandatory

The symbolic identifier (not index) of the day in the timetabling cycle.  This field must match one of the DayName’s in the liss.publishBellTimes()/liss.getBellTimes() call, or be “Holiday”.

MonA

MonB

Holiday

DayNumber

integer

The day number as used in the liss.publishTimetable(),  liss.publishBellTimes() or liss.getBellTimes() calls. This field can be used to link cyclical timetables with dates. The first day in the cycle is given number '1'.  Any holiday or weekend, i.e. any date which does not match any day in the cyclical timetable, can have this field blank or omitted.

(Note: you don't need to match cyclical timetables to dates if you use the 'publishDailyData()' call instead.) 

1

9

10

Rotation

integer

Timetabling programs sometimes introduce a concept called "rotation" whereby at certain prearranged times of the year, some modifications to the cyclical timetable take effect. These changeover dates may or may not correspond to semesters or terms.

2

Returns:

A string.  An empty string means success, otherwise it’s an error message.

 

Semantics:

·       Each call to this function will overwrite whatever mapping previously existed for the dates supplied.


4.18  liss.getCalendar

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.

 

4.19  liss.changeClassMembership()

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:

Field

Type

Notes

Example

 auth   

See section 3.3

  

   

studentId

String

mandatory

The student identifier

652129

date

Timestamp mandatory

When does this change take effect from?

20120630T00:00:00

outOfClasses

array of strings

optional

A list of class-codes representing the classes the student is moving out of.   Can be an empty array.

{"7MAT A","7SCI A"}

intoClasses

array of strings

optional

A list of class-codes representing the classes the student is moving into.   Can be an empty array.  If you enter a class-code for a class that the student is already in, then this is allowed but unnecessary.

{"7MAT B","7SCI B"}


Returns: A string.  An empty string means success, otherwise it’s an error message. 


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.



4.20     liss.getClasses

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.