Note This application was retired on 10/05/2023.
This repo contains configuration for the University of York's Course Search powered by Funnelback. This configures a collection of course information within Funnelback, which can be queried as an API returning JSON.
- Course Search - the user-facing Course Search application on the University of York website.
- Courses API - the API that provides Course Search functionality and in turn calls the Funnelback Courses API.
The Funnelback Courses API is available at https://york.funnelback.co.uk/search?collection=courses&profile=_default&form=course-search&smeta_contentType=course&query=History (update the query parameter with your search term).
Currently this defaults to bringing back 10 results.
- To retrieve 25 entries in the results array, add
&num_ranks=25to the URL. - To retrieve from entry 11, add
&start_rank=11to the URL.
The latest version of the API specification is published and kept up-to-date automatically. It is defined using the OpenAPI specification and is served as a static site using a distribution of Swagger-UI.
A Funnelback collection is a set of data that can be searched. It is possible for collections to contain other collections, as the york-uni-campusmap collection contains others.
There are three collections for courses.
york-uni-coursesis powered by a web crawler that indexes all York courses.external-coursesis a custom collection that contains details on HYMS courses published by the CMS.coursesis a meta collection that combines both of the other collections.
The course collection we use for the courses API is courses.
Search templates are *.ftl files that determine the format of results from Funnelback.
The course-search template outputs just the course fields the Courses API requires as a Funnelback response in JSON format, with callback if 'callback' parameter is included in query string.
In the version of Funnelback currently in use (15.24), it requires the following line in the collections.cfg file so it will return the results with a content type of application/json:
ui.modern.form.course-search.content_type=application/json
See UI Modern Form Content Type (collection.cfg)
Useful resources:
You will need a Funnelback (v15.10+) account with the necessary permissions to maintain collections.
Funnelback collections have two profiles, for 'Live' and 'Preview'. The preview profile can be used for testing purposes. For details on how to deploy files to the preview profile, see 'Deployment'.
Deployment of configuration files to Funnelback cannot be done programmatically, and must be done using the web interface.
While logged in to the Funnelback admin console, find the collection you wish to make a change to and select 'Browse Collection Configuration Files'. From here you will see a list of configuration files for each profile. In order to publish a configuration file to Live, it must first be pushed to 'Preview'.
The simplest method of uploading/updating a file is to use the file picker at the bottom of the section. There is also a drop-down menu that allows for the creation of new files that indicates the possible filenames that will be recognised by Funnelback.
When uploading a new version of an existing file, the old one will be archived with a date-time stamp within Funnelback. This allows for a change to be quickly reverted by using the 'Restore' option on an archived version.
Funnelback also provides a visual interface for viewing/editing existing files. Click on the name of the file you want to edit in the preview section to open the editor. You will need to copy the code from the matching file in Source Control to overwrite the file, and then click Save.
Test that the file is working by running an example search, then when you are satisfied return to the config list and click Publish to publish that file to Live.
Due to Funnelback updates it is no longer possible to upload collection.cfg in this way. Because it must now be edited in the UI
it is recommended that changes are made in the UI first, and then copied into this repo. To do this select
'Edit Collection Configuration' under the 'Administer' tab. From there you can select 'Edit raw text' (pictured below) to
get the file contents.
The customised Swagger-UI has been set up by following these instructions. For development documentation and ADR history, there is more information available at the Course Search wiki.
MIT