Calendar API |
|
|
|
|
Calendar API |
|
|
|
|
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.
There are several key elements involved in the calendar API that will come into play when interacting with the data and should be understood.
1.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.
Calendar API Data Elements and Associations
2.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 are also supported by the API, as shown in the following example:
Example:
(((StartDate>="2011-10-01T05:00:00.000Z")&&(EndDate<="2011-10-31T05:00:00.000Z"))&&(Location.Room.BuildingId in ("31ec568d-fc17-46f0-a7d5-462d294f8c9e")))
TIP: The calendar API test tool, described below, 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.
NOTE: The calendar API test tool lets you pick from a list of string values in the UI but then inserts actual GUIDs for the values selected when constructing the query. The queries may be used as is, with GUIDs. However, the API also supports using text string comparisons as well if preferred.
For example, if you want to get all activities occurring in a specific building, you could include Location.Room.BuildingId in "31ec568d-fc17-46f0-a7d5-462d294f8c9e" in your call, OR you could use Location.Room.Building.Name = "Jones Hall"
3.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
4.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.
NOTE: The vCal and RSS output formats have field requirements that should be noted. In both cases these formats require that specific fields in the return data map to specific fields in the output type. If the number of fields returned is limited by the user so that the required fields are no longer available to the output format, the format will not function.
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")))
A Calendar API test tool is provided within the Astra Schedule application. This tool may be used to test the results returned by a certain filter and output, as well as to help formulate the filter syntax that can be used in the API queries.
The test tool can be accessed by going to the following URL from within the Astra Schedule application:
http://*HostName*/*AstraScheduleInstance*/calendars/apitest/calendarapitest.aspx
The API test tool consists of the following elements:
•Filter Panel
A filter panel is provided on the far left side of the page. The filter controls here work similarly to other list page filters throughout the application. You may enter a keyword search, date range, and/or one or more filter criteria from the list. When "Search" is clicked, the list grid will update to show the matching results.
The purpose of this tool is to test certain filters to see if the data returned is what is desired.
•Activity List Grid
This grid shows a list of all activities returned by the search criteria. Activities may include event activities, section activities, holidays, and announcements. Review the data to be sure that the results are desired.
•Show URL
When satisfied with the results, the API query that returned the results can be copied directly by using the "Show URL" option. This can help you formulate the required API calls when creating a program that utilizes the API.
•List Output Options
The buttons across the top of the page allow you to test the list output formats supported by the API. Click one of the output buttons and the list of activities in the search results will be displayed or exported in the format desired.
•Detail Output Options
The buttons to the left of each row in the search results allow you to test the detail output formats supported by the API. Click one of the output buttons and the detail information for that specific activity will be displayed or exported in the format desired.
Page url: ?calendar_api.htm
