Getting Started with the Calendar API

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).

mceclip0.png

 

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

mceclip1.png

 

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

mceclip2.png

 

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.

mceclip3.png

 

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

 


Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.