Sakai Gradebook Modifications Specification

Owned by Jon Gorrono (Unlicensed)
Last updated: Aug 03, 2006Version comment

Sakai Gradebook Modifications

Purpose

The Sakai Gradebook tool currently provides 'Instructors' the ability to download grade information in two different ways.

  • First is the 'Roster View Download' (RVD) which downloads a list of assigmnents and some point grade information. (The Roster View Download feature is currently being enhanced as per SAK-1753 and http://bugs.sakaiproject.org/confluence/display/SG2X/Grade+Import by UC Berkeley)
     
  • The Second download feature is the 'Course Grade Download' (CGD). The CGD is the focus of this specification and the purpose of feature is final grade reporting.
    The motivational factors driving change in CGD has come from both the Sakai Project community and from local exigencies. Locally, the need to provide a mechanism that fits into or replaces the current final grade submission workflow that involves both MyUCDavis and The Final Grading Tool aka the Grade Submission Tool. The current output of the CGD does not provide sufficient infomation (within the data) for the Final Grading Tool to process without brittleness.

While the primary focus of this work is on the CGD, code re-use in the original design results in some of the same methods being used for CGD and RVD. And so, it was not possible to change the first without some effect the second. This also means that final integration testing must include RVD functions.

The Sakai community expresses its preferences using feature requests and periodic requirements gathering an a large scale. The current outstanding requirements include 'make [CGD] more configurable' which primarily means to be able to reorder the columns for the output; and 'enable/disable download buttons' and, 'add section information'.

References

REQ-2, REQ-76, SAK-5444

Status and Results

Requirement: Disable/enable Download buttons - using configuration files

Status

complete

Configuration

By 'properties' file

property key: course_grade_export_enabled - default value: true
property key: roster_export_enabled - default value: true
compile-time path: tool/src/bundle/org/sakaiproject/tool/gradebook/bundle/Messages.properties
run-time path: WEB-INF/classes/org/sakaiproject/tool/gradebook/bundle/Messages.properties

By JSF configuration file

Bean id: exportBean
property: courseGradeDownloadEnabled - default value: true
property: rosterDownloadEnabled - default value: true
compile-time path: tool/src/webapp/common/WEB-INF/faces-beans.xml
run-time path: WEB-INF/faces-beans.xml

Requirement: 'Make download more configurable' - using configuration files

Status

complete

Configuration

By 'properties' file

compile-time path: tool/src/bundle/org/sakaiproject/tool/gradebook/bundle/Messages.properties
run-time path: WEB-INF/classes/org/sakaiproject/tool/gradebook/bundle/Messages.properties

A new property can be specified in the 'Messages' bundle: export_course_grade_column_order_keys
This property can be defined with a comma-separated (configurable) list of keys used to defind column titles in the same 'Messages' bundle properties file. These keys are used to define the order and consituency of the columns as they are downloaded as well.

Propery key

key value

download data

export_course_grade_gradebookid_column_name

column name, eg "Site ID"

Gradebook Id = Site Id

export_course_grade_siteprovider_column_name

column name, eg "Provider ID"

Site Provider Id

export_course_grade_sitetitle_column_name

column name, eg "Site Title"

Site Title

export_student_name

column name, eg "Student Name"

user displayName

export_student_id

column name, eg "Student Id"

user Eid

roster_course_grade_column_name

column name, eg "Cumulative"

see 'course_or_roster'

course_grade_details_course_grade_column_name

column name, eg "Course Grade"

see 'course_or_roster'

course_or_roster

none: placeholder *

'cumulative roster view grade' or the 'course grade'

assignments

none: placeholder *

All the assignment columns sorted in 'natural' order (sort specified in GUI)

* The special placeholder pseudo-keys, assignments and course_or_roster are not treated as keys with property values like the others.

The GradebookCourseGradeFeedService defines the above property (and placeholder psuedo-) keys as well as:

  • the name of the sort order key: export_course_grade_column_order_keys
  • the delimiter string for the key list: , (comma)

Warning

Two things worth noting

  1. The properties file overrides defaults.
    • If any of the keys are specified in the export_course_grade_column_order_keys property, the all the defaults are overridden.
  2. The 'Roster View Download' and 'Course Grade Download' ulitmately share the same methods.

 
An example that touches on both: if the placeholder assignments is left out of the list, roster columns will not be printed.

 Screen-shot of Course Grade Download buttons

Changes to Online Grade Submission, the existing UC Davis Final Grading Tool (Coldfusion application)

Status

  • Work Begun: 06/19/2006
  • Percent Complete: 85%

Requirements

  1. The Course Management Final Grading system must accept .csv files exported from Sakai with the following columns:
    1. Site Title: Unparsed label field.
    2. Site ID: Parsed unique course identifier of the form (term_yearterm_idcrn).
    3. Provider ID: Parsed unique course identifier of the form (term_yearterm_idcrn) or (term_yearterm_idcrn).
    4. Student Name: Unparsed label field.
    5. Student ID: Parsed unique student identifier (kerberos_name).
    6. Course Grade: Parsed two-letter grading code (valid Banner gradecode).
  2. Accepted files must be parsed to resolve valid grading tuples (Course,Student,Grade) according to systemic grading rules.
  3. Grading tuples passing validation must be saved to the internal database.
  4. Instructors must be notified of invalid grading tuples and the cause.
  5. An interface to allow direct upload of a grading sheet via url parameters must be developed
  6. An interface to provide direct retrieval and parsing of gradesheets saved to common AFS space must be developed

File Format

The transitional .csv file will be required to have the following columns, in order:

Name

Data Type

Data Element

Processing

Site Title

char(19-21)

Title of Course Site

N/A

Course Site ID

char(99)

Sakai Site ID

[term year][term_id][crn]

Course Provider ID

char(14)

Unique Course ID

[term year][term_id][crn] OR [term year][term_id][crn]

Student Name

char(???)

Student Name

N/A

StudentID

char(32)

Kerberos Name

[kerberos_name]

Grade

char(2)

Grade Code

[grade_code]

Gradesheet Retrieval Interface

A new requirement is to provide a new page that will retrieve and parse a sakai-format gradesheet saved to an AFS space common to the Sakai and Course Management servers.

All pages of the final grading tool are designed to read a specific cookie when resolving course and instructor information. Therefore, the retrieval page will be responsible for correctly setting the cookie in addition to parsing the saved gradesheet.

The format of the required cookie is as follows:-
CM_CURRENTCOURSE: 200605-53443-613536 (TERM_CODE-CRN-INSTRUCTOR_PIDM)

In order to set up the cookie correctly, Sakai will need to forward some information along the url passed to the final grading tool. Specifically, Sakai will need to indicate the course that will be used. The page itself should be able to resolve the correct instructor information from the content of the auth_user cookie.

The passed in url parameters will include both site id and provider id. The page will then inspect the url parameters in an attempt to resolve a usable course identifier. Once found, it will be used to create the necessary currentcourse cookie.

Once the necessary cookie is set up, the page will need to find the saved sakai gradesheet and forward its contents to the sakai-format parser. The path to the gradesheet file will be assembled as follows:

/afs/sakai/gradefiles/course_grade-<site_id>-<provider_id>.csv

The site_id and provider_id values will be read from the url parameters of the page request. Once read, they will be assembled into a path with the default values. The service will then attempt to read the file at the indicated location. If the file does not exist, a document refresh will be initiated. The document will refresh until the file is read successfully. On a successful read, the page will invoke the gradesheet parsing routines as normal.

Interface Mockups

There are two ways we can approach the Final Grading interface for SmartSite Course Grading sheet uploads. We can either integrate the interface with the existing interface for download and upload of excel files, or we can build a separate interface. Providing one interface, while perhaps allowing some confusion, should present the most powerful set of features.

Gradesheet Download / Upload

Import Summary

Code Changes

The following pages will be changed:

  • fgs_gradsheet_parse.cfm : Implement detection of Sakai format file and invocation of appropriate tag. Also implementing new initialization mode for retrieval of sakai gradesheet.
  • tag_fgs_gradesheet_parse_sakai.cfm : New implementation of csv parsing for Sakai file format.

The following pages will be created:

  • fgs_direct_upload.cfm : Page to allow direct upload of a SmartSite format file to a course.
  • fgs_sakai_retrieve.cfm : Page to retrieve SmartSite format file from AFS space and parse.