Calendar API Overview

The Astra Schedule Calendar API was created to provide access to calendar activity data for use by third party programs.  Activities and their directly related data components may be queried and filtered using the API and utilized in other systems, displays, and output types outside of the Astra Schedule application.

The Astra Schedule calendar API makes the activity data available for consumption.  It is the responsibility of the institution to create any programs that utilize the API and to display the content.

Key Components of the Calendar API

There are several key elements involved in the calendar API that will come into play when interacting with the data and should be understood.

Data Structures

Understanding the data structure and relationships for the activity and related data you are interested in is a key element in utilizing the API. Common basic activity data elements and relationships are provided below.  If additional information is desired, please contact Ad Astra for assistance. See the Calendar API Data Elements and Associations article for detailed information. 

Filter Syntax

It is likely that you will want to filter the data returned by the API in some way to limit the number of records you have to work with. Learning how to structure the filter syntax is important in getting the correct results. Common examples of filtering include:

Keyword ("ART")

(((ActivityName?="%ART%")||(ParentActivityName?="%ART%"))||(Description?="%ART%"))

Date Range

((StartDate>="2011-11-01T05:00:00.000Z")&&(EndDate<="2011-11-30T06:00:00.000Z"))

Campus ("Main")

(Location.Room.Building.CampusId in ("c2b87e48-dd05-450e-9845-d66ed0c3e7a4"))

Building

(Location.Room.BuildingId in ("31ec568d-fc17-46f0-a7d5-462d294f8c9e"))

Event Type

(EventMeetingByActivityId.Event.EventTypeId in ("e16ec8d9-eb07-4fa3-aa98-357ff6b27b88"))

Standard Operators

Standard operators are also supported by the API, as shown in the following example:

(((StartDate>="2011-10-01T05:00:00.000Z")&&(EndDate<="2011-10-31T05:00:00.000Z"))&&(Location.Room.BuildingId in ("31ec568d-fc17-46f0-a7d5-462d294f8c9e")))

Creating Filters

The calendar API test tool can assist in creating filters for use when calling the API. Filters may be set and tested using the user interface and then the queries can be copied and pasted into your program.

For example, if you want to get all activities occurring in a specific building, you could include Room.BuildingId in "31ec568d-fc17-46f0-a7d5-462d294f8c9e" in your call, OR you could use Location.Room.Building.Name = "Jones Hall"

Fields

The API returns a list of fields by default when activities are returned by a query, based upon the activity type. The results grid in the test tool displays these fields. However, you can restrict the list of fields returned in your query. Example of the default fields provided for list queries:

fields: ActivityName,ParentActivityName,Description,StartDate,EndDate,StartMinute,EndMinute,ActivityTypeCode,CampusName,BuildingCode,RoomNumber,RoomName

Example of the default fields provided for event detail queries:

fields: ActivityId,ActivityName,ParentActivityName,Description,StartDate,EndDate,StartMinute,EndMinute,ActivityTypeCode,LocationId,CampusName,BuildingCode,RoomNumber,RoomName,InstitutionId,ReservationNumber:EventMeetingByActivityId.Event.ReservationNumber,Customer:EventMeetingByActivityId.Event.Customer.Name,ContactFirstName:EventMeetingByActivityId.Event.PrimaryCustomerContact.Person.FirstName,ContactLastName:EventMeetingByActivityId.Event.PrimaryCustomerContact.Person.LastName,MeetingType:EventMeetingByActivityId.EventMeetingType.Name

Data Format Result Types

The API can return activity data in various output formats. The API call must specify the "view" format desired. See example query below:

The output format options provided include Excel, XML, RSS, vCal, Text, JSON, and HTML.

API Query Example

"All activities from 10/1/2011 through 10/31/2011 in the Adams building using the vCal output format."

url: http://localhost:59697/~api/calendar/calendarList?action=get

view: vcal

columns:
ActivityName|0,ParentActivityName|1,Description|2,StartDate|3,EndDate|4,StartMinute|5,EndMinute|6,ActivityTypeCode|7,CampusName|8,BuildingCode|9,RoomNumber|10,RoomName|11

fields:
ActivityName,ParentActivityName,Description,StartDate,EndDate,StartMinute,EndMinute,ActivityTypeCode,CampusName,BuildingCode,RoomNumber,RoomName

sortOrder:
+StartMinute,+StartDate

filter:
(((StartDate>="2011-10-01T05:00:00.000Z")&&(EndDate<="2011-10-31T05:00:00.000Z"))&&(Location.Room.BuildingId in ("31ec568d-fc17-46f0-a7d5-462d294f8c9e")))