Developer Platform (October 2022)

Calendar (Events and scheduling)

«  News service (news items, user feed)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Courses (course offerings, templates, schemas)  »

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>
    "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
{
    "UserId": <number:D2LID>,  // Added as of LMS v20.20.3
    "Name": <string>,
    "DisplayName": <string>,  // Added as of LMS v20.21.6
    "Role": <string>,
    "DisplayRole": <string>,  // Added as of LMS v20.21.6
    "Duration": <number>,  // Added as of LMS v20.21.6
    "Visible": <boolean>  // Added as of LMS v20.21.6
}

This structure provides information on presenters configured within an event.

UserId, Name, Role

User ID, name, and presenter role name for the user who will be presenting.

DisplayName, DisplayRole

Display name and role 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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

DELETE /d2l/api/le/(version)/(orgUnitId)/calendar/event/(eventId)/presenter/(userId)

Removes a presenter from a specified calendar event.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • eventId (D2LID) – Event ID.

  • userId – User ID.

Status Codes:
API Versions:

  • 1.54+ – Route first appears in LMS v20.21.6.

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

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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:
Query Parameters:

  • associatedEventsOnly (boolean) – Optional. Fetch only events with an associated entity.

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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 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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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 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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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 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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

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:
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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 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:
JSON Parameters:
Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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.

POST /d2l/api/le/(version)/(orgUnitId)/calendar/event/(eventId)/presenter

Adds a presenter to a specified calendar event.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • eventId (D2LID) – Event ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.54+ – Route first appears in LMS v20.21.6.

Return. This action returns a EventDataInfo JSON data block containing the properties of the calendar 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:
Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.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.

GET /d2l/api/le/(version)/(orgUnitId)/calendar/event/(eventId)/access/

Retrieve a list of users with access to a specified calendar event.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • eventId (D2LID) – Event ID.

Query Parameters:

  • userId (D2LID) – Optional. Retrieve access for a single user.

  • roleId (D2LID) – Optional. Retrieve access for users with the given role.

Oauth2 Scopes:

calendar:access:read

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.46-1.50 – Deprecated as of LMS v20.22.1.

Return. This action returns a object list page containing the resulting UserAccess blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

«  News service (news items, user feed)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Courses (course offerings, templates, schemas)  »