Rating

Rating is a simple application developed as a way to demonstrate how to build an IMS LTI tool provider. The application allows teachers to create items which can be rated by students. A separate list of items is maintained for each link from which the tool is launched. If the link has the Outcomes service enabled, then the associated gradebook column will be populated with the proportion of the visible items which each student has rated.

Before downloading the application you can try out the PHP version by requesting a free trial consumer key and secret which will be valid for 14 days:

Request free 14-day trial access

An implementation of this application as a Building Block for Learn 9.1 is available. This application is based on an original PHP version.

The Rating application is written in Java and uses the open source Java LTI Tool Provider classes for handling the LTI-related communications. The download file contains code written for use with a MySQL or SQLite database, but it can be used with any database supported by the LTI classes.

The Building Block version of this application is hosted within a Learn 9.1 server and uses the Blackboard database schema.

Java source files

The source Java and JSP files for this application are contained in the src.zip file contained within the download file available from OSCELOT (see link in Licence section below). The download file also includes some brief notes on setting up a project to compile the application. The following dependent library files are required:

• LtiToolProvider
• servlet-api
• commons-httpclient
• commons-logging
• apache-commons-lang
• jdom
• oauth-core.jar
• commons-codec
• gson
• mysql-connector-java

Alternative JDBC database connectors are available; for example for SQLite. The Java classes are also described in the JavaDocs documentation.

Restrict access

The admin directory is used to manage access to the application; on a production server, therefore, steps should be taken to prevent unathorised access to this directory.

Configuration

The following application setting may be specified in the Config class file:

• APP_NAME - the name of the application is used in the HTML page headers

The database connection is configured through the following settings:

• DB_NAME - a JDBC connection string such as 'jdbc:mysql://localhost/MyDb' or 'jdbc:sqlite:php-rating.sqlitedb'
• DB_USERNAME - the database username with SELECT, INSERT, UPDATE and DELETE privileges for the database tables used by the application
• DB_PASSWORD - the password for the database user
• DB_TABLENAME_PREFIX - an optional prefix to insert before each table name

(The DB_USERNAME and DB_PASSWORD settings should be left empty for an SQLite database connection.)

The application uses the following database tables:

• item - a record for each item to be rated
• rating - a record for each rating made by a student

The table names may also have a prefix (see DB_TABLENAME_PREFIX setting above).

CREATE TABLE item (
  item_id int(11) NOT NULL AUTO_INCREMENT,
  consumer_key varchar(50) NOT NULL,
  resource_id varchar(50) NOT NULL,
  item_title varchar(200) NOT NULL,
  item_text text,
  item_url varchar(200) DEFAULT NULL,
  max_rating int(2) NOT NULL DEFAULT '5',
  step int(1) NOT NULL DEFAULT '1',
  visible tinyint(1) NOT NULL DEFAULT '0',
  sequence int(3) NOT NULL DEFAULT '0',
  created datetime NOT NULL,
  updated datetime NOT NULL,
  PRIMARY KEY (item_id)
)

CREATE TABLE rating (
  item_id int(11) NOT NULL,
  consumer_key varchar(50) NOT NULL,
  user_id varchar(50) NOT NULL,
  rating decimal(10,2) NOT NULL,
  PRIMARY KEY (item_id,consumer_key,user_id)
)

In addition, the tables used by the Java Tool Provider classes are also used. When using a MySQL or SQLite database the required database tables are created automatically when calling the Manage tool consumers page (provided the database user has the CREATE privilege).

Building Block

The Building Block version of this application is installed in the same way as any other building block. The database schema tables will be created automatically as part of the installation process.

Manage tool consumers

Administrators should access the <app_path>/admin/ (where <app_path> is the URL to the application) page to manage the tool consumers which are permitted to use the application. The page displays a list of defined tool consumers in name order.

For a tool consumer to be marked as available it must be both enabled and the current time must fall between any enable from/until dates specified. If a tool consumer is not available, its row in the table will be displayed with a grey background. The version column is completed with data provided by an LTI launch request; the tool consumer GUID is displayed when placing the mouse over the value.

A new tool consumer can be added by entering its details in the form provided at the bottom of the page. An existing tool consumer definition can be edited by clicking on the edit icon in the Options column of the table. This will add its details in the table at the bottom of the page; click on the Update consumer button to save any changes, or click on Cancel to clear the form. Click on the delete icon in the Options column to delete an existing tool consumer definition.

The launch URL (<app_path>/launch, consumer key and secret should be communicated by a secure means to the administrator of the VLE for which they were created so that they can be used to add the Rating application to their system.

Manage rating items

If a teacher launches a link to the Rating application from within their course, a page listing the items to be rated is displayed. The list displayed is specific to the link which was followed.

Alternate rows within the list of items are given a different background colour; hidden items are marked [hidden] and displayed with a grey background. The maximum rating determines the number of stars displayed against the item. The rating value (displayed as red stars) is the average rating awarded by students to the item. Hovering the mouse over a rating will display its numeric value.

A new item can be added by entering its details in the form provided at the bottom of the page. Items can be re-ordered by selecting a new position for an item from the drop-down list provided. An existing item definition can be edited by clicking on the edit icon in the Options column of the table. This will add its details in the table at the bottom of the page; click on the Update item button to save any changes, or click on Cancel to clear the form. Click on the delete icon in the Options column to delete an existing item definition.

Rating items

If a student launches a link to the Rating application from within their course, a page listing the items to be rated is displayed. The list displayed is specific to the link which was followed.

A student may rate an item by clicking on the apppropriate star; it an increment step less than one has been selected for the item then the student should click on the appropriate section of the star. The numeric value of the rating is displayed when the mouse is hovered over the stars. A student is only permitted to rate each item once.

Ratings and outcomes

If a resource link supports the LTI Outcomes service then the associated gradebook column is used to record the proportion of visible items each student has rated. This means that the grades column will be updated when the following events occur:

• a new or existing item is made visible;
• an item's visibility is disabled;
• a user rates an item

If a change leads to no items being visible then any gradebook entries will be deleted; otherwise the value will be zero (if the user has not rated any of the visible items), one (if all of the visible items have been rated by the user), or a value between zero and one when a user has rated some, but not all, of the visible items.

Note, this is just one way in which the application could link a student's activity to an LTI outcome value between 0 and 1 and has been added to illustrate the use of the Outcomes service.

Building Block

The Building Block uses virtually the same code as the standard version. The Manage tool consumers page can be accessed via the Settings option on the Installed tools page of the System Admin tab. The launch URL should be the URL of the Building Block with a path of /launch. For example:
https://www.learn.server/webapps/spv-rating-BBLEARN/launch
(change https://www.learn.server to the URL of the Learn 9.1 server and BBLEARN to the schema name used by the server, if different.

This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The Rating application is available for download from OSCELOT where it is also possible to report bugs.