Update.Calendar.Event.ConnectEvents

Updates one or many calendar events (course) by linking event to another event as "Next event". Users specified in a content of the message are assigned as creators and owners of respective events. It's only possible to use this event when "Enable French calendar layout" customer setting is on for the site.

Action

Message with that type will update calendar events by setting their next events. Events should be course events. If "ShowExtraDescription" parameter was set to false, it will be automatically set to true. If the target event was previously connected to another calendar event (which might be even outside of event scope mentioned in the message), the connection will automatically be deleted.

Scenario

In order to set next events for course calendar events, a user needs to add a message with type corresponding to action Update.Calendar.Event.ConnectEvents. The message type is synchronous, so the results of message processing can be read from the response.

Input parameters

Message type

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
SyncKeys	Event SyncKeys array.	SyncKeysType From 1 to 1000	M
EventConnections	Calendar event connections	EventConnectionsType	M

SyncKeysType

Name	Description	Type	M/O
SyncKey	Events’ SyncKeys.	ID	M

EventConnectionsType

Name	Description	Type	M/O
EventConnection	A single event connection.	EventConnectionType From 1 to 500	M

EventConnectionType

Name	Description	Type	M/O
SourceEventSyncKeyRef	A reference to source event SyncKey (SyncKey itself is defined above).	IDREF	M
NextEventSyncKeyRef	A reference to SyncKey of the event which is going to be connected as next event (SyncKey itself is defined above). When not specified, there will be "disconnect" operation instead (when you're going to disconnect any event from event specified as SourceEventSyncKeyRef.	IDREF	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

Notes:

Either editor's UserId or UserSyncKey must be specified. This means specify at least one is mandatory.

Output

Finished status

Message	Description
The connection between event and next event is set.	The successful result of connect operation
Next event is disconnected.	The successful result of disconnect operation
There is no need to update the connection between event and next event, it was already set.	Connect operation: Message is valid, but there's nothing to update in the database, everything was already set like that.
There is no need to disconnect the next event, it was already disconnected.	Disconnect operation: Message is valid, but there's nothing to update in the database, everything was already set like that.

Warning status

Message	Description
Event '{sourceEventSyncKey}': 'ShowExtraDescription' was previously set to false. It's now set to true.	Occurs when adding next event to the event with given sync key, but its 'ShowExtraDescription' was previously set to false.
Event '{sourceEventSyncKey}': Event '{nextEventSyncKey}' was set to be the next event of another event (ID={oldPreviousEvent.EventId}, SyncKey='{oldPreviousEvent.SyncKey}'). Previous connection is deleted.	Occurs when event, which is going to be connected as next event already was the next event of another event (which could even be created manually). In such case the previous connection is deleted. Next event is then connected to the event mentioned in the operation.

Errors status

Message	Description
Invalid format / parameters (different to specified schema).
SyncKey is not unique.
Message must contain valid UserId/UserSyncKey.
User with specified UserId/UserSyncKey is not valid.
User with specified UserId/UserSyncKey is deleted.
User with specified UserId/UserSyncKey is external.
Message must contain valid CourseId/CourseSyncKey.
Course with specified CourseId/CourseSyncKey is not valid.
Course is deleted.
Course is external.
Course is archived.
Calendar is disabled for user ‘{Person ID or SyncKey}’.	Occurs when calendar is disabled in person profile/policy.
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.
Event ‘{sourceEventSyncKey}’ 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.
Event ‘{sourceEventSyncKey}’ 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.
Event '{sourceEventSyncKey}': Your security settings doesn't allow you to perform that operation. Please contact administration to grant you an access to {HierarchyName} organisation.	Occurs when the organisation level security settings prohibit you access to a related course.
Event '{sourceEventSyncKey}': 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.
Event '{sourceEventSyncKey}' cannot be updated because its 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).
Event '{sourceEventSyncKey}' cannot be updated, because 'Enable French calendar layout' customer setting is off.	The whole operation can only be performed when 'Enable French calendar layout' customer setting is ON.
Event '{sourceEventSyncKey}' cannot be updated, because its next event '{nextEventSyncKey}' does not exist in itslearning or the event was permanently deleted through the API.	Occurs when setting non-existing event to be next event.
Event '{sourceEventSyncKey}' cannot be updated, because its next event '{nextEventSyncKey}' has been manually deleted in itslearning.	Occurs when setting previously imported event (which has been deleted from itslearning) as next event.
Event '{sourceEventSyncKey}' cannot be updated because it's not course event.	The connection between events can only be set for course events. Source event is not course event.
Event '{nextEventSyncKey}' is not course event. It cannot be set as next event of event '{sourceEventSyncKey}'.	The connection between events can only be set for course events. The event, which is going to be set as next event is not course event.
Event '{nextEventSyncKey}' cannot be set as next event of event '{sourceEventSyncKey}' because they belong to different courses.	Source and next events belong to different courses. They should belong to the same courses in order to connect them.
The start date of event '{nextEventSyncKey}' cannot be before the end date of event '{sourceEventSyncKey}'.	Next event's start date should be after current event's end date.
Event '{sourceEventSyncKey}' occurs more than once in the message.	The sync key of source event occurs more than once (as SourceEventSyncKeyRef) in the message.
Event '{nextEventSyncKey}' cannot be set as next event of event '{sourceEventSyncKey}' because it's set as next event of more than one event. Affected events: {listOfSourceEventSyncKeys}.	The sync key of next event occurs more than once (as NextEventSyncKeyRef) in the message and relates to several different source events).

Schema

Update.Calendar.Event.ConnectEvents 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="EventConnections" type="EventConnectionsType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="SyncKeysType">
    <xs:sequence>
      <xs:element name="SyncKey" type="SyncKeyType" minOccurs="1" maxOccurs="1000" />
    </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="EventConnectionsType">
    <xs:sequence>
      <xs:element name="EventConnection" type="EventConnectionType" minOccurs="1" maxOccurs="500" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="EventConnectionType">
    <xs:sequence>
      <xs:element name="SourceEventSyncKeyRef" type="xs:IDREF" minOccurs="1" maxOccurs="1" />
      <xs:element name="NextEventSyncKeyRef" type="xs:IDREF" 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:sequence>
  </xs:complexType>
</xs:schema>

Message content example

Update.Calendar.Event.ConnectEvents message example

<Message xmlns="urn:message-schema">
  <SyncKeys>
    <SyncKey ID="ID1">YK_040</SyncKey>
    <SyncKey ID="ID2">YK_041</SyncKey>
    <SyncKey ID="ID3">YK_042</SyncKey>
    <SyncKey ID="ID4">YK_043</SyncKey>
    <SyncKey ID="ID5">YK_044</SyncKey>
  </SyncKeys>
  <EventConnections>
    <EventConnection>
     <SourceEventSyncKeyRef>ID1</SourceEventSyncKeyRef>
     <NextEventSyncKeyRef>ID4</NextEventSyncKeyRef>
     <UserId>400020</UserId>
    </EventConnection>
    <EventConnection>
     <SourceEventSyncKeyRef>ID2</SourceEventSyncKeyRef>
     <NextEventSyncKeyRef>ID3</NextEventSyncKeyRef>
     <UserId>400020</UserId>
    </EventConnection>
    <EventConnection>
     <SourceEventSyncKeyRef>ID5</SourceEventSyncKeyRef>
     <UserId>400020</UserId>
    </EventConnection>
  </EventConnections>
</Message>