Attributes¶

HIDDENUNIT_T

We use the term HIDDENUNIT_T to stand in for an appropriate integer value indicating the basic time unit used to express a range of visibility restriction time in conjunction with VISIBILITY_T.

Range unit type	Value
Days	1
Hours	2
Minutes	3

REPEAT_T

We categorize the various ways that events can recur using a number of different general types and use the term REPEAT_T to stand in for an appropriate integer value.

Repetition type	Values
None	1
Daily	2
Weekly	3
Monthly	4
Yearly	5

VISIBILITY_T

We categorize the various ways that events can appear or be hidden from view using a number of different general types and use the term VISIBILITY_T to stand in for an appropriate integer value. Note that we use this value in conjunction with HIDDENUNIT_T which expresses a basic unit for time ranges of visibility/hiding.

Visibility type	Values
Visible	1
HiddenUntil	2
HiddenStarting	3
VisibleBetween	4
Hidden	5

Calendar.AssociatedEntity¶

{
    "AssociatedEntityType": "<string>",
    "AssociatedEntityId": "<number:D2LID>"
}

Calendar.AssociatedEntityInfo¶

{
    "AssociatedEntityType": "<string>",
    "AssociatedEntityId": "<number:D2LID>",
    "Link": "<string>"
}

Calendar.EventData¶

Actions that clients take to create or update events use a structure like this to provide event property information to the service.

{
    "Title": "<string>",
    "Description": "<string>",
    "StartDateTime": "<string:UTCDateTime>|null",
    "EndDateTime": "<string:UTCDateTime>|null",
    "StartDay": "<string:LocalDateTime>|null",
    "EndDay": "<string:LocalDateTime>|null",
    "GroupId": "<number:D2LID>|null",
    "RecurrenceInfo": "{composite:Calendar.RecurrenceInfo}",
    "LocationId": "<number:D2LID>|null",
    "LocationName": "<string>",
    "AssociatedEntity": "{composite:Calendar.AssociatedEntity}",
    "VisibilityRestrictions": "{composite:Calendar.VisibilityInfo}"
}

GroupId

Events with a Group ID value are group calendar events associated with the group identified by the ID, within the org unit context. Events without this property are associated with the calling user context, within the org unit context.

Calendar.EventDataInfo¶

Actions that clients take to retrieve event information from the service will receive it in a structure like this one.

{
    "CalendarEventId": "<number:D2LID>",
    "OrgUnitId": "<number:D2LID>",
    "Title": "<string>",
    "Description": "<string>",
    "StartDateTime": "<string:UTCDateTime>|null",
    "EndDateTime": "<string:UTCDateTime>|null",
    "IsAllDayEvent": "<boolean>",
    "StartDay": "<string:LocalDateTime>|null",
    "EndDay": "<string:LocalDateTime>|null",
    "GroupId": "<number:D2LID>|null",
    "IsRecurring": "<boolean>",
    "RecurrenceInfo": "{composite:Calendar.RecurrenceInfo}",
    "LocationId": "<number:D2LID>|null",
    "LocationName": "<string>",
    "OrgUnitName": "<string>",
    "OrgUnitCode": "<string>",
    "IsAssociatedWithEntity": "<boolean>",
    "AssociatedEntity": "{composite:Calendar.AssociatedEntityInfo}",
    "HasVisibilityRestrictions": "<boolean>",
    "VisibilityRestrictions" : "{composite.Calendar.VisibilityInfo}"
}

Calendar.RecurrenceInfo¶

{
    "RepeatType": "<number:REPEAT_T>",
    "RepeatEvery": "<number>",
    "RepeatOnInfo": "{composite:Calendar.RepeatOnInfo}",
    "RepeatUntilDate": "<string:UTCDateTime>"
}

RepeatType

Recurrence frequency unit type (recurrence expressed in days, weeks, months, years, or no recurrence).

RepeatEvery

How many of the units make up the recurrence cycle (every two days, every four weeks, and so on).

RepeatOnInfo

Occurrence template to indicate which days in the week a repeating event occurs on. This property applies only with weekly RepeatType events.

RepeatUntil

A date and time after which this event will no longer recur.

Calendar.RepeatOnInfo¶

{
    "Monday": "<boolean>",
    "Tuesday": "<boolean>",
    "Wednesday": "<boolean>",
    "Thursday": "<boolean>",
    "Friday": "<boolean>",
    "Saturday": "<boolean>",
    "Sunday": "<boolean>"
}

This structure provides a template for the days of the week when a recurring event will occur, and the days on which it will not occur. If a day property is true, a repeating event will occur on that day; if a day property is false, the repeating event will not occur on that day.

Calendar.VisibilityInfo¶

{
    "Type": "<number:VISIBILITY_T>",
    "Range": "<number>|null",
    "HiddenRangeUnitType": "<number:HIDDENUNIT_T>|null",
    "StartDate": "<string:UTCDateTime>|null",
    "EndDate": "<string:UTCDateTime>|null",
}

