Anthology Logo
search rss_feed menu

Using the calendars APIs with Ultra

Tested with Blackboard Learn version 3900.48.0

You can review the model in our developer portal for details on each attribute on each endpoint: model of each endpoint

Introduction

Let’s say you are a student and let’s say you want to keep track of your day to day, what do you do? Yes, a to-do list… Not quite, You can use the tools that already exist and a Calendar is more than enough to know your due dates, create activites with a deadline or just to know what is today’s date.

This also applies to administrators and instructors, what if you want to create new items for your students based on gradebook columns, or reminders of meetings? What about an integration with third party tools such as Zoom or Collaborate where you can set the link of the meeting, the occurrency and how frequent the event is? Well, this API will help you do that!

To start, we have five different “types” of calendars (We will reference this types as calendarItemType)

Where is the Institutional and Personal Calendar?

The Institutional/Personal calendar is marked as such in the calendar, Where can you see them? Well in Ultra, in the main menu, you may see a Schedule/Calendar on your main menu at login:

Calendar api image in learn

When you click in the gear in the top right of the page it will allow you to filter per calendar, You can select which calendars you want to see, Including Personal and institutional:

Calendar api image in learn - submenu

The course calendars show up automatically when you are enrolled in a course, those will show up here as well when enrolled.

Want to learn even more about calendars? Please visit Our calendar guide to go above and beyond!

What about in a course?

For Students, Instructors and course builders

All users that are part of a course see the same things, both calendar and the Course schedule.

Calendar api image in learn in a course

There are clearly several differences between users given each role capabilities:

Course view for an instructor vs student

Creating a new Item in Learn

As an Instructor, when you want to create a new item for the Course schedule, The UI looks like this:

Calendar flow in the GUI

When the item is finally created, it looks then like a small card, you can edit it or delete it:

Calendar event card

Mapping a calendar Item to the API payload

This is an example of how a Course schedule item looks like in the GUI and in the payload when calling it using:

Mapping between calendar an the API payload

Calendar C.R.U.D

It is not possible to create, update or delete calendars, you can only read them, this is because, the calendars are either Personal or Institutional by default, The course calendars are added automatically when the user is enrolled on a course.

There is an important difference that needs to be made and that is Calendar items are part of calendars and calendar items are owned by the persosns who have access to them. The only way calendar items are created, updated or deleted by an application is if it is acting on behalf of the person who owns the calendar.

Payload example

{
  "results": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "paging": {
    "nextPage": "string"
  }
}

A little example of how this looks in real life, when you are enrolled in a course, a calendar is automatically generated, If you only have 1 course, then it will look something like this when you make an API call:

{
  "results": [
    {
      "id": "INSTITUTION",
      "name": "Institution"
    },
    {
      "id": "PERSONAL",
      "name": "Personal"
    },
    {
      "id": "_905_1",
      "name": "CalendarCourseLearning: Calendar Course Learning"
    }n
  ]
}

When looking at this on Learn, Instructors and Students have a pretty much identical view, the only difference is the Calendar capability to manage Course calendar items:

Difference between instructor view and student view in calendars

Calendar Items C.R.U.D

We are not able to create, update or delete Calendars BUT We can create new items on those calendars.

Please keep in mind that:

Pre-requisites

In order to use calendar items you need the following:

For office-hours

About GET /calendar/items

Payload example

{
  "results": [
    {
      "id": "string",
      "type": "Course",
      "calendarId": "string",
      "calendarName": "string",
      "title": "string",
      "description": "string",
      "location": "string",
      "start": "2022-09-29T19:14:37.520Z",
      "end": "2022-09-29T19:14:37.520Z",
      "modified": "2022-09-29T19:14:37.520Z",
      "color": "string",
      "disableResizing": true,
      "createdByUserId": "string",
      "dynamicCalendarItemProps": {
        "attemptable": true,
        "categoryId": "string",
        "dateRangeLimited": true,
        "eventType": "string",
        "gradable": true
      },
      "recurrence": {
        "count": 0,
        "frequency": "Monthly",
        "interval": 0,
        "monthRepeatDay": 0,
        "monthPosition": 0,
        "originalStart": "2022-09-29T19:14:37.520Z",
        "originalEnd": "2022-09-29T19:14:37.520Z",
        "repeatBroken": true,
        "repeatDay": "Sunday",
        "until": "2022-09-29T19:14:37.520Z",
        "weekDays": ["Sunday"]
      }
    }
  ],
  "paging": {
    "nextPage": "string"
  }
}

