Create.Calendar.Event and Update.Calendar.Event

Creates or updates one or many calendar events (personal or course). Users specified in a content of the message are assigned as creators and owners of respective events

Recurring events are not yet supported through the API

Action

Message with that type will create or update calendar events. All rich content is passed through white-list filter. The filtering level is taken according to "Allowed HTML Code Level" option in creator’s profile/policy.

images/download/attachments/11174049/calendar-event.png

Scenario

In order to create/update calendar events, a user needs to add a message with type corresponding to actions Create.Calendar.Event/Update.Calendar.Event respectively. These message types are synchronous, so the results of message processing can be read from the response.

Input parameters

Message type

Name

Description

Type

M/O

SyncKeys

Event SyncKeys array.

SyncKeysType

M/O

Events

Calendar event

EventsType

M

SyncKeysType

Name

Description

Type

M/O

SyncKey

Events’ SyncKeys. Can be empty for new events. Mandatory for update message

ID

M/O

EventsType

Name

Description

Type

M/O

Event

A single calendar event.

EventType
From 1 to many

M

EventType

Name

Description

Type

M/O

SiteId

Site where action will be executed

Int

O

VendorId

VendorId which will be associated with created content

Text

O

StartDateTime

The date and time when event starts.

dateTime

M

EndDateTime

The date and time when event ends.

dateTime

M

Description

Event description text. In the UI this description will be listed under "Event notes", see below for more information.

string

O

SyncKeyRef

A reference to event SyncKey (SyncKey itself is defined above)
Mandatory for update message

IDREF

O/M

IsLesson

Defines whether the event represents a lesson in calendar. If the value is not specified it considers as false.

Note: This field is now deprecated and will be ignored. All course events are lessons now (IsLesson=true for all course events).

boolean

O

UserId

UserId of the event creator (either UserId or UserSyncKey must be specified).

integer

O/M

UserSyncKey

User’s SyncKey of the event creator (either UserId or UserSyncKey must be specified).

string

O/M

CourseId

The ID of the course which imported event belongs to (either CourseId or CourseSyncKey should be specified; if both are missing, the event is considered to be Personal event, otherwise Course event).

integer

O

CourseSyncKey

SyncKeyID of the course which imported event belongs to (either CourseId or CourseSyncKey should be specified; if both are missing, the event is considered to be Personal event, otherwise Course event).

string

O

GroupHierarchyId

Hierarchy ID for a course group already synchronized with course defined by CourseId or CourseSyncKey. Either GroupHierarchyId or GroupHierarchySyncKey can be specified for Course events only. If both are not specified for Course events, it means “All participants” in course.

integer

O

GroupHierarchySyncKey

Hierarchy SyncKey for a course group already synchronized with course defined by CourseId or CourseSyncKey. Either GroupHierarchyId or GroupHierarchySyncKey can be specified for Course events only. If both are not specified for Course events, it means “All participants” in course.

string

O

DisableDelete

Defines whether the ability to delete that event for the user is disabled. If the value is not specified, it is considered false.

boolean

O

Notes:

  • Either Creator’s UserId or UserSyncKey must be specified. This means specify at least one is mandatory.

  • Either CourseId or CourseSyncKey must be specified for course events. If both are missing, the event is considered to be Personal.

  • Either GroupHierarchyId or GroupHierarchySyncKey can be specified for Course events only. If both are not specified for Course events, it means “All participants” in course.


Description versus Event Notes:

The description of events created with the Organisation API will be shown in itslearning under Event Notes:

images/download/attachments/11174049/CalendarEventEdit.png

The "Event description" field can only be changed by users in itslearning, this field cannot be read or changed with the Organisation API. This allows teachers to add / change their own description, while at the same time allowing the 3rd party using the Organisation API to update the Event notes, without causing any conflicts. In every place where the event is shown, both the Event description and the Event notes are shown:

images/download/attachments/11174049/CalendarEventView.png

Output

Finished status

Message

Exists in Create messages

Exists in Update messages

Calendar event created

Yes

No

Calendar event updated

No

Yes

Warning status

Message

Description

Exists in Create messages

Exists in Update messages

