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")))
Comments
Please sign in to leave a comment.