Specifications

LISS

Light-weight Interoperability Standard for Schools

Version 1.0.2


1.   Introduction

1.1      Terminology

  • SIS = Student Information System
  • Class = A timetabled class, such as “Mrs Henderson’s Yr 7 Maths class”.  Represented by a code which combines the course and class identifier, such as:   7MAT1
  • Course = A course or subject in a particular year-level, such as “Yr 7 Maths” or “Yr12 Maths Standard”.
  • Class identifier = Also known as “class number”, this is used to distinguish the different classes belonging to one course.
  • Cyclical Lesson = a {class,teacher,room,period,day} tuple representing a repeating lesson, e.g. the “7MATA Monday period 1 lesson”.
  • TimetableStructure = A field attached to a cyclical lesson identifying what academic year it is associated with, and if a school has different bell-times for different parts of the school, which part of the school it is associated with.  A TimetableStructure object has 1 or more Term objects.


1.2      Architecture

LISS is based on XmlRpc, which is a certain XML-based schema being sent over HTTP/HTTPS.  The SIS is always the server, and the satellite systems are always the client, meaning that connections are always initiated by the satellite systems and query/publish actions are always initiated by the satellite systems.  However, data can flow both ways.  The satellite systems can be non-web-based and can be offline, whereas the SIS should always be online.

 

For example, if the satellite system wants to download a list of all students for a particular school, it makes a request to download all students.  If the satellite system wishes to publish timetabling data, it makes an HTTP “request” to publish timetabling data.   A subscribe model is not used and there is no way for the SIS to pull data from the satellite system.

 

In some cases, LISS will be deployed in a non-traditional way, such as: 

·       timetabling software connecting to attendance software

·       an SIS connecting to another SIS

·       a school-based SIS connecting to a district (enterprise) system 

In these cases, one of the systems will take on the role of the SIS and the other will act as the “satellite” system, depending on which one you want to be the server. 

 

1.3      Data flows

The SIS will always be the server, i.e. all calls are initiated by the satellite system regardless of which way the data actually flows.  With a few exceptions, data can flow in either direction:  from the SIS to the satellite system or vice versa.  Therefore, most calls occur in pairs:  

liss.get<objects>()

liss.publish<objects>()

In these cases, the 2 calls share the same definition of the objects being sent.

  • When data is Pushed (“publish”), this means it is sent to the SIS
  • When data is Pulled (“get”), this means it is sent to the satellite application
  • If you see (F?), it means that the function may be implemented in a future version of the standard.

Data / Function Call

Push
(To SIS)

Pull
(From SIS)

RPC function name

Teachers

(F?)

Y

liss.getTeachers

Rooms

(F?)

Y

liss.getRooms

Classes

Y

(F?)

liss.publishClasses

Timetable

Y

(F?)

liss.publishTimetable

TimetableStructures

(F?)

Y

liss.getTimetableStructures

Class Membership

Y

Y

liss.getClassMembership

liss.publishClassMembership

Students

(F?)

Y

liss.getStudents

Student Family

(F?)

Y

liss.getStudentFamilies

Daily data (excursions, room swaps etc)

Y

(F?)

liss.publishDailyData

Bell times/cycle structure

Y

Y

liss.getBellTimes

liss.publishBellTimes

 

On any given installation, there should be clear agreement as to which system is the single point of truth for a particular type of object.  This will determine which function calls will succeed, or perhaps even which function calls are implemented.  LISS v1.0 does not have any formal system for managing this constraint – it is up to the configuration of the SIS and/or satellite systems.

One Timetabling/SIS pair (Edval and Edumate) agreed that the SIS should be the primary data source of class lists for active timetables, whereas the timetabling system could be the primary data source of class lists for future timetables (next year’s timetable).   In some cases, the timetabling system will not deal with class lists.  In many cases, the school will want to make the decision as to which system they manage class lists in.

1.4    Compliance requirements

To be LISS compliant, a system is not required to implement all these functions.  It need only implement the functions “expected” of a system of its type.  (If a client calls an unimplemented function, the server should return a suitable XmlRpc error message rather than an HTTP error.)

In the case of a timetabling system, the minimum is (as the client): 

  • liss.publishTimetable
  • liss.publishClasses

 

In the case of an SIS, the minimum is (as the server):

  • liss.hello
  • liss.publishTimetable
  • liss.publishClasses
  • liss.getRooms
  • liss.getTeachers
  • liss.getStudents
  • liss.getTimetableStructures

 

2       The Transport Layer

2.1      JSON or XmlRpc