About POST /calendar/items

This endpoint creates a calendar item, items can be single or recurring.

Personal and institutional calendars

Course calendars

GradebookColumn calendar

OfficeHours

Payload example

{
  "type": "Course",
  "calendarId": "string",
  "title": "string",
  "description": "string",
  "location": "string",
  "start": "2022-09-29T20:30:04.346Z",
  "end": "2022-09-29T20:30:04.346Z",
  "disableResizing": true,
  "recurrence": {
    "count": 0,
    "frequency": "Monthly",
    "interval": 0,
    "monthRepeatDay": 0,
    "monthPosition": 0,
    "originalStart": "2022-09-29T20:30:04.346Z",
    "originalEnd": "2022-09-29T20:30:04.346Z",
    "repeatBroken": true,
    "repeatDay": "Sunday",
    "until": "2022-09-29T20:30:04.346Z",
    "weekDays": ["Sunday"]
  }
}

Now we can return specific items per calendar, remove them or update them:

About GET {calendarItemType}/{calendarItemId}

Personal and institutional calendars

Course calendars

GradebookColumn calendar

OfficeHours

Payload example

{
  "id": "string",
  "type": "Course",
  "calendarId": "string",
  "calendarName": "string",
  "title": "string",
  "description": "string",
  "location": "string",
  "start": "2022-09-30T15:58:25.082Z",
  "end": "2022-09-30T15:58:25.082Z",
  "modified": "2022-09-30T15:58:25.082Z",
  "color": "string",
  "disableResizing": true,
  "createdByUserId": "string",
  "dynamicCalendarItemProps": {
    "attemptable": true,
    "categoryId": "string",
    "dateRangeLimited": true,
    "eventType": "string",
    "gradable": true
  },
  "recurrence": {
    "count": 0,
    "frequency": "Monthly",
    "interval": 0,
    "monthRepeatDay": 0,
    "monthPosition": 0,
    "originalStart": "2022-09-30T15:58:25.082Z",
    "originalEnd": "2022-09-30T15:58:25.082Z",
    "repeatBroken": true,
    "repeatDay": "Sunday",
    "until": "2022-09-30T15:58:25.082Z",
    "weekDays": ["Sunday"]
  }
}

About DELETE {calendarItemType}/{calendarItemId}

With this endpoint you can delete a calendar item or series, however, the following must be true in order to delete a calendar item:

Personal and institutional calendars

Course calendars

GradebookColumn calendar

OfficeHours

Payload example

When using DELETE {calendarItemType}/{calendarItemId} the endpoint returns:

204 No content

About PATCH {calendarItemType}/{calendarItemId}

With this endpoint you can update a calendar item or series, however, the following must be true in order to delete a calendar item:

When updating the series the existing CalendarItems will be removed and a new set of CalendarItems will be created. This is the same behavior as experienced via the UI.

Personal and institutional calendars

Course calendars

GradebookColumn calendar

OfficeHours

Payload example

{
  "id": "string",
  "type": "Course",
  "calendarId": "string",
  "calendarName": "string",
  "title": "string",
  "description": "string",
  "location": "string",
  "start": "2022-09-30T16:36:40.313Z",
  "end": "2022-09-30T16:36:40.313Z",
  "modified": "2022-09-30T16:36:40.313Z",
  "color": "string",
  "disableResizing": true,
  "createdByUserId": "string",
  "dynamicCalendarItemProps": {
    "attemptable": true,
    "categoryId": "string",
    "dateRangeLimited": true,
    "eventType": "string",
    "gradable": true
  },
  "recurrence": {
    "count": 0,
    "frequency": "Monthly",
    "interval": 0,
    "monthRepeatDay": 0,
    "monthPosition": 0,
    "originalStart": "2022-09-30T16:36:40.313Z",
    "originalEnd": "2022-09-30T16:36:40.313Z",
    "repeatBroken": true,
    "repeatDay": "Sunday",
    "until": "2022-09-30T16:36:40.313Z",
    "weekDays": ["Sunday"]
  }
}