Event '{EventSyncKey}': There is a planner lesson linked to this date. Changing the date of this event will disconnect it from the planner.

Occurs when updating an existing lesson that connected to planner lesson and there are another events connected to the same planner lesson and dates of event is changed

No

Yes

Errors status

Message

Description

Exists in Create messages

Exists in Update messages

Invalid format / parameters (different to specified schema).

Yes

Yes

SyncKey is not unique.

Yes

No

Message must contain valid UserId/UserSyncKey.

Yes

Yes

User with specified UserId/UserSyncKey is not valid.

Yes

Yes

User with specified UserId/UserSyncKey is deleted.

Yes

Yes

User with specified UserId/UserSyncKey is external.

Yes

Yes

Message must contain valid CourseId/CourseSyncKey.

Yes

Yes

Course with specified CourseId/CourseSyncKey is not valid.

Yes

Yes

Course is deleted.

Yes

Yes

Course is external.

Yes

Yes

Course is archived.

Yes

Yes

Event ‘{EventSyncKey}’: This lesson is linked to course content (i.e. a planner lesson, the deadline of an assignment, etc.). It’s not possible to make this event personal.

Occurs when existing event is lesson, which is linked to course content, but event is treated as personal (no course id or synckey defined)

No

Yes

Event '{EventSyncKey}': This lesson is linked to course content (i.e. a planner lesson, the deadline of an assignment, etc.). It's not possible to change CourseId/CourseSyncKey.

Occurs when existing event is lesson, which is linked to course content, and CourseId or CourseSyncKey is changed

No

Yes

Event ‘{EventSyncKey}’: This lesson is linked to course content (i.e. a planner lesson, the deadline of an assignment, etc.). It’s not possible to change GroupHierarchyId/GroupHierarchySyncKey.

Occurs when existing event is lesson, which is linked to course content, and GroupHierarchyId or GroupHierarchySyncKey is changed (or not specified)

No

Yes

Calendar is disabled for user ‘{Person ID or SyncKey}’.

Occurs when calendar is disabled in person profile/policy

Yes

Yes

User ‘{Person ID or SyncKey}’ is not allowed to administrate calendar in course ‘{Course ID or SyncKey}’.

Occurs when importing course event, but creator doesn’t have administrate calendar rights

Yes

Yes

Message must contain valid GroupHierarchyId/GroupHierarchySyncKey.

Occurs when GroupHierarchyId is less than 1

Yes

Yes

There is no course group synchronised with hierarchy ‘{Hierarchy ID or SyncKey}’.

Occurs when providing an invalid GroupHierarchyId or GroupHierarchySyncKey

Yes

Yes

Event ‘{EventSyncKey}’: Start date is after end date.

Start date > end date

Yes

Yes

Event ‘{EventSyncKey}’: ‘GroupHierarchyId’ or ‘GroupHierarchySyncKey’ parameters can be defined only for course events.

Occurs when importing a personal event (no course id or sync key provided), but either ‘GroupHierarchyId’ or ‘GroupHierarchySyncKey’ are specified

Yes

Yes

Event ‘{EventSyncKey}’ cannot be updated, because it does not exist in itslearning or the event was permanently deleted through the API.

Occurs when updating non-existing event

No

Yes

Event ‘{EventSyncKey}’ cannot be updated, because it has been manually deleted in itslearning.

Occurs when trying to update previously imported event, which has been deleted from itslearning

No

Yes

Event '{EventSyncKey}': Your security settings doesn't allow you to perform that operation. Please contact administration to grant you an access to {HieararchyName} organisation.

Occurs when the organisation level security settings prohibit you access to a related course.

Yes

Yes

Event '{EventSyncKey}': Your security settings doesn't allow you to perform that operation. No valid Organisation found for course - (Course Id {0}) {1}

Occurs when organisation level security is enabled and a related course does not have an organisation.

Yes

Yes

Schema

Create.Calendar.Event schema
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:message-schema" elementFormDefault="qualified" targetNamespace="urn:message-schema">
<xs:element name="Message" type="MessageType" />
<xs:complexType name="MessageType">
<xs:sequence>
<xs:element name="SyncKeys" type="SyncKeysType" minOccurs="0" maxOccurs="1" />
<xs:element name="Events" type="EventsType" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeysType">
<xs:sequence>
<xs:element name="SyncKey" type="SyncKeyType" minOccurs="0" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeyType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="ID" type="xs:ID" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="EventsType">
<xs:sequence>
<xs:element name="Event" type="EventType" minOccurs="1" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="EventType">
<xs:sequence>
<xs:element name="StartDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="EndDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="SyncKeyRef" type="xs:IDREF" minOccurs="0" maxOccurs="1" />
<xs:element name="IsLesson" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="UserId" type="xs:integer" />
<xs:element name="UserSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="CourseId" type="xs:integer" />
<xs:element name="CourseSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="GroupHierarchyId" type="xs:integer" />
<xs:element name="GroupHierarchySyncKey" type="xs:string" />
</xs:choice>
<xs:element name="DisableDelete" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:schema>
Update.Calendar.Event schema
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:message-schema" elementFormDefault="qualified" targetNamespace="urn:message-schema">
<xs:element name="Message" type="MessageType" />
<xs:complexType name="MessageType">
<xs:sequence>
<xs:element name="SyncKeys" type="SyncKeysType" minOccurs="1" maxOccurs="1" />
<xs:element name="Events" type="EventsType" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeysType">
<xs:sequence>
<xs:element name="SyncKey" type="SyncKeyType" minOccurs="1" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeyType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="ID" type="xs:ID" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="EventsType">
<xs:sequence>
<xs:element name="Event" type="EventType" minOccurs="1" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="EventType">
<xs:sequence>
<xs:element name="StartDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="EndDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="SyncKeyRef" type="xs:IDREF" minOccurs="1" maxOccurs="1" />
<xs:element name="IsLesson" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="UserId" type="xs:integer" />
<xs:element name="UserSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="CourseId" type="xs:integer" />
<xs:element name="CourseSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="GroupHierarchyId" type="xs:integer" />
<xs:element name="GroupHierarchySyncKey" type="xs:string" />
</xs:choice>
<xs:element name="DisableDelete" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:schema>

Message content example

Create.Calendar.Event message example
<Message xmlns="urn:message-schema">
<SyncKeys>
<SyncKey ID="ID1">YK_013</SyncKey>
<SyncKey ID="ID2">YK_014</SyncKey>
</SyncKeys>
<Events>
<Event>
<StartDateTime>2012-05-05T18:00:00+04:00</StartDateTime>
<EndDateTime>2012-05-05T19:00:00+04:00</EndDateTime>
<Description>This COURSE event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID1</SyncKeyRef>
<IsLesson>true</IsLesson>
<UserId>2</UserId>
<CourseId>1</CourseId>
<GroupHierarchyId>1</GroupHierarchyId>
<DisableDelete>1</DisableDelete>
</Event>
<Event>
<StartDateTime>2012-05-07T18:00:00+04:00</StartDateTime>
<EndDateTime>2012-05-07T19:00:00+04:00</EndDateTime>
<Description>This PERSONAL event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID2</SyncKeyRef>
<UserId>2</UserId>
</Event>
</Events>
</Message>
Update.Calendar.Event message example
<Message xmlns="urn:message-schema">
<SyncKeys>
<SyncKey ID="ID1">YK_013</SyncKey>
<SyncKey ID="ID2">YK_014</SyncKey>
</SyncKeys>
<Events>
<Event>
<StartDateTime>2012-05-05T18:00:00+04:00</StartDateTime>
<EndDateTime>2012-05-05T19:00:00+04:00</EndDateTime>
<Description>This COURSE event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID1</SyncKeyRef>
<IsLesson>true</IsLesson>
<UserId>2</UserId>
<CourseId>1</CourseId>
<GroupHierarchyId>1</GroupHierarchyId>
<DisableDelete>1</DisableDelete>
</Event>
<Event>
<StartDateTime>2012-05-07T17:00:00+04:00</StartDateTime>
<EndDateTime>2012-05-07T18:00:00+04:00</EndDateTime>
<Description>This PERSONAL event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID2</SyncKeyRef>
<UserId>2</UserId>
</Event>
</Events>
</Message>