This structure provides an encoding for the event’s visibility. By default, events are Visible.

Type

Type of visibility status, expressed by a VISIBILITY_T enumeration value. Depending on this property’s value, the remainder of the properties in this structure get used in different ways.

• Visible (1) means that the event is always visible.
• HiddenUntil (2) means that the event is hidden until some time before the StartDate, as determined by the Range and HiddenRangeUnitType. Thus, with a range of “four hours”, the event is invisible until four hours before the event’s start date; after that point, the event will be visible.
• HiddenStarting (3) means that the event is hidden some time after the EndDate, as determined by the Range and HiddenRangeUnitType. Thus, with a range of “two days”, the event is visible until two days after the event’s end date; after that point, the event will be hidden.
• VisibleBetween (4) means that the event is visible only between the StartDate and EndDate property times; outside that time range, the event remains hidden.
• Hidden (5) means that the event is always hidden.

Range

This value expresses the number of range units the visibility state should persist (for example, a value of 2 with a HiddenRangeUnitType value of 2 would mean two hours).

StartDate

Used by HiddenUntil and VisibleBetween restriction types; this value gets ignored in HiddenStarting, Visible, and Hidden types.

EndDate

Used by HiddenStarting and VisibleBetween restriction types; this value gets ignored in HiddenUntil, Visible, and Hidden types.

Actions¶

DELETE /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/event/(D2LID: eventId)¶

Remove a calendar event from a particular org unit.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID. eventId (D2LID) – Event ID.
Status Codes:	200 – Action succeeded. 403 – No permission to modify calendar event. 404 – Unable to find the calendar event.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

GET /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/event/(D2LID: eventId)¶

Retrieve a calendar event from a particular org unit.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID. eventId (D2LID) – Event ID.
Status Codes:	200 – Action succeeded. 403 – No permission to see calendar event. 404 – Unable to find the calendar event.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Return. This action returns a EventDataInfo JSON data block containing the properties of a calendar event.

GET /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/events/¶

Retrieve all the calendar events for the calling user, within the provided org unit context.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID.
Query Parameters:
	associatedEventsOnly – Optional. Boolean. Fetch only events with an associated entity.
Status Codes:	200 – Action succeeded. 403 – No permission to see calendar events.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Return. This action returns a JSON array of EventDataInfo data blocks.

GET /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/events/orgunits/¶

Retrieve all the calendar events for the calling user, within a number of org units.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID.
Query Parameters:
	orgUnitIdsCSV – Comma separated list of Org Unit IDs. startDateTime – UTCDateTime string for beginning of time window to examine. endDateTime – UTCDateTime string for end of time window to examine. bookmark – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:	200 – Action succeeded. 400 – Provided start date occurs after end date, or no provided list of Org Unit IDs. 403 – No permission to see calendar events.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Return. This action returns a paged result set containing the resulting EventDataInfo JSON data blocks for the segment following your bookmark parameter (or the first segment if that paramter is empty or missing).

GET /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/events/user/¶

Retrieve all the calander events for a specified user’s explicit enrollments within the organization containing the specified org unit.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID.
Query Parameters:
	userId – Long integer User ID (D2LID) for user to query. startDateTime – UTCDateTime string for beginning of time window to examine. endDateTime – UTCDateTime string for end of time window to examine. bookmark – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:	200 – Action succeeded. 400 – Provided start date occurs after end date, or invalid provided User ID. 403 – No permission to see calendar events within the provided org unit.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Input. This action retrieves events occurring between your provided start and end times (inclusive), for all of the specified user’s explicit enrollments within the organization containing the provided org unit ID.

Return. This action returns a paged result set containing the resulting EventDataInfo JSON data blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

Note

The calling user context must have a role giving permission to see calendar events within the org unit type associated with your provided org unit. The role permissions of the user identified with the userId query parameter is not considered when determining the permissions around this call.

POST /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/event/¶

Create a new event.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID.
Status Codes:	200 – Action succeeded. 400 – Invalid event data provided. 403 – No permission to create or modify events.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Input. Provide as POST data for this action a EventData JSON data block containing the properties for the new event to create.

Return. This action returns a EventDataInfo data block for the newly created event.

PUT /d2l/api/le/(D2LVERSION: version)/(D2LID: orgUnitId)/calendar/event/(D2LID: eventId)¶

Update the properties for a calendar event from a particular org unit.

Parameters:	version (D2LVERSION) – API version. orgUnitId (D2LID) – Org Unit ID. eventId (D2LID) – Event ID.
Status Codes:	200 – Action succeeded. 400 – Invalid update data for calender event provided. 403 – No permission to see calendar event. 404 – Unable to find the calendar event.
API Versions:	1.1+ – Route first appears in LMS v10.0.0.

Input. Provide a EventData JSON data block containing your updated properties for the calendar event.

Return. This action returns a EventDataInfo JSON data block containing the updated properties of the calendar event.