Contents
Attributes¶
- ASSOCENTITY_T
We use the term ASSOCENTITY_T to stand in for a dictionary of string values indicating associated entities that can be indicated in a calender
AssociatedEntity
orAssociatedEntityInfo
property. Note that the list of types is dynamic: installed product components can provide new entity types into this list. Here is a list of known, core types:Associated entity type
Service object name
D2L.LE.Checklist.ChecklistItem
Checklist item
D2L.LE.Content.ContentObject.ModuleCO
Content module
D2L.LE.Content.ContentObject.TopicCO
Content topic
D2L.LE.Discussions.DiscussionForum
Discussion forum
D2L.LE.Discussions.DiscussionTopic
Discussion topic
D2L.LE.Dropbox.Dropbox
Dropbox
D2L.LE.Grades.GradeObject
Grade item
D2L.LE.Quizzing.Quiz
Quiz
D2L.LE.Survey.Survey
Survey
Associated entities are described by the entity type, and an entity ID. Where appropriate, you can use the entity ID as the identifier for use with that entity through the Brightspace APIs. For example, the AssociatedEntityId provided with an entity type of D2L.LE.Dropbox.Dropbox is the D2LID you can use in API calls to identify that associated dropbox.
- ASSOCIATION_T
We support filtering calendar events based on whether or not they have associated entities and use the term ASSOCIATION_T to stand in for an appropriate type by name or value.
Association type
Value
Any
1
AssociatedOnly
2
UnassociatedOnly
3
- EVENTTYPE_T
We support filtering calendar events based on the role they play within the user’s schedule and use the term EVENTTYPE_T to stand in for an appropriate type by name or value (for example, an event that acts as due date for an assigned activity would have the associated type DueDate).
Event type
Value
Reminder
1
AvailabilityStarts
2
AvailabilityEnds
3
UnlockStarts
4
UnlockEnds
5
DueDate
6
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
Value
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
Value
Visible
1
HiddenUntil
2
HiddenStarting
3
VisibleBetween
4
Hidden
5
-
Calendar.
AssociatedEntity
¶ { "AssociatedEntityType": <string:ASSOCENTITY_T>, "AssociatedEntityId": <number:D2LID> }
-
Calendar.
AssociatedEntityInfo
¶ { "AssociatedEntityType": <string:ASSOCENTITY_T>, "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.
- StartDay, EndDay
When creating or updating all-day events, these fields get used. The EndDay must be on a later day than the StartDay. The back-end system takes the date-time values you provide and strips off the time component.
When creating an all-day event, the service makes 00:00:00 on the start day as the earliest time that’s included in the all-day event, and 00:00:00 on the end day is the earliest time that’s not included in the all-day event.
For example, if you want to create an all-day event for April 4 that lasts for one day, you should provide a StartDay with any time on April 4, and an EndDay with any time on April 5, and the back-end service will use 00:00:00 on April 4 for the start date-time, and 00:00:00 on April 5th for the end date-time.
-
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> }, "CalendarEventViewUrl" : <string:URL> "Presenters" : [ // Array of PresenterInfo blocks { <composite:Calendar.PresenterInfo> }, { <composite:Calendar.PresenterInfo> }, ... ] }
-
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.
-
Calendar.
PresenterInfo
¶ { "Name": <string>, "Role": <string> }
This structure provides information on presenters configured within an event.
- Name
Contains the name of the user who will be presenting.
- Role
Contains the presenter role name for the user who will be presenting.
-
Calendar.
EventCountInfo
¶ { "OrgUnitId": <number:D2LID>, "UserId": <number:D2LID>, "EventCount": <number>, }
- EventCount
Number of events for a user in the provided course.
Actions¶
-
DELETE
/d2l/api/le/
(version)/
(orgUnitId)/calendar/event/
(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 OK – Action succeeded.
403 Forbidden – No permission to modify calendar event.
404 Not Found – Unable to find the calendar event.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/calendar/event/
(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 OK – Action succeeded.
403 Forbidden – No permission to see calendar event.
404 Not Found – Unable to find the calendar event.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Return. This action returns a
EventDataInfo
JSON data block containing the properties of a calendar event.
-
GET
/d2l/api/le/
(version)/
(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 (boolean) – Optional. Fetch only events with an associated entity.
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see calendar events.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Return. This action returns a JSON array of
EventDataInfo
data blocks.
-
GET
/d2l/api/le/
(version)/calendar/events/myEvents/
¶ Retrieve the calling user’s calendar events, within a number of org units (see query parameter)
- Parameters
version (D2LVERSION) – API version.
- Query Parameters
association (ASSOCIATION_T) – Optional. Association type.
eventType (EVENTTYPE_T) – Optional. Calendar event type.
orgUnitIdsCSV (CSV of D2LIDs) – List of org units in which to search.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid org unit ID or invalid event or association type or provided start date later than end date.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When calling this action, you must provide a list of org unit IDs that amount to some or all of the calling user’s active enrollments. You must also provide a time window within which to search (with the startDateTime and endDateTime parameters).
You can also filter the data retrieved based on its association type (by default, Any).
If you provide Any or AssociatedOnly for the association query parameter, then the items retrieved by this action include the appropriate
AssociatedEntity
structure.Return. An
ObjectListPage
JSON block containing a list ofEventDataInfo
JSON data blocks.Note that this action first sorts results in descending order by StartDateTime in the EventDataInfo structure (or, by StartDate, if StartDateTime is null), and then sorts by CalendarEventId; this helps newer activities appear closer to the top of the sorted list.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/calendar/events/myEvents/
¶ Retrieve the calling user’s events for a particular org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters
association (ASSOCIATION_T) – Optional. Association type.
eventType (EVENTTYPE_T) – Optional. Calendar event type.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid org unit ID or invalid event or association type or provided start date later than end date.
403 Forbidden – No permission to see calendar event in specified org unit.
404 Not Found – Specified org unit does not exist.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When calling this action, you can filter the data retrieved based on its association type (by default, Any) or whether an item’s due date falls within a provided time window.
If you provide Any or AssociatedOnly for the association query parameter, then the items retrieved by this action includes the appropriate
AssociatedEntity
structures.Return. An
ObjectListPage
JSON block containing a list ofEventDataInfo
JSON data blocks.Note that this action first sorts results in descending order by StartDateTime (or, by StartDate, if StartDateTime is null), and then sorts by CalendarEventId; this helps newer activities appear closer to the top of the sorted list.
-
GET
/d2l/api/le/
(version)/calendar/events/myEvents/itemCounts/
¶ Retrieve a count of calling user’s calendar events, within a number of org units (see query parameter).
- Parameters
version (D2LVERSION) – API version.
- Query Parameters
association (ASSOCIATION_T) – Optional. Association type.
eventType (EVENTTYPE_T) – Optional. Calendar event type.
orgUnitIdsCSV (CSV of D2LIDs) – List of org units in which to search.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid org unit ID or invalid event or association type or provided start date later than end date.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When calling this action, you must provide a list of org unit IDs that amount to some or all of the calling user’s active enrollments. You can also filter the data retrieved based on its association type (by default, Any) or whether an event’s time falls within a provided time window.
Return. An
ObjectListPage
JSON block containing a list ofEventCountInfo
JSON data blocks.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/calendar/events/myEvents/itemCount
¶ Retrieve a count of calling user’s calendar events, within the provided org unit context.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters
association (ASSOCIATION_T) – Optional. Association type.
eventType (EVENTTYPE_T) – Optional. Calendar event type.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid org unit ID or invalid event or association type or provided start date later than end date.
403 Forbidden – No permission to see calendar event in specified org unit.
404 Not Found – Specified org unit does not exist.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When calling this action, you can filter the data retrieved based on its association type (by default, Any) or whether an item’s due date falls within a provided time window.
Return. An
EventCountInfo
JSON data block.
-
GET
/d2l/api/le/
(version)/
(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 (CSV) – List of Org unit IDs.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Provided start date occurs after end date, or no provided list of Org unit IDs.
403 Forbidden – No permission to see calendar events.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Return. This action returns a
paged result set
containing the resultingEventDataInfo
JSON data blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/calendar/events/user/
¶ Retrieve all the calendar 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 (D2LID) – User to query.
startDateTime (UTCDateTime) – Start of time window to examine.
endDateTime (UTCDateTime) – End of time window to examine.
bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Provided start date occurs after end date, or invalid provided User ID.
403 Forbidden – No permission to manage calendar events within the provided org unit (see note in description).
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
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 resultingEventDataInfo
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 manage calendar events within the org unit type associated with your provided org unit. Additionally, the user identified with the userId query parameter must have a role giving them permission to see the calendar events for the provided org unit.
-
POST
/d2l/api/le/
(version)/
(orgUnitId)/calendar/event/
¶ Create a new event.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters
EventData (
Calendar.EventData
) – Properties for the new calendar event.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid event data provided.
403 Forbidden – No permission to create or modify events.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When creating all-day events, note that the service uses only the information in the StartDay and EndDay fields and ignores any time component of the date-time value you pass in for those fields. The EndDay must be on a later date than the StartDay.
When creating an all-day event, the service makes 00:00:00 on the start day as the earliest time that’s included in the all-day event, and 00:00:00 on the end day is the earliest time that’s not included in the all-day event.
When creating other kinds of events, the service uses only the StartDateTime and EndDateTime fields instead.
Return. This action returns a
EventDataInfo
data block for the newly created event.
-
PUT
/d2l/api/le/
(version)/
(orgUnitId)/calendar/event/
(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.
- JSON Parameters
EventData (
Calendar.EventData
) – Properties for the updated calendar event.
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid update data for calendar event provided.
403 Forbidden – No permission to see calendar event.
404 Not Found – Unable to find the calendar event.
- API Versions
1.34+ – Route first appears in LMS v20.19.5.
1.27-1.33 – Deprecated as of LMS v20.20.1.
1.26- – Obsolete as of LMS v20.20.1.
Input. When updating all-day events, note that the service uses only the information in the StartDay and EndDay fields and ignores any time component of the date-time value you pass in for those fields. The EndDay must be on a later date than the StartDay.
When updating an all-day event, the service makes 00:00:00 on the start day as the earliest time that’s included in the all-day event, and 00:00:00 on the end day as the earliest time that’s not included in the all-day event.
When updating other kinds of events, the service uses only the StartDateTime and EndDateTime fields instead.
Return. This action returns a
EventDataInfo
JSON data block containing the updated properties of the calendar event.