Timetable
Overview
The Timetable product integration allows students, lecturers, and other users of the app to view their schedule or list of calendar events for the day, week, month, and year through the app using their mobile devices or PCs.
Note that this product integration requires Ex Libris team work. Please submit a Support ticket for full configuration. See more information in the Configuration section.
Vendors
Timetable feeds can be retrieved with Celcat, Ellucian Banner, Ellucian Colleague (custom), MyTimetable (Eveoh), Oracle PeopleSoft, and RESTful APIs.
It is possible to have multiple Timetable feeds, which can have different formats (for example, 2 MyTimetable feeds and 1 Banner feed) with different configurations accordingly.User Experience
User Activities
- Users can see their events from multiple Timetable feeds.
- Users can select specific Timetable feeds to view.
- Users can see a list of events in a daily, weekly, or monthly view.
- Users can see the following details about a specific event: Start Time, End Time, Location information, etc.
- Users can select the option to display a blended view.
User Flow Diagram
Authentication
Offline Support
- On native (Android/ iOS):
The cache size is configured in the Web Service Endpoint. If a user enters the app after more time than configured in the Frequency for Checking parameter (defined in Web Service Endpoint), the calendars are refreshed according to the size of the cache. A refresh occurs even if the Timetable Refresh (Web Service Endpoint) parameter is set to NO. Also, when the user accesses the Timetable tile after the app is refreshed, the current block (week or month based on the device) is refreshed. If the user scrolls to a block that has not been queried for data yet, the app calls the endpoint to download the data for that block. If the user accesses the app offline later, all the cached/ previously viewed data is available. If the user logs out of the app, the cache gets cleared automatically.
- On Web:
There is no background cache that occurs actively.
Screenshots
The following is an overview of the Timetable product integration user interface for a reference when configuring it.
Blended Calendar View
Web Calendar View
Technical Overview
Prerequisites
- CMAuth configured Profile Registration Authentication (App Manager -> App Settings -> Profile Registration Authentication)
- CMAuth configured Authentication Access (App Manager -> App Settings -> Authentication Access)
- Timetable feeds should be provided by one of the following:
- CelCat APIs
- Ellucian Banner APIs
- Ellucian Colleague (custom) APIs
- MyTimetable APIs
- Oracle PeopleSoft APIs
- RESTful API which provides timetable feed in one of the following formats:
- JSON
- XML
- iCal
Required Format
Celcat Vendor
campusM uses the following Celcat APIs:
GET /api/students – The parameters and headers passed into this API are all set within the configuration page.
GET /api/events?studentId={{user_input_identifier}} – This returns the timetable data for the user.
Oracle PeopleSoft Vendor
campusM uses the following API:
GET - https://campus.edu/PSIGW/RESTListeningConnector/ExecuteQuery.v1/PUBLIC/CAMPUSM_TIMETABLE/JSON/NONFILE?isconnectedquery=N&maxrows=0&prompt_uniquepromptname=USERNAME,START,END&prompt_fieldvalue=STUDNT,2020-04-06,2020-04-13&json_resp=true
The parameters and headers passed into this API are all set within the configuration page.
JSON Expected Format:
{
"status": "success",
"data": {
"query": {
"numrows": 2,
"queryname=": "CAMPUSM_TIMETABLE",
"rows": [
{
"attr:rownumber": 1,
"EVENT_REF": "9",
"DESC1": "Multiplatform Content Creation",
"DESC2": "COM",
"DESC3": "COM-200-01",
"START": "2020-04-06T12:00:00-0700",
"END": "2020-04-06T14:50:00-0700",
"TEACHER_NAME": "Dianne Dianne",
"TEACHER_EMAIL": "do_not_reply@campus.edu",
"LOC_CODE": "ANM1-259",
"LOC_ADD1": "259",
"LOC_ADD2": "79 New"
},
{
"attr:rownumber": 2,
"EVENT_REF": "25",
"DESC1": "Multiplatform Content Live",
"DESC2": "COM",
"DESC3": "COM-210-01",
"START": "2020-04-06T15:40:00-0700",
"END": "2020-04-06T18:30:00-0700",
"TEACHER_NAME": "Dianne Dianne ",
"TEACHER_EMAIL": "do_not_reply@campus.edu",
"LOC_CODE": "ANM1-259",
"LOC_ADD1": "259",
"LOC_ADD2": "79 New"
}
]
}
}
}
RESTful API Vendor
- JSON Expected Format
{
"events": [
{
"eventRef": "ref 1",
"desc1": "Quantum mechanics exam 1",
"desc2": "Exam Timetable",
"desc3": "Some other description",
"start": "2020-07-27T07:00:00.000Z",
"end": "2020-07-27T07:00:00.000Z",
"teacherName": "Faculty invigilator",
"teacherEmail": "buckleym@example.ac.uk",
"locCode": null,
"locUrl": null,
"locLat": null,
"locLong": null,
"locAdd1": "Great Hall",
"locAdd2": "Senate building",
"locAdd3": null,
"locAdd4": null,
"locPostCode": null,
"locWorkTel": null,
"attendanceExclude": false,
"campus": "London",
"meeting": true,
"meetingURL": "https://www.google.com/",
"meetingURLDesc": "This is a meeting url description"
} - XML Expected Format
<root>
<events>
<eventRef>ref 1</eventRef>
<desc1>Quantum mechanics exam 1</desc1>
<desc2>Exam Timetable</desc2>
<desc3>Some other description</desc3>
<start>2020-07-27T07:00:00.000Z</start>
<end>2020-07-27T07:00:00.000Z</end>
<teacherName>Faculty invigilator</teacherName>
<teacherEmail>buckleym@example.ac.uk</teacherEmail>
<locCode/>
<locUrl/>
<locLat/>
<locLong/>
<locAdd1>Great Hall</locAdd1>
<locAdd2>Senate building</locAdd2>
<locAdd3/>
<locAdd4/>
<locPostCode/>
<locWorkTel/>
<attendanceExclude>false</attendanceExclude>
<campus>London</campus>
<meeting>true</meeting>
<meetingURL>https://www.google.com/</meetingURL>
<meetingURLDesc>This is a meeting url description</meetingURLDesc>
</events>
</root> - Attributes Mapping for JSON/XML Fields
Attributes Mapping External Field Name Internal CampusM Field Name Description Mandatory Yes/No Data Type Default Example Event Reference eventRef A unique ID for the event yes String max 100 chars - "EVENT12345" eventRef should include only alphanumeric chars and '.', '-', ':'
Primary Description desc1 The primary description of the Event/Course/Exam yes String - "Quantum mechanics exam 1" Secondary Description desc2 The secondary description of the Event/Course/Exam no String - truncated after 2000 chars - "Exam Timetable" Tertiary Description desc3 Tertiary description - Any additional details of the event type. It is displayed on the detail page of the calendar, below the primary description. no String - truncated after 2000 chars - - Start Date start The start date/time - the format for this is configurable in the configuration area. yes String - "2019-08-13T07:00:00.000Z" End Date end The end date/time. The format for this is configurable in the configuration area. (It does not have to contain the timezone information). yes String - "2019-08-13T07:00:00.000Z" Lecturer Name teacherName The name of the teacher no String - Lecturer Email teacherEmail The email of the teacher - Clicking the email allows the user to send an email no String - "buckleym@example.ac.uk" Location Reference locCode Clicking the location links the user to campus maps. This must be a unique identifier for the location to which you want to link in campus maps. The data type can be any string, and must be set as the location reference for the position in the App Manager. no String - Location Reference locUrl A URL that can be sent in the response. It can be a campusM URL scheme / standard HTTP link (overrides locCode as the location reference link) no String - Location Latitude locLat The latitude for the location coordinates no Decimal - Location Longtitude locLong The longitude for the location coordinates no Decimal - Location Name locAdd1 A description of the location of the event no String - "Great Hall" Additional Location Information locAdd2 An additional description of the location no String - "Senate building" Additional Location Information locAdd3 An additional description of the location no String - Additional Location Information locAdd4 An additional description of the location no String - Location Post Code locPostCode If this field is populated, the location name will be treated as the first line of an address rather than a room name no String - Location Work Telephone Number locWorkTel Contact number of the event location or organizer no String - Attendance Exclude Flag attendanceExclude A flag that defines whether or not to exclude the event from attendance monitoring. If this is not specified, all events have attendance monitoring enabled. Note that this is only relevant when campusM Attendance has been deployed. no Boolean (true/false) false true Campus Name campus If there are multiple campuses, this field can be used to distinguish between different timezones no String - Meeting meeting A flag that indicates if a meeting link will be included no Boolean false Meeting URL meetingURL The URL for the meeting for the event no String - Meeting URL Description meetingURLDesc The description for the meeting URL no String - - iCal Expected Format:
BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20200428T180000
DTEND:20200428T210000
CREATED:20200226T165202Z
UID:8568585558096800-1588107600
SUMMARY:Linear Algebra
DESCRIPTION:This is a math course
URL:https://www.hostName.edu/event/r-a-d-free-9-hour-womens-self-defense/2020-04-28/
LOCATION:Hammond Peregrine Hall 300\, 2330 173rd Street\, Hammond\, IN\, 46323\, United States
GEO:41.5805562;-87.4723704
ORGANIZER;CN=John Smith:MAILTO:jsmith@host1.com
X-MEETING:true
X-MEETING-URL:https://google.com/
X-MEETING-URL-DESC:This is a great description
X-PROPERTY-LOCATION-WORK-PHONE:207-123-4567
END:VEVENT
END:VCALENDAR - Attributes Mapping for iCal Fields
Attributes Mapping External Field Name Internal CampusM Field Name Description Mandatory Yes/No Data Type Default Example SUMMARY Primary Description, Event Reference The primary description of the Event/Course/Exam. In addition, 'Events Reference' will consist of this field (together with few others). yes String SUMMARY Primary Description, Event Reference DESCRIPTION Secondary Description,
Event ReferenceThe secondary description of the Event/Course/Exam. In addition, 'Events Reference' will consist of this field (together with few others). no String - truncated after 2000 chars DESCRIPTION Secondary Description,
Event ReferenceDTSTART Start Date, Event Reference The start date/time - the format for this is configurable in the configuration area. In addition, 'Events Reference' will consist of this field (together with few others). yes String - yyyymmddThhmmssZ DTSTART Start Date, Event Reference DTEND End Date, Event Reference The end date/time. The format for this is configurable in the configuration area. (It does not have to contain the timezone information). In addition, 'Events Reference' will consist of this field (together with few others). yes String - yyyymmddThhmmssZ DTEND End Date, Event Reference ORGANIZER Lecturer Name The name of the teacher no String ORGANIZER Lecturer Name ORGANIZER Lecturer Email The email of the teacher - Clicking the email allows the user to send an email no String ORGANIZER Lecturer Email URL Location Reference A URL that can be sent in the response. It can be a campusM URL scheme / standard HTTP link (overrides locCode as the location reference link) no String URL Location Reference GEO Location Latitude and Location Longtitude The latitude (before ';') and longtitude (after ';'') for the location coordinates no Decimal GEO Location Latitude and Location Longtitude LOCATION Location Name A description of the location of the event no String - "Great Hall" - Error Handling
If there is an error in the response because timetable data does not exist for the user, the response is the following:
HTTP Status Code should be ‘404 Not Found’
The response contains the following text: timetable_not_found
- iCal
iCal is required according to the iCal standard format. Customized event attributes can be added as additional iCal properties in the iCal feed. For the additional properties’ required configuration, see the Configuration section.
Banner Vendor
campusM uses the following Banner APIs:
- https://<hostName>:<portNumber>/StudentApi/api/students/<BANNER_ID>/class-schedules?term=<term>
Banner ID – username or an attribute from the token.
Term – a term code according to the dates range given in the request from the Application.
This API returns a list of courses for the student of the given Banner ID during the given term code.
- https://<hostName>:<portNumber>/StudentApi/api/terms
This API returns a list of all the available terms for all the students with the information of each term.
MyTimetable (Eveoh) Vendor
- startDate
- endDate
- excludeResourceTimetables
- apiToken
- requestedAuth
Ellucian Colleague (Custom) Vendor
{
"studentId": "123456",
"startDate": "08/01/2020",
"endDate": "12/01/2020"
}
- The Ellucian Colleague (custom) vendor configuration is retrieved with the calType in the request coming from the application.
- The body is built with information from the user identifier and from the request (start+end dates).
- The courses information is received.
- Event items are created.
Technical Flow Diagram
- Currently, when using not-blended view, list all calendar feeds is being displayed (with only relevant data in them, according to calendar's response). It is planned to be fixed in Q2 2020.
- Events that occur on vacation days are not removed.
Configuration
To use the Timetable product integration, configure the following components:
- Timetable Product Integration instances - an instance for each feed.
- To be done by Ex Libris: Application Server, Authentication Access, Web Service Endpoints, 'Calendar' Menu Entry.
Configure a Timetable Product Integration Instance
Configuration for Celcat Vendor
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Manage Integration | |||||
Enable Product Integration | Select to enable the product integration | Yes | Checkbox | False | |
Product Integration Description | A description of the product integration for internal use | Yes | String | ||
Vendor | |||||
Vendor Name | Celcat | Yes | Drop-down | ||
Base URL to retrieve the information | This is the base URL for the Celcat API | Yes | String | https://myDomain.com | |
Parameter Input Option | Sets the type of User Input Identifier that is needed | Yes | Drop-down | ||
Token Property Name | This is a type of User Input Identifier that can be used | Yes, if the Parameter Input Option selected was "Token Property" | String | ||
Constant Value | This is a type of User Input Identifier that can be used | Yes, if the Parameter Input Option selected was "Constant" | String | ||
Authentication Type | Sets the API authentication type | No | Drop-down | ||
API Code | This is required to authenticate with Celcat | Yes | String | ||
Username Resource Type | Sets the supported Celcat resource type that matches the campusM username attribute | Yes | Drop-down | ||
Timetable ID | Sets the Celcat ID of the timetable to fetch events from | Yes | Integer | ||
Start of Academic Timetable Year | Sets the first month of the academic year; the feed needs to know this | Yes | Drop-down | ||
Timezone Configuration | |||||
Timezone Configuration Option | Sets how the date should be handled that is returned from the API | Yes | Drop-down | ISO Standards | |
Select Timezone | If you selected "Single Timezone" for the Timezone Configuration Option, then this field will specify which timezone to use | Yes | Drop-down | UTC | |
Field Name | If you selected "Multiple Timezones" for the Timezone Configuration Option, then this field will specify which attribute in the response indicates the location | Yes | String | ||
Field Value | If you selected "Multiple Timezones" for the Timezone Configuration Option, then this field will specify what value should indicate the specific timezone | Yes | String | ||
Timezone | If you selected "Multiple Timezones" for the Timezone Configuration Option, then this field will specify what timezone should be used | Yes | Drop-down | ||
General | |||||
Use Location URL? | If this is checked, the app will use the location URL specified in the PI data feed, over the location reference value (used to deep link to a position within the maps component) | No | Checkbox | False | |
Import/Export Configuration | |||||
Export | Creates a JSON file with the product integration configuration | No | |||
Import | Use this option in order to load configuration information from JSON of an exported product integration | No |
Configuration for RESTful API Vendor
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Enable Product Integration | Select to enable the product integration on the user's campusM app | No | Check box | Yes | Select to enable the product integration on the user's campusM app. |
Product Integration Description | A description of the product integration for internal use | Yes | Description | ||
Vendor Name | Select API | No | |||
Date Format | The date format for the data returned in the feed | No | yyyy-MM-dd HH:mm:ss:SSS | ||
URL to retrieve the information | The URL for the Web service | No | https:// | ||
Response Content Type | The Web service’s response content type | No | JSON | ||
URL Query Parameters | The parameters sent as part of the query | No | For https://someHostName/serviceName?username={user}, the query parameter is username. | ||
URL Path Parameters | The parameters sent as part of the path | No | For https://someHostName/serviceName/username, the path parameter is username. | ||
General Headers | Add (key, value) for additional needed headers | No | |||
Authentication Type | Select one of the following options:
|
No | |||
Time Zone Configuration | Select an option to determine how to take into account the time zone when handling the time returned from the API. The following options are available:
|
No |
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Teacher Email Property Name | The property name for the email of the teacher | No | String | - | X-PROPERTY-TEACHER-EMAIL |
Location Code Property Name |
The property name for the location code (Click on the location will link out the user to campus maps. This must be a unique identifier for the location you want to link to in campus maps. The data type can be any string, and must be set as the location reference for the position in the App Manager) |
No | String | - | X-PROPERTY-LOCATION-CODE |
Location Image Property Name | The property name for the location image | No | String | - | X-PROPERTY-LOCATION-IMAGE |
Location Address No. 2 Property Name | The property name for the location secondary address | No | String | - | X-PROPERTY-LOCATION-ADDRESS-2 |
Location Work Phone Number Property Name | The property name for the contact number of the event location or organizer | No | String | - | X-PROPERTY-LOCATION--WORK-PHONE |
Location Post Code Property Name | The property name for the location post code | No | String | - | X-PROPERTY-LOCATION-POST-CODE |
Location URL Property Name | The property name for the URL that can be sent in the response. can be a campusM URL scheme / standard HTTP link | No | String | - | X-PROPERTY-LOCATION-URL |
Location Latitude Property Name | The property name for the latitude for the location Coordinates | No | String | - | X-PROPERTY-LOCATION-LATITUDE |
Location Longitude Property Name | The property name for the longitude for the location Coordinates | No | String | - | X-PROPERTY-LOCATION-LONGITUDE |
Attendance Exclude Property Name | The property name for the flag that defines whether or not to exclude the event from attendance monitoring. If this is not specified all events will have attendance monitoring enabled. Note that this is only relevant when campusM Attendance has been deployed. | No | String | - | X-PROPERTY-ATTENDANCE-EXCLUDE |
Meeting Property Name | The property name for the meeting indicator | No | String | - | X-MEETING |
Meeting URL Property Name | The property name for the meeting URL | No | String | - | X-MEETING-URL |
Meeting URL Description Property Name | The property name for the meeting URL description | No | String | - | X-MEETING-URL-DESC |
Configuration for Banner API Vendor
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Enable Product Integration | Select to enable the product integration on the user's campusM app | No | Check box | Yes | |
Product Integration Description | A description of the product integration for internal use | Yes | String | ||
Vendor Name | Banner | Yes | Drop-down | ||
Base URL to retrieve the information | URL for the webservice. Should be in the following format: https://<hostName>:<portNumber>/StudentApi/api/students/<BANNER_ID>/class-schedules | Yes | URL | ||
User Input Identifier | Select a parameter input option for Banner ID. Possible values: Username, Token Property, and Constant. | Yes | Drop-down | For https://someHostName/serviceName/username, the path parameter is username | |
Authentication Type |
Authentication type against the web service |
No | Drop-down | No Auth | |
Time Zone Configuration | Select an option to determine how to take into account the time zone when handling the time returned from the API. The following options are available:
|
No | Drop-down | ||
General | |||||
Use Location URL? | If this is checked, the app will use the location URL specified in the PI data feed, over the location reference value (used to deep link to a position within the maps component) | No | Checkbox | Unselected | |
Display Location Description | Select to display the location description in the UI | No | Checkbox | Unselected | |
Display Campus Description | Select to display the campus description in the UI | No | Checkbox | Unselected | |
Display Room Description | Select to display the room number in the UI | No | Checkbox | Unselected |
Configuration for MyTimetable (Eveoh) API Vendor
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Enable Product Integration | Select to enable the product integration on the user's campusM app | No | Check box | Yes | |
Product Integration Description | A description of the product integration for internal use | Yes | String | ||
Vendor Name | MyTimetable | Yes | Drop-down | ||
Base URL to retrieve the information | URL for the webservice. | Yes | URL |
https://someHost.com:portNumber https://myColleagueHost:5555 |
|
User Input Identifier | Select the source for your user identifier to send as the requestedAuth header on the MyTimetable API. Possible values: Username, Token Property, and Constant. | Yes | Drop-down | For https://someHostName/serviceName/username, the path parameter is username | |
Authentication Type | Select one of the following options:
|
No | Drop-down | No Auth | |
Time Zone Configuration | Select an option to determine how to take into account the time zone when handling the time returned from the API. The following options are available:
|
No | Drop-down |
Configuration for Ellucian Colleague (Custom) Vendor
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Enable Product Integration | Select to enable the product integration on the user's campusM app | No | Check box | Yes | |
Product Integration Description | A description of the product integration for internal use | Yes | String | ||
Vendor Name | Ellucian Colleague (custom) | Yes | Drop-down | ||
Base URL to retrieve the information | URL for the webservice. | Yes | URL |
https://someHost.com:portNumber https://myColleagueHost:5555 |
|
User Input Identifier | Select a parameter input option for Banner ID. Possible values: Username, Token Property, and Constant. | Yes | Drop-down | For https://someHostName/serviceName/username, the path parameter is username | |
Authentication Type | Authentication type against the web service | No | Drop-down | No Auth | |
Time Zone Configuration | Select an option to determine how to take into account the time zone when handling the time returned from the API. The following options are available:
|
No | Drop-down |
Configuration for Oracle PeopleSoft Vendor
The following table describes the configuration options available for the Oracle PeopleSoft vendor:
Configuration Option | Description | Mandatory | Data Type | Default | Example |
---|---|---|---|---|---|
Enable Product Integration | Select to enable the product integration on the user's campusM app | No | Check box | Yes | |
Product Integration Description | A description of the product integration for internal use | Yes | String | ||
Vendor Name | Oracle PeopleSoft | Yes | Drop-down | ||
URL to retrieve the information | The URL for the Web service | No | https:// | ||
URL Query Parameters | The parameters sent as part of the query. If it is prompt param, select this checkbox. | No | For:
https://host?isconnectedquery=N&maxrows=0&prompt_uniquepromptname=USERNAME,START,END&prompt_fieldvalue=STUDNT,2020-04-06,2020-04-13&json_resp=true
The regular query parameter is maxrows. The prompt param is USERNAME and its value is STUDNT.
|
||
Authentication Type | Select one of the following options:
|
No | Drop-down | No Auth | |
Time Zone Configuration | Select an option to determine how to take into account the time zone when handling the time returned from the API. The following options are available:
|
No | Drop-down |