The Course-Catalog is a web front-end for searching and browsing course information stored in Ellucian Banner.

Overview of operation

1. (Nightly) Data from the Banner Oracle database is copied into tables in a MySQL database (via coursecatalog/bin/update-from-banner.php)
2. (Nightly) Derived tables and views to improve the ease of fetching are built from the data now in MySQL (via coursecatalog/bin/update-from-banner.php)
3. (Nightly) Search indices are built based on the data now in MySQL (via coursecatalog/bin/build_indices.php)
4. The PHP data model based on the OSID Course Catalog API provides an object-oriented API for accessing the course catalog data. This API ensures consistency in data fetching so that different user-interface screens always have the same information available.<
5. The front-end application (using the Zend Framework's MVC system) provides search, browse and display interfaces to access the course information. It also provides XML web services for using the course information in remote systems. Additionally, the front-end application includes a schedule-planning tool to help students plan their semesters. All user-interfaces and web services get their data through the OSID Course Catalog API.

Examples

Examples of the the Course-Catalog in action at Middlebury College:

• Main Search UI (catalog app)
• Section Details Page (catalog app)
• Department "courses" RSS feed (catalog app)
• Departments listing to feed to the Drupal content type form (catalog app)
• Department Course Listing (Drupal "courses" content-type displaying a feed from the catalog app)
• Department Section Listing (Drupal "courses" content-type displaying a feed from the catalog app)
• Faculty Profile (Drupal "profile" content-type displaying a feed from the catalog app)

Schedule Planner - Screen-shots and more information about the schedule-planner.

Installation

These instructions assume that you have a POSIX machine running Apache with PHP 7.0 or later.

1. In a non-web-accessable directory, clone the course-catalog repository: git-clone /~https://github.com/middlebury/coursecatalog.git

2. cd into the new coursecatalog/ directory:

   cd coursecatalog
   

3. Install dependencies with Composer:

   composer install
   

4. Make a symbolic link to the coursecatalog/docroot/ directory in a web-accessible directory or add a virtualhost rooted in the coursecatalog/docroot/ directory.

5. Create a MySQL database for the catalogs data and a cache of Banner data.

6. Make copies of the example config files at configuration.plist, frontend_config.ini, and update_config.ini and edit values to match your environment.

7. Create the database tables defined in application/library/banner/course/sql/table_creation.sql

8. Run the script at bin/update-from-banner.php to dump Banner data into the the MySQL database:

   php bin/update-from-banner.php
   php bin/build_indices.php
   

Development environment setup

Lando

Install Docker and Lando to provide a local containerized environment

In the code directory, start the local containers with lando start

Copying the production database

Dump the production database to a non version-controlled file path like var/catalog_prod.sql.

Strip out any DEFINER statements that will break the import:

sed -i '' 's/DEFINER=[^*]*\*/\*/g' var/catalog_prod.sql

Import the database into the local container:

lando db-import var/catalog_prod.sql

Scheduled jobs and worker processes

Database update jobs

Archive export jobs.

Exports for all active jobs can be enqueued for export by a messenger consumer worker (see below) with:

lando ssh -c "bin/console app:export:enqueue:active"

Similarly, a single export jobs can be triggered with:

lando ssh -c "bin/console app:export:enqueue:single <job-id>"

Alternatively there are two commands that can directly export the print catalogs without relying on the messenger worker process:

lando ssh -c "bin/console app:export:active"

lando ssh -c "bin/console app:export:single <job-id>"

Messenger consumer worker

The Archive exporter uses the Symfony messenger system to let the admin UI queue up builds of the archive exports which are then processed asynchronously by the messenger:consumer worker process. In production a messenger:consumer process should always be kept running either via supervisor, systemd, or via a docker command depending on the deployment environment.

In development, the worker process can be manually started with:

lando ssh -c "bin/console messenger:consume -vv"

Unit Tests

Most of the Course Catalog OSID API is covered by PHPUnit tests. To run these tests:

1. Install PHPUnit if you do not have it available.
2. Create an empty MySQL database for running the tests.
3. Edit application/test/banner/configuration.plist and enter your database configuration parameters.
4. On the command-line, change directory to your course-catalog source directory.
5. Run the command phpunit application/test/TestSuite.php

Configuration

To configure the OSID Course data model, copy configuration.plist-example to configuration.plist and edit the values in that file to point at your application's database server.

To configure the rest of the application, create a .env.local file and copy the sections you need to modify from .env.

.env/.env.local changes

Database

At a minimum, you will likely need to configure the DATABASE_URL to point at your application database.

Saml Authentication

If you choose to use authentication, you will need to update these values to fit your identity provider.

SAML_IDP_ENTITYID="https://idp.example.edu/abc123"
SAML_IDP_SINGLESIGNONSERVICE="https://idp.example.edu/abc123/saml2"
SAML_IDP_SINGLELOGOUTSERVICE="https://idp.example.edu/abc123/saml2"
SAML_IDP_X509CERT="MIIC...."

Course Manager implementation

• banner_course_CourseManager: The default implementation that queries a local copy of a Banner database to fetch data.
• apc_course_CourseManager: An implementation that wraps APCU caching of commonly fetched results around the underlying implemenation. By default the apc_course_CourseManager uses the banner_course_CourseManager as its underlying implementation, but this can be configured to a custom one in configuration.plist

Implementation Notes

The implementation of this system is layered such that the Web UI code is separated from the data model. The data model is an implementation of the Open Knowledge Initiative (O.K.I.) Open Service Interface Definition (OSID) for Course information, the Course OSID (detailed doc). Because of this structure, it is possible for other institutions to modify the data model (the OSID implementation) so as to use the same UI code against different data sources, be they different Banner implementations or alternative systems. See also OSID Usage.