LISS is available in 2 flavours:  JsonRpc and XmlRpc (see http://www.xmlrpc.com/  )   JsonRpc and XmlRpc are essentially replacements for each other, protocols for sending arrays & structs etc. over HTTP. Both these protocols can use HTTP or HTTPS.  Since there is no formal certification process for LISS compliance, you can claim LISS compliance if you support either, but you should check that your integration partners support the chosen flavour. If the integration partner supports only the opposite flavour then the TS (Timetabling System) should implement both flavours.

 JsonRpc and XmlRpc are interchangeable to the extent that there is very little to explain in terms of how things are done differently.  The only thing to explain is the date format in JsonRpc, since JsonRpc does not specify a particular time/date format.  We use the format:  YYYYMMDD'T'HH:mm:ss  e.g. 20160303T9:00:00    . 

It is also worth saying that JsonRpc is a very simple addition to JSON. You can POST the following text for the simplest LISS call:

      { "method": "liss.hello", "params": [], "id": 1}

JSON is better than XmlRpc, in the sense of having lower bandwidth requirements and being easier to debug, but as of 2015, most SIS's are supporting the XmlRpc version.


2.2      HTTP or HTTPS?

LISS recommends that LISS implementations all use HTTPS.  It is not a requirement to use HTTPS in any given context, but it is a requirement that your software supports HTTPS in order to claim that you are LISS-compliant.  Some SIS vendors may mandate HTTPS.

2.3      Setting up

To configure an instance of a satellite system to use LISS, the user is required to enter the following 3 items: 

1.     Username

2.     Password

3.     URL, e.g.:   https://www.denfort.nsw.edu.au:9001/liss.php

 

URL’s are used just as they are used in browsers, except that browser don’t understand the XmlRpc protocol. A URL identifies:

1.     The protocol:  HTTP or HTTPS

2.     The port, in this example is 9001.  If not specified, it defaults to 443 (Https) or 80 (Http)

3.     The server – can be a domain name or IP address

4.     The ‘object’ on the server which responds to the request. liss.xxx is preferred for consistency, where xxx is php, asp, jsp etc.

3       Application-level issues common to all calls

3.1      Naming conventions

Readers are warned in particular that XmlRpc struct field names are case sensitive.  Because of this confusion, LISS uses:

·       camel-case with an uppercase first letter for field names, e.g.:   FirstName

·       camel-case with a lowercase first letter for method names, e.g.:   getStudents

Note that with reference fields, i.e. fields that can refer from one object to another, we attempt to keep the same spelling in both places.  For example, ‘StudentId’ is the same in all places where it’s used.  However, with non-reference fields, the convention is to not duplicate the table name in the field name – e.g. we use ‘Name’ instead of ‘StudentName’.

Note also that we use 2 parallel forms of identification:  codes and id’s.  A ‘code’ is a short mnemonic identifier which is unique within the school.  An ‘id’ is a slightly longer identifier, often numeric but not necessarily, also unique within the school.  For example, there is both a TeacherId and a TeacherCode field.  The reason for this is that in Australia as at the creation of LISS, mnemonic identifiers rather than numeric identifiers are used by almost all timetabling software packages to communicate to SIS’s.

LISS also has a “StatewideId” field for students, which is envisaged to be unique amongst all students in all schools within one instance of an SIS.  However, this is not used as a reference field.

Note that there has been discussion within LISS about a 3rd form of identification:  UUID’s aka GUID’s:  Globally unique identifiers, such as are used in SIF.  However, at this stage we are not including support for GUID’s in LISS.

3.2      Mandatory fields

LISS fields are all optional unless otherwise specified.  Consistent with our goal of making LISS simple, we have tried to make as few fields as possible mandatory.

Wherever an XmlRpc struct is used, each SIS and satellite system is free to add additional fields:  any field that is not defined by this standard should be ignored by the receiving system, or interpreted at its own risk.   (If a later version of LISS introduces new fields whose name overlap with customised fields’ names that a particular {SIS, satellite system} pair use, then it is the responsibility of those systems’ vendors to coordinate the change;  Or they could choose a naming convention which guarantees that the field names will never clash with standard fields.  Any fieldname containing a punctuation character is guaranteed never to be used by LISS).

3.3 Authentication

All calls except “liss.hello” will begin with an “authentication object”.  An authentication object is an XmlRpc struct with the following structure: 

Field

Type

Notes

Example

School

string

Mandatory

If you are an Australian school, then this is the DEEWR school number of the school.  If you are an Irish school, then this is the 5-digit Department of Education school number.  

If you wish to use an alternative identification system for schools, then you can if negotiated between the client and server organisations.

A single connection can theoretically send/receive data for multiple schools, but only one school for each XmlRpc call.

03014

UserName

string

Mandatory

The username of the person running the client program.  Usually this is someone in an administrator role...it’s not envisaged that (username, password) pairs will be issued to all staff in a school.  The SIS can link the username and password to LDAP or alternatives, or not, as they think best.

Jsmith

Password

string

Mandatory

A password, in plaintext.   There was some discussion about whether we should require the password be SHA-256 hashed, with or without a salt.  The consensus was that (a) this is unnecessary when LISS is used over HTTPS;  (b) most sites will be using HTTPS and our recommendation is HTTPS;  (c) when LISS is used over HTTP, this hashing would provide not much more than a false sense of security because an eavesdropper can use the hashed password to effect changes.

Password1

LissVersion

integer

Mandatory

The LISS protocol version used by the client. For example, LISS version 1.0 (i.e. this version) will be 10000, and LISS version 1.23.2 will be 12302. 

10000

UserAgent

string

Mandatory

The name of the satellite software system, e.g. “Edval”.

Edval

 

If the version number of the client and server do not match, then the server should try to complete the RPC call notwithstanding.  All versions of the LISS protocol are designed with forwards and backwards compatibility in mind, so most enhancements will be in the form of additional fields (which can be ignored by either system) or additional functions.  If a client is calling a function which has been newly added to LISS, and the server does not recognise this function, then an error will be returned by the server.  In some cases the server might want to use the LissVersion to decide what to send the client.

It is the server’s responsibility to decide what data the client has permission to receive when sending its responses, and likewise the client must decide what data it will send to the server. ACL’s (access control lists) are the responsibility of each system.

3.4      Courses versus Timetabled Classes

See section “1.1 Terminology”.

SIS’s typically deal primarily with Course’s, and TTS’s typically deal primarily with Class’s.

In LISS, class identifiers will be in the form of a string consisting of 2 parts:  “Course” and “Class identifier”, with a single space separating them.  Neither the course code nor the class code may contain spaces.  For example:   7MAT 1  or  12MATE 1”.   The class identifier can be alphanumeric.  The TTS and SIS do not need to store or display class codes in this particular notation, they merely need to be able to construct or parse it for the purposes of LISS.

ClassCode values can have at most 20 characters including the space.  In addition, the class identifier must be no more than 10 characters.  For example, this is a valid LISS ClassCode:   DUTY BusLinesPm”, but this is not:   DUTY BusLines_Pm”.

3.5      Size limits on fields

Many software systems use RDBMS technology that uses fixed-length fields.  In order to cater for these systems, LISS has specified a maximum size for certain types of fields.  The limit is only applied to “reference fields”, that is, fields which need to be matched between 2 different RPC calls or fields which might be used as keys in the receiving system, e.g. ClassCode, TeacherCode, StudentId.  Non-reference fields, such as student FirstName, can be any length, and the expectation is that the receiving system will truncate it if it is too long.

The limit is 20 for all id and code fields, and 10 for “class identifier”, which is the 2nd component of ClassCode.

Limits are specified in the field descriptions.  If there is no mention of a limit then there is no limit on that type of field.

 This limitation is a compliance requirement, however any given pair of systems can choose to go beyond these limits.

(There was some discussion about whether the limit should be 32, large enough to store a UUID, but the consensus was that UUID’s are unlikely to replace the id fields as envisaged here and that a limit of 20 lowers the bar for systems to become compliant.)

3.6      Transactions

The XmlRpc system ensures that each XmlRpc call is either received by the business layer of the application in its entirety, or not at all.

Each XmlRpc call is a fairly coarse-grained object:  there is a lot of overhead, and a lot of data is transferred.  LISS does not have any “incremental” calls.

Each SIS or satellite system can choose whether to process each row in an XmlRpc table as a transaction, or whether the table as a whole is processed as a transaction.  LISS does not recommend either approach.

3.7      Fault codes

The XmlRpc spec defines a <fault> object to be returned whenever an RPC call fails.  The <fault> object contains:  (a) a numeric fault code, and (b) a string description.  

LISS does not define any standardised values for the fault code.  However, LISS urges SIS developers to create meaningful and comprehensive strings.

Note also that the XmlRpc <fault> object is only returned on high-level errors, such as “missing school code”.  Lower level errors such as “this server does not recognise this URL” will produce Http-level errors.

4       Calls

4.1      liss.hello()

This call is used mainly for debugging or as a “ping”:  don’t bother trying to get other calls to work if this one doesn’t.

This call is the only call that does not begin with an authentication object.

Call:

liss.hello()


Parameters

None


Returns:

An XmlRpc struct as follows:

Field

Type

Notes

Example

SIS

string

Mandatory

The name of the SIS

Edumate

LissVersion

integer

Mandatory

The LISS protocol version number used by the SIS.  The version number is encoded as in section 3.3, i.e. major version number followed by 2 digits for minor version number followed by 2 digits for release number.

10000

 

See also: 

Core RPC calls

Extension 1: daily delta's and excursions
Proposed extension: Attendance
Proposed extension 2

Future directions