Astra Schedule Help (8.0)

Getting Started with the Calendar API

Hide Navigation Pane

Getting Started with the Calendar API

Previous topic Next topic  

Getting Started with the Calendar API

Previous topic Next topic JavaScript is required for the print function  

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.

 

noteNOTE: 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, log into the Astra site and navigate to the Calendar page (Calendars header then select the Calendar option).

 

CalendarAPI1

 

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

 

CalendarAPI2

 

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

 

CalendarAPI3

 

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.

 

CalendarAPI4

 

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

 

An example call 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.  

 

The standard access of the CalendarAPI includes:

 

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