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/284207449/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

Title

Event title text. Short text (no longer than 80 characters).

string

O

TitleReadOnlyInUi

Defines whether the ability to edit the title of the event in the user interface. If the value is not specified, it is considered false.

boolean

O

Description

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

string

O

ShowExtraDescription

Defines whether to show extra description text for event and make possibility to connect event to event as next event. The parameter can only be used when "Enable French calendar layout" customer setting is ON for site.

boolean

O

ExtraDescription

Extra description text for event. The parameter can only be used when "Enable French calendar layout" customer setting is ON for site.

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

KeepAttendance

Defines that for this event can keep attendance. This parameter used for course events and when "Attendance for HigherEd" used for a customer. If the value is not specified, it is considered true.

boolean

O

PlanId

The ID of the plan which imported event connect to. If the value is not specified, it is means event should be not connected to any plan. In case if there is not PlanId element in Update request, event will not be disconnected from previously connected plan. Event is only disconnected from the plan if Update request contains <PlanId>0</PlanId>.

integer

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.

  • PlanId can be specified for Course events only. If PlanId equals to 0 it means "Event should not be connected to a plan".
    During Update operations the event will be disconnected from a plan if was connected previously.


Description versus Event Notes:

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

images/download/attachments/284207449/calendar-event-edit.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/284207449/CalendarEventView.png


Connection to a plan

Dates of plans connected to events via Org Api cannot be changed by users in itslearning.

If the event connected to a plan via OrgApi this connection to plan can only be changed via OrgApi (impossible to change in UI).

When an event can be disconnected from the connected plan via Create request:

  • If a plan specified in the request already connected to other event on the other group or on the other date

When an event can be disconnected from the connected plan via Update request:

  • If the current event for whole course - all connected events will be disconnected except of events for all participants on the same date.

  • If the current event for a group - events on whole course or events on the same group will be disconnected except events on the same group and the same date.

Allowed to connect several events to one plan if they on the one date and have the same course group or on all participants in the course.

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

Following event(s) {disconnected event SyncKeys and Ids} were disconnected from plan with PlanID {PlanId} because the date of the event(s) had been changed.

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

No

Yes

Event '{EventSyncKey}': There was an event connected to this one as Next event. The connection is deleted due to 'ShowExtraDescription' set to false.

Occurs when updating an existing event setting 'ShowExtraDescription' to false. If there was any connection to next event, it will be deleted.

No

Yes

The planner is disabled in given course (Course Id {CourseId}).

Occurs when in the course of event 'Planner' setting is disabled.

Yes

Yes

PlanId ({PlanId}) must be numeric.

Occurs when PlanId is wrong.

Yes

Yes

PlanId ({PlanId}) must be larger than 0.

Occurs when PlanId is 0.

Yes

No

Plan with PlanId {PlanId} is not valid.

Ocurrs when plan with the specified PlanId is not exists.

Yes

Yes

Plan with PlanId {PlanId} is deleted.

Ocurrs when plan with the specified PlanId is deleted.

Yes

Yes

The plan with PlanId {PlanId} does not belong to given course (Course Id {CourseId}).

Occurs when specified plan does not belong to course of the event

Yes

Yes

Following event(s) {disconnected event SyncKeys and Ids} were disconnected from plan with PlanID {PlanId}

Occurs when during creating/updating event and connection it to the plan some already connected events were disconnected from this plan to prevent conflict.

Yes

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

Event '{SyncKey}' cannot be created because its start time is within the locked period in given course (Course Id {CourseId}).

Occurs when creating course event when course calendar is "locked" (not possible to create or edit events before certain date).

Yes

No

Event '{SyncKey}' cannot be updated because its new start time is within the locked period in given course (Course Id {CourseId}).

Occurs when trying to update course event by setting event's start time to be within "locked" period in given course (not possible to create or edit events before certain date).

No

Yes

Event '{SyncKey}' cannot be updated because its existing start time is within the locked period in given course (Course Id {CourseId}).

Occurs when trying to update course event which was within "locked" period in given course (not possible to create or edit events before certain date).

No

Yes

Event '{EventSyncKey}': 'ShowExtraDescription' or 'ExtraDescription' parameters can be defined only for course events.

Only course events can have extra descriptions. Personal events don't support that.

Yes

Yes

Event '{EventSyncKey}': 'ShowExtraDescription' parameter can't be set to true because the related feature is disabled for customer.

'ShowExtraDescription' and 'ExtraDescription' can only be used when "Enable French calendar layout" customer setting is ON for site.

Yes

Yes

Event '{EventSyncKey}': 'ExtraDescription' parameter can be defined only when 'ShowExtraDescription' is set to true.

Occurs when creating or updating event with 'ShowExtraDescription' set to false. In this case it's not possible to set 'ExtraDescription'

Yes

Yes

Event '{EventSyncKey}' has kept attendance in given course (Course Id {CourseId}). It's not possible to make this event personal.

Occurs when existing event is a course event which has kept attendance, but event is treated as personal (no course id or synckey defined)

No

Yes

Event '{EventSyncKey}' has kept attendance in given course (Course Id {CourseId}). It's not possible to change CourseId/CourseSyncKey.

Occurs when existing event is a course event which has kept attendance, but CourseId or CourseSyncKey is changed

No

Yes

Event '{EventSyncKey}' has kept attendance in given course (Course Id {CourseId}). It's not possible to change GroupHierarchyId/GroupHierarchySyncKey.

Occurs when existing event is a course event which has kept attendance, but GroupHierarchyId or GroupHierarchySyncKey is changed or not specified

No

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="SiteId" minOccurs="0" maxOccurs="1" type="xs:int" />
<xs:element name="VendorId" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<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="Title" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="80" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="TitleReadOnlyInUi" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="ShowExtraDescription" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:element name="ExtraDescription" 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:element name="KeepAttendance" type="xs:boolean" default="true" minOccurs="0" maxOccurs="1" />
<xs:element name="PlanId" type="xs:integer" 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="SiteId" minOccurs="0" maxOccurs="1" type="xs:int" />
<xs:element name="VendorId" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<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="Title" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="80" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="TitleReadOnlyInUi" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="ShowExtraDescription" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:element name="ExtraDescription" 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:element name="KeepAttendance" type="xs:boolean" default="true" minOccurs="0" maxOccurs="1" />
<xs:element name="PlanId" type="xs:integer" 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>
<Title>Coding practice</Title>
<TitleReadOnlyInUi>true</TitleReadOnlyInUi>
<Description>This COURSE event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID1</SyncKeyRef>
<IsLesson>true</IsLesson>
<PlanId>100</PlanId>
<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>
<Title>Coding practice</Title>
<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>
<Title>Coding practice</Title>
<TitleReadOnlyInUi>true</TitleReadOnlyInUi>
<Description>This COURSE event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID1</SyncKeyRef>
<IsLesson>true</IsLesson>
<KeepAttendance>false<?KeepAttendance>
<PlanId>101</PlanId>
<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>
<Title>Coding practice</Title>
<Description>This PERSONAL event has been imported through Migration toolkit</Description>
<SyncKeyRef>ID2</SyncKeyRef>
<UserId>2</UserId>
</Event>
</Events>
</Message>