Specifications

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

There is no formal compliance process for LISS. Instead a company should demonstrate to its customers that it has implemented the functions expected of a system of its type.

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

  • liss.getTeachers

  • liss.getRooms

  • liss.publishClasses

  • liss.publishTimetable

  • liss.publishClassMemberships

If a client calls an unimplemented function, the server should return a suitable XmlRpc error message or an empty string (i.e. as a stub implementation) rather than an HTML error because it is difficult for the LISS client to turn the HTML error into a readable error message.

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 3^rd 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:

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 2^nd 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/Error codes

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

JSON

For errors when using the JSON protocol you should return a JSON object with the property "error" detailing the issue.

e.g. { "error": "The student ABC123 does not exist" }

XML

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.

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: