Getting Started with the Calendar API

Melody Quinn

November 12, 2020 20:12

The Calendar API is the ideal tool to get occupancy data from Ad Astra for integrating with other systems

Make sure to look over the code examples to see the basics of the authentication and to help in getting started. These examples are ready to compile once the Base URL and authentication information have been updated to match the desired site.

C# API Call Example

Java API Call Example

PHP API Call Example

When working with any API in Astra Schedule, the first step is to set up a user and an appropriate role in Astra. It is recommended to call the user “APIUser”. This makes for easy tracking of what processes are being done by this user and if there are any issues that occur in these operations.

The Role should be set so that the user is able to do see and execute the same behavior through the front end.

The role permissions do not currently restrict the what the API user can view. This functionality is being added soon.

Once the User has been created, signed into the Astra site and navigate to the Calendar page (Calendars header then select the Calendar option).

Using the Search bar, select some basic search options (Include Events, Include Academics).

Open a browser debugger (F12 in Chrome) and navigate to the network tab.

Next, click on the search button. The Calendar API call should display in the debugger. Click into the details of the call and you will see the full call in the Request URL.

This call can be copied and pasted into a new browser tab to return the data. By default, it returns in the JSON format and has a limit of 5000. This call can be altered in the browser to change these values.

Below, the URL has had the limit expanded to 10,000 and the view changed to XML:

https://test.aaiscloud.com/DemoAS8Solutions/~api/calendar/calendarList?_dc=1523027855849&start=0&limit=100&fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId&_s=1&filter=((EndDate%3E%3D%222018-04-06T00%3A00%3A00%22)%26%26((((((CurrentState%20in%20(%22Scheduled%22))%26%26(ActivityTypeCode%3D%3D2))%7C%7C(ActivityTypeCode%3D%3D1))%7C%7C(((ActivityTypeCode%3D%3D252)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D251)%26%26(ActivityId%3D%3Dnull))))%7C%7C(((ActivityTypeCode%3D%3D9)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D356)%7C%7C(ActivityTypeCode%3D%3D357))))%7C%7C(ActivityTypeCode%3D%3D255)))&sortOrder=%2BStartDate%2C%2BStartMinute&page=1

Notice that the Filter fields and filter portions of the call have been URL Encoded. This encoding is required for the Filter to be properly processed. If manually testing or troubleshooting, there are many URL Decoders available to see filter options from the calendar with standard logical formatting.

((EndDate>="2018-04-06T00:00:00")&&((((((CurrentState in ("Scheduled"))&&(ActivityTypeCode==2))||(ActivityTypeCode==1))||(((ActivityTypeCode==252)&&(ActivityId==null))||((ActivityTypeCode==251)&&(ActivityId==null))))||(((ActivityTypeCode==9)&&(ActivityId==null))||((ActivityTypeCode==356)||(ActivityTypeCode==357))))||(ActivityTypeCode==255)))

By default, the filter may look complex due to the fact of it being code generated. Most manually crafted filters will be much more simple and straightforward. The filters do not require the Id to be passed. They can use any accessible value. The most common filters are by date, activity type code, and location.

Activity Types

Activity Type codes should be used to make sure that only records of the expected types are being processed.

Code Name

1 Section

2 Event

9 Usage Policy

130 AdHoc Reservation

250 ResourceReservation

251 SetupTeardownWindow

252 PrePostMeeting

253 RoomBlockingEventResource

254 ResourceNotAllowedInRoom

255 PartitionConflict

356 Holiday

357 Announcement

358 Hybrid

Example with basic filtration would be all events and sections for the month of August in the “Washington” building

ActivityTypeCode in (1,2)&&EndDate>="2018-05-01T00:00:00"&&StartDate>="2018-03-31T23:59:59"&&Location.Room.Building.Name=="Washington"

When properly encoded

ActivityTypeCode%20in%20(1%2C2)%26%26EndDate%3E%3D%222018-05-01T00%3A00%3A00%22%26%26StartDate%3E%3D%222018-03-31T23%3A59%3A59%22%26%26Location.Room.Building.Name%3D%3D%22Washington%22

Full call that will return data in JSON format

https://test.aaiscloud.com/DemoAS8Solutions/~api/calendar/calendarList?_dc=1523027855849&start=0&limit=100&fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId&_s=1&filter=ActivityTypeCode%20in%20(1%2C2)%26%26EndDate%3E%3D%222018-05-01T00%3A00%3A00%22%26%26StartDate%3E%3D%222018-03-31T23%3A59%3A59%22%26%26Location.Room.Building.Name%3D%3D%22Washington%22&sortOrder=%2BStartDate%2C%2BStartMinute&page=1

By default, a limit is enforced on the call to manage site pagination and performance. This limit can be altered but is typically required. To determine if there is more data than your limit, the returned results will be equal with your limit number. That will indicate that there is another “page” of results. To access the next page, simply include the start option in the call with a value equal to the limit or its iterative values.

https://test.aaiscloud.com/DemoAS8Solutions/~api/calendar/calendarList?_dc=1523027855849&start=100&limit=100&fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId&_s=1&filter=ActivityTypeCode%20in%20(1%2C2)%26%26EndDate>%3D"2018-05-01T00%3A00%3A00"%26%26StartDate>%3D"2018-03-31T23%3A59%3A59"%26%26Location.Room.Building.Name%3D%3D"Washington"&sortOrder=%2BStartDate%2C%2BStartMinute&page=1

The Calendar API has direct access to a very wide array of information, but still allows access to other information through the entity associations.

Standard Access of The CalendarAPI

ActivityId

ActivityName

ParentActivityId

ParentActivityName

MeetingType

Description

StartDate

EndDate

StartMinute

EndMinute

ActivityTypeCode

LocationId

CampusName

BuildingCode

RoomNumber

RoomName

LocationName

StartDateTime

EndDateTime

InstitutionId

SectionId

IsExam

IsPrivate

EventId

CurrentState

MeetingStatus

UsageColor

UsageColorIsPrimary

EventTypeColor

ActivityPk

LocationPk

SectionPk

EventPk

Entity Associations

EventMeetingByActivityId

Event

HolidayByActivityId

PrePostMeetingByActivityId

Location

SectionMeetInstanceByActivityId

Section

SetupTeardownWindowByActivityId

When those values do not include a necessary element, both the filter and the fields can be modified to use associated data. The entity associations will require some basic knowledge of Astra and the concepts of how they connect.

For Example, filtering and returning the EventType to only return “Athletic”.

Encoded

fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId%2CEventMeetingByActivityId.Event.EventType.Name

Decoded

fields=ActivityId,ActivityPk,ActivityName,ParentActivityName,MeetingType,Description,StartDate,EndDate,StartMinute,EndMinute,ActivityTypeCode,LocationId,CampusName,BuildingCode,RoomNumber,RoomName,LocationName,StartDateTime,EndDateTime,InstitutionId,SectionId,SectionPk,IsExam,IsPrivate,EventId,EventPk,CurrentState,UsageColor,UsageColorIsPrimary,EventTypeColor,RoomId:Location.RoomId,EventMeetingByActivityId.Event.EventType.Name

Filter

filter=((EndDate%3E%3D%222018-04-06T00%3A00%3A00%22)%26%26(((((((EventMeetingByActivityId.Event.EventType.Name%20in%20(%22Internal Meeting%22))%26%26(CurrentState%20in%20(%22Scheduled%22)))%26%26(ActivityTypeCode%3D%3D2))%7C%7C((ActivityTypeCode%3D%3D1)%26%26(ActivityId%3D%3Dnull)))%7C%7C(((ActivityTypeCode%3D%3D252)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D251)%26%26(ActivityId%3D%3Dnull))))%7C%7C(((ActivityTypeCode%3D%3D9)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D356)%7C%7C(ActivityTypeCode%3D%3D357))))%7C%7C(ActivityTypeCode%3D%3D255)))

The full functional call would be

https://test.aaiscloud.com/DemoAS8Solutions/~api/calendar/calendarList?_dc=1523032386088&start=0&limit=100&fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId%2CEventMeetingByActivityId.Event.EventType.Name&_s=1&=((EndDate%3E%3D%222018-04-06T00%3A00%3A00%22)%26%26(((((((EventMeetingByActivityId.Event.EventType.Name%20in%20(%22Internal Meeting%22))%26%26(CurrentState%20in%20(%22Scheduled%22)))%26%26(ActivityTypeCode%3D%3D2))%7C%7C((ActivityTypeCode%3D%3D1)%26%26(ActivityId%3D%3Dnull)))%7C%7C(((ActivityTypeCode%3D%3D252)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D251)%26%26(ActivityId%3D%3Dnull))))%7C%7C(((ActivityTypeCode%3D%3D9)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D356)%7C%7C(ActivityTypeCode%3D%3D357))))%7C%7C(ActivityTypeCode%3D%3D255)))&sortOrder=%2BStartDate%2C%2BStartMinute&page=1

When making these associations, sometimes the header value can get unmanageable. Due to this, the XML or JSON column header can be cast by using the Columns option in the call.

For example, setting the Event Type the value of EventType rather than <call>

In the full URL

https://test.aaiscloud.com/DemoAS8Solutions/~api/calendar/calendarList?_dc=1523032386088&start=0&limit=100&fields=ActivityId%2CActivityPk%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CLocationId%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CUsageColor%2CUsageColorIsPrimary%2CEventTypeColor%2CRoomId%3ALocation.RoomId%2CEventMeetingByActivityId.Event.EventType.Name&_s=1&columns:ActivityId|1,ActivityPk|2,ActivityName|3,ParentActivityName|4,MeetingType|4,Description|5,StartDate|6,EndDate|7,StartMinute|8,EndMinute|9,ActivityTypeCode|10,RoomConfigId|11,CampusName|12,BuildingCode|13,RoomNumber|14,RoomName|15,LocationName|16,StartDateTime|17,EndDateTime|18,InstitutionId|19,SectionId|20,SectionPk|21,IsExam|22,IsPrivate|23,EventId|24,EventPk|25,CurrentState|26,UsageColor|27,UsageColorIsPrimary|28,EventTypeColor|29,RoomId|30,EventType|31&=((EndDate%3E%3D%222018-04-06T00%3A00%3A00%22)%26%26(((((((EventMeetingByActivityId.Event.EventType.Name%20in%20(%22Internal%20Meeting%22))%26%26(CurrentState%20in%20(%22Scheduled%22)))%26%26(ActivityTypeCode%3D%3D2))%7C%7C((ActivityTypeCode%3D%3D1)%26%26(ActivityId%3D%3Dnull)))%7C%7C(((ActivityTypeCode%3D%3D252)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D251)%26%26(ActivityId%3D%3Dnull))))%7C%7C(((ActivityTypeCode%3D%3D9)%26%26(ActivityId%3D%3Dnull))%7C%7C((ActivityTypeCode%3D%3D356)%7C%7C(ActivityTypeCode%3D%3D357))))%7C%7C(ActivityTypeCode%3D%3D255)))&sortOrder=%2BStartDate%2C%2BStartMinute&page=1