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 or AssociatedEntityInfo 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

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	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>  // Added to LE v1.18 API contract as of LMS v10.6.6
}

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.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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.0.

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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.0.

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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.0.

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.18+ – Route first appears in LMS v10.6.6.

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 of EventDataInfo 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.18+ – Route first appears in LMS v10.6.6.

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 of EventDataInfo 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.18+ – Route first appears in LMS v10.6.6.

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 of EventCountInfo 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.18+ – Route first appears in LMS v10.6.6.

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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.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 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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.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 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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.0.

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.12+ – Route first appears in LMS v10.6.0.

• 1.5-1.11 – Deprecated as of LMS v10.7.0.

• 1.4- – Obsolete as of LMS v10.7.0.

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.