The Calendar Synchronisation system is a series of APIs for 3rd party systems to populate and update Calendars in itslearning.

Calendars are used throughout itslearning and can be used by individual users ("personal calendar") or within courses ("course calendar").

Calendar events follow a similar format, with a title, start/end date, start/end time and a rich content "text" area.

Synchronisation of these is supported through the API.

 

The core services are as follows:

  1. ReadCalendarEvent
  2. CreateCalendarEvent
  3. UpdateCalendarEvent
  4. DeleteCalendarEvent

Linking Calendar Events and Users

When the 3rd party system creates a calendar event in itslearning it must link the entry to an individual itslearning user. All events have a 'created by' identifier. Without this an event cannot be created. Users can be referenced by either their UserID (the unique user identifier in itslearning) or their UserSyncKey (a unique identifier created by an external system when the user was imported or synchronised into itslearning). In many cases the system providing the calendar information will also be creating users and groups in itslearning, so this data will be readily present. If not, then the 3rd party and local itslearnng consultant will need to agree a way of matching users in itslearning with those in the calendar system (perhaps through IMS-ES). This should only need to be done once, as users cannot manually change their ID or UserSyncKey.

Linking Calendar Events and Courses

When the 3rd party system creates a calendar event in itslearning linked to a course it must know the identifier of the course.  Courses can be identified in different ways:

CourseId

The unique itslearning ID of the course to which imported event belongs.

CourseSyncKey

The SyncKeyID of the course to which imported event belongs. SyncKeys are created by external systems when they create courses in itslearning.

In many cases the system providing the calendar information will also be creating courses and groups in itslearning, so this data will be readily present. If not, then the 3rd party and local itslearning consultant will need to agree a way of matching users in itslearning with those in the calendar system (perhaps through IMS-ES).

Event SyncKeys

All events created by an the 3rd party will have an EventSyncKey. This is unique with itslearning for that partner. It acts as a unique identifier for the event and can be used, for example, to reference a previously created event in a delete request.

The 3rd party can use their own SyncKey (which is a text string) or is one is not specified it is automatically generated by itslearning. 3rd parties may want to embed their internal references in the SyncKey.

We recommend the format: YourDd-GUID. In this way we know all SyncKeys are statistically unique within the system. Using the 3rd party reference alone carries the risk of non-unique SyncKeys being used. If a SyncKey is not unique it is rejected by the API.

SyncKeys can not be reused, even if the event originally using a given SyncKey has been properly deleted. This is by design, and there are checks in place to ensure this, to avoid potential issues with IDs not being unique.

Consider the following sequence:

  1. Create event with SyncKey 'abc123-GUID'
  2. Delete event with SyncKey 'abc123-GUID'
  3. Delete was issued in error, try to recreate event with SyncKey 'abc123-GUID'

This will fail, as the SyncKey has been used before and is not considered to be unique, even though its corresponding event has been deleted.

 

Known Issues and Practical Implementation Information

The following are practical advice for implementation of systems calling the APIs.

  1. Only calendar events created by the 3rd party are given SyncKeys - this means it is possible only to read calendar entries created by a 3rd party system.
  2. If no SyncKey is specified through the Create.Calendar.Event message then itslearning will created one. The 3rd party system should keep track of all SyncKeys.
    Can calendar event be changed manually, and then read back to source system with updates?
  3. Recurrence is not supported in the API, so each event in the recurrence must be imported based on the recurring rules of the source system