Developer Platform (July 2017)

Calendar (Events and scheduling)

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

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 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 Values
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 Values
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 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: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.
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:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated 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:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated 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:
Query Parameters:
 
  • associatedEventsOnly (boolean) – Optional. Fetch only events with an associated entity.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated 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:
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.

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 (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:
  • 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:
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:
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:
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.11Deprecated 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:
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 see calendar events within the provided org unit.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated 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 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/(version)/(orgUnitId)/calendar/event/

Create a new event.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
 
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated 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 updated properties of the calendar event.

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