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