2.2.3 Release Notes


1. Overview

Security Update: 2.2.3 adds a critical security fix to the 2.2.2 maintenance release and should therefore be taken to simply supersede 2.2.2 and all 2.2.x releases which came before it. Anyone running unpatched versions of earlier 2.2 releases should upgrade to 2.2.3 immediately. Unpatched systems could allow a user to view all attachments on the system through the browser ( SAK-7288) as well as alter or delete them through a WebDAV client (SAK-7672).

The Sakai 2.2 series as a whole marks the culmination of a significant effort to restructure the framework into more logical functional/architectural units, paving the way for multiple focused teams to work in parallel on moving the framework and legacy code forward. This release also incorporates the Open Source Portfolio suite of tools, available in this first merged effort as provisional tools. Additional functional improvements include group awareness for each of the Resources, Assignments, and Schedule tools, the inclusion of French and Catalan translations, updated help content, and the addition of four innovative provisional tools.

2. Migrating from 2.2.0

Since all 2.2 minor releases involve no API changes, a migration from 2.2.0 is very simple and straightforward: skins, providers, and other code written for the 2.2 codebase should be fine.

Some of the 2.2.1 fixes, however, were applied to the DB schema, and so a DB conversion script is still necessary for that upgrade, although neither 2.2.2 nor 2.2.3 introduced any schema changes. The conversion scripts to be applied - in distinct versions for MySQL and Oracle, respectively - are found in the reference/docs/conversion folder of the release or on subversion:

That's it for a migration from 2.2.0. You can freely skip past most of the rest of this page, though you'll probably want to jump down and skim the fixed issues and open issues sections.

3. Migrating from 2.1.x

If you're moving to 2.2.3 from a 2.1 version (or earlier), the changes are more significant, and since the 2.2 code is still fairly recent, it's worth spending a little more time here to describe what you can look forward to.

3.1. What's New

3.1.1. Enhancements

3.1.1.1. Framework Refactoring

The 2.2 codebase marks the culmination of a significant effort to restructure the framework into more logical functional/architectural units, paving the way for multiple, focused teams to work in parallel on moving the framework and legacy code forward.

These changes in themselves do not have a direct functional impact, but they are echoed by a change in the organization of Sakai's subversion repository, and many services and packages have different names from those in 2.1. To see more discussion of migration issues that may result, see below.

3.1.1.2. Group Awareness

Group awareness has been extended to three additional tools: Resources, Assignments, and Schedule. That is to say, the contents of each of those tools can have their access restricted to specific groups, as they are defined by site maintainers in the Site Info tool.

3.1.1.3. EID/UID Separation

For the last few releases we've been working to introduce the concept of "internal" and "external" identifiers in Sakai in the user records. We started with a single identifier that had to play both of these roles, and have been tweaking the code to separate these out. This separation was completed with 2.2.0. It is now possible for an institution to, for example, alter the enterprise IDs of their users without losing access to their sites and materials in Sakai. For a thorough discussion of these changes, see the doc reference/docs/architecture/sakai_id_eid.doc (or in subversion at: https://source.sakaiproject.org/svn/reference/tags/sakai_2-2-3/docs/architecture/sakai_id_eid.doc)

3.1.1.4. FCKeditor

The FCKeditor WYSIWYG editor was available in 2.1, but not the default. In 2.2 it has become the default editor. HTMLArea is still included, however, and the default editor may be overridden in sakai.properties by altering the following setting:

# specify the wysiwyg editor
wysiwyg.editor=FCKeditor
3.1.1.5. Included Skins

The three highest-scoring skins from the recent skins contest have been included in the distribution. You can make any of these your default skin by using the following property in sakai.properties (other possible values are commented out in the example below):

# The default skin for sites without a skin setting
# skin.default=gen-u
# skin.default=examp-u
# skin.default=some-u
skin.default=default
3.1.1.6. Updated Help Content

Help content in 2.1 was out of date, reflecting only version 2.0 of the software. The help content has been updated for 2.2, along with some style improvements. To see the ongoing work of the Help project, visit their space in Confluence:

http://bugs.sakaiproject.org/confluence/display/HELP/Home

3.1.1.7. New translations

New interface translations for French and Catalan, as well as updated Japanese translations, are available in this release. See reference/docs/readme_i18n.txt for more information.

3.1.2. New Tools

3.1.2.1. Open Source Portfolio

2.2 involves closer integration with the Open Source Portfolio, an existing suite of tools supporting portfolio activities, and which are available in this release as provisional tools. Using OSP, individuals can collect items, reflect, design portfolios, and publish them to designated audiences. Instructors and program administrators are able to provide structure and guidance to an individual's work that include step-by-step (sequential) wizards, matrices of goals/standards, and hierarchies to organize related work.

3.1.2.2. Provisional Tools

Sakai 2.2 has added four new provisional tools

  • Message Center: a tool combining a discussion forum with private messaging.

  • Search: a tool providing a Google-like search of all site content.

  • Summary Calendar: a synoptic calendar view that may be used in either the My Workspace or the Home page of course/project sites, including an event summary from either all the sites to which a user is a member (if in My Workspace) or the events of a particular site (if in that site).

  • Post 'Em: an automated reporting system that enables faculty to post grades and comments without compromising student privacy. Post ‘Em accepts CSV files, empowering faculty to track student grades in a spreadsheet application of their choice.

You can find more details about these and all other provisional tools on the provisional tools page.

3.2. Migration Issues

3.2.1. Database Conversion

A database conversion is required for a migration from 2.2.0 to 2.2.1, but not for a migration from 2.2.1 to 2.2.3. Since DB conversions require the successive application of all intermediate scripts, a migration from a 2.1.x or earlier version will require at least two conversions (e.g. one from 2.1.2 to 2.2.0, and then one from 2.2.0 to 2.2.1). The conversion scripts to be applied - in distinct versions for MySQL and Oracle, respectively - are found in the reference/docs/conversion folder of the release or on subversion:

https://source.sakaiproject.org/svn/reference/tags/sakai_2-2-3/docs/conversion

Examine before using

As a general rule, be sure to read through these conversion scripts before applying them. They do not take into account any special customizations you may have made - such as new roles, or the deployment of additional tools - and they may complicate your migration with unintended consequences if you execute the script blindly.

The Message Center tool offers one such particular example for 2.2. A number of schools deployed Message Center in 2.1.x production, before it was yet a provisional tool. Now that it is a provisional tool, the conversion scripts were written to introduce its tables, and thus assume that Message Center is a new tool for your deployment. If it isn't, you'll want to comment out the portions of the 2.1.2 - 2.2.0 conversion script that treat it, and instead perform the following conversions:

MySQL:
ALTER TABLE MFR_TOPIC_T ADD DEFAULTASSIGNNAME VARCHAR(255);
ALTER TABLE MFR_OPEN_FORUM_T ADD DEFAULTASSIGNNAME VARCHAR(255);
ALTER TABLE MFR_MESSAGE_T ADD GRADEASSIGNMENTNAME VARCHAR(255);
ALTER TABLE MFR_MESSAGE_T ADD GRADECOMMENT VARCHAR(255);
Oracle:
ALTER TABLE MFR_TOPIC_T ADD DEFAULTASSIGNNAME VARCHAR2(255) NULL;
ALTER TABLE MFR_OPEN_FORUM_T ADD DEFAULTASSIGNNAME VARCHAR2(255) NULL;
ALTER TABLE MFR_MESSAGE_T ADD GRADEASSIGNMENTNAME VARCHAR2(255) NULL;
ALTER TABLE MFR_MESSAGE_T ADD GRADECOMMENT VARCHAR2(255) NULL;

3.2.2. Framework Changes

If you're migrating from an earlier version you'll also need to be apprised of the framework changes that the 2.2 codebase involves. The 2.2 refactoring means that many package names have changed from 2.1, and these differences will mainly be encountered in sakai.properties settings with bean references. It's best to not try to use a sakai.properties from a previous release, and instead start with the sample in reference/docs/sakai.properties.

Any custom code, such as providers, may also need revision. See below for more discussion of providers in particular.

3.2.3. Provider Changes

As mentioned above, 2.2 introduces a separation of external user identifiers from Sakai's internal user ids. Any custom UserDirectoryProvider will need some alteration to account for this, along with changes to its import statements and declarations that stem from API changes. Below is a list of changes that a typical provider should require:

  1. Import statements altered to reflect new package names.

  2. A search and replace to turn getters and setters from, e.g., 'getId' to 'getEid'.

  3. Revise the project.xml files in both the provider module and 'component' with the appropriate UDP location.

  4. Change the Spring bean declaration in component.xml.

  5. The UDP class may implement the DisplayAdvisorUDP interface (optional), and the two additional methods this pulls in.

Be sure to review the SampleUserDirectoryProvider, and compare it against the sample for previous releases:

https://source.sakaiproject.org/svn/providers/tags/sakai_2-2-3/sample/src/java/org/sakaiproject/provider/user/SampleUserDirectoryProvider.java

3.2.4. Skin Changes

A number of CSS changes will need to be made to any 2.1 skins in order to adapt them to 2.2 versions. These changes - including conversion steps - are thoroughly documented in the appendices of the skin document available in reference/docs/architecture/sakai_skin.doc, or in subversion at: https://source.sakaiproject.org/svn/reference/tags/sakai_2-2-3/docs/architecture/sakai_skin.doc

4. Maintenance Branch

The code of each release has a corresponding maintenance branch, which is patched with fixes in an ongoing way by a branch manager - effectively until there is no longer sufficient interest in it for a branch manager to volunteer. Maintenance branches therefore represent the latest snapshot of fixes for any given Sakai version.

These maintenance branches may be checked out through subversion; they are labeled with an 'x' replacing their minor version number, e.g. '2-2-x'. You can check out the 2.2 maintenance branch with the following command:

svn export https://source.sakaiproject.org/svn/sakai/branches/sakai_2-2-x/

If you come upon an important fix that you believe should be included in the branch (and perhaps isn't yet), feel free to bring it to the attention of the branch manager, Lance Speelmon (lance@indiana.edu).

5. Fixes Included in this Release

Sakai 2.2.3 fixes the following issue from 2.2.2:

http://source.sakaiproject.org/release/2.2.3/fixed-issues.html

6. Open Issues

The list of known issues with Sakai 2.2.3 is found at:

http://source.sakaiproject.org/release/2.2.3/open-issues.html

See in particular the "Important Issues" noted at the top of the list.