TABLE OF CONTENTS

1. Overview
2. Migration
   2.1. Database Conversion
   2.2. Skin Update
   2.3. Significant code changes
   2.4. Configuration changes
3. What's New
   3.1. Tool Promotions
   3.2. Tool Enhancements
   3.3. General Enhancements
4. Fixes Included in this Release
5. Open Issues
6. Maintenance Branch
7. Post-2.4 Assignments Tool
   7.1. Upgrade Recommendations
   7.2. New Features
   7.3. Migration Information

1. Overview

The Sakai 2.4 series as a whole incorporates a large number of refinements and refactoring touches at the tool layer, with relatively few changes at the framework level. Four new provisional tools have been added, while three very successful provisional tools have been promoted to the enterprise bundle. See below for more details.

Documentation on this release - ranging from installation to use and configuration of the software - is maintained here in the Confluence wiki. You're encouraged to create an account and give us your comments and questions!

2. Migration

2.1 Database conversion

A DB conversion script is required for a database migration from 2.3.1 to 2.4.1. One is provided with the release, but, as always, this script should be reviewed before application as it is designed for a "vanilla" sakai instance and may well require adaptation for any customizations (e.g. new roles, additional tools) you may have made to earlier releases.

Conversions and versions

DB conversions require the successive application of all intermediate scripts. Note that there were no schema changes introduced in 2.2.2 and 2.2.3, so these should also use the 2.2.1 to 2.3.1 script. The 2.3.0 release was superseded for security issues, and is no longer even a waystation in the database conversion process. Likewise, 2.4.1 introduces no schema changes from 2.4.0.

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-4-1/docs/conversion

2.2 Skin update

A few tweaks were made to Sakai skinning in 2.4, but their impact is confined to the tool layer. That is to say, portal.css was not changed at all, while there were a number of small changes to tool_base.css. A Sakai 2.3 skin could therefore be moved directly onto Sakai 2.4 and look identical at the institutional brand layer, while some tool presentation would not. For full details, see Appendix J of the skin .doc at:

https://source.sakaiproject.org/svn/reference/tags/sakai_2-4-1/docs/architecture/sakai_skin.doc

2.3 Significant code changes

The code changes that implementing institutions will want to pay particular heed to, either because the changes are fairly deep and new, or because of how they may affect local custom work, are highlighted below.

2.3.1 Java 1.4 compatibility pack

Previous Sakai releases required the use of a Tomcat compatibility pack for code compiled for Java 1.4. This is no longer the case, and in fact the compatibility pack will now break Sakai (i.e. it will fail to start up). The good news is that the core distribution of Tomcat 5.5 is all that's needed, and installation is that much simpler.

2.3.2 CM changes

'CM' has become a rather broad identifier indicating a wide variety of changes to how Sakai handles its course management, section and group services. To offer some examples of specific changes in 2.4: the BasicCourseManagementService no longer exists, the Term class has been retired in favor of AcademicSession, CourseSectionImpl has changed quite a bit, class names have changed for section classes, SiteAction has changed significantly, etc. Institutions moving to 2.4 will want to take a close look at the Course Management space here on Confluence, and have their developers post questions on sakai-dev@collab.sakaiproject.org (where the reigning expert to appeal to is Josh Holtzman of UC Berkeley).

Sakai 2.4 deploys with a CM-based group provider out-of-the-box, and can now build with a sample set of course data. To enable the CM OOTB data, you need to start tomcat with -Dsakai.demo=true in JAVA_OPTS. This will activate the sample UDP and load the sample CM data, including the academic terms.

The CM API is significantly richer than the legacy service it replaces, but it is fairly new and the relative number of implementations is small. For institutions that require Sakai to model complex group hierarchies, memberships and their associated data, the CM API should ease the burden of integration. However, institutions which have already implemented successful course management integrations will need to take into account a large number of changes, and a mature set of documentation on this migration has not yet been developed.

2.3.3 Chat

The chat tool was essentially rewritten from the ground up for 2.4 (and dubbed "chat2"). Although it represents significant fixes for performance and stability, and although it went through QA successfully, it is nevertheless new and relatively untested. Institutions who may wish to remain with the legacy chat tool are therefore still able to find it in contrib:

https://source.sakaiproject.org/contrib/deprecated/chat/

In addition to running the conversion script, institutions wishing to migrate data from chat1 to chat2 need to set migration properties. If you wish to run the migration, set the following in sakai.properties:

# to perform the data migration from chat1 to chat2
performChatMigration@org.sakaiproject.chat2.model.impl.ChatDataMigration=true

#To run the migration scripts during startup
chatMigrationExecuteImmediate@org.sakaiproject.chat2.model.impl.ChatDataMigration=true

A value of "false" in that latter setting will only write the sql out to a file in Tomcat's Sakai directory, so that you can then run it by hand. Special characters are escaped in this file, but in order for that to work in some tools you will have to set and enable the escape character ('\'). This added complication means that it's recommended you simply set the 'ExecuteImmediate' value above to true.

2.3.4 Splitting Message Center

Message Center has been divided into two tools for the release - Messages and Forums - although if you keep the same tool id as in previous releases you can still use them as a unified tool. An institution should consider whether to run them as a single or split tool (not both), as this affects import, namely that Messages & Forums can only import to Messages & Forums and Forums can only import to Forums. Further, the Help tool content is set for the split tool arrangement.

If you would like to continue running Message Center as a single tool, you will need to make the following changes to the registration files found in the msgcntr module: remove the <category> tags from sakai.forums.xml and sakai.messages.xml, then add the <category> tags to sakai.messagecenter.xml. See:

https://source.sakaiproject.org/svn/msgcntr/tags/sakai_2-4-1/messageforums-app/src/webapp/tools/

The single and split tools share not only the same tables, but the same code base. Whether the user sees a single or split tool is decided entirely by the tool registration files. This means that any changes or bug fixes will apply to both the single and split tools.

If you later decide to move from the single tool to the split tool setup, there is a utility available to aid this:

https://source.sakaiproject.org/contrib/tool-placement-migration

2.3.5 Roster

The group awareness introduced for the Roster tool in 2.4 brought in significant performance problems for sites with large numbers of groups (see SAK-8434). If your institution's usage profile involves large sites with a large number of groups (e.g. 1000 users and 25 groups), its performance will be extremely poor. A new roster tool based on the IU tool has however been developed by UC Berkeley, and it does not share the same performance issues. That said, it has not yet seen much production experience, but your institution may wish to evaluate it and perhaps find it a better calculated risk:

https://source.sakaiproject.org/svn/roster/branches/ucb/

2.3.6 Gradebook configuration

Between the 2.3 and 2.4 release of Gradebook a bean name referenced in the Grade configuration xml file was changed from org.sakaiproject.api.section.SectionAwareness to org.sakaiproject.section.api.SectionAwareness. Institutions with custom grade configuration will need to be aware of this. The change was made in gradebook/service/sakai-pack/src/webapp/WEB-INF/components.xml:

https://source.sakaiproject.org/svn/gradebook/tags/sakai_2-4-1/service/sakai-pack/src/webapp/WEB-INF/components.xml

2.4 Configuration changes

The Tomcat compatibility patch for Java 1.4 is no longer required (nor should it be used) (SAK-7408)
The search.experimental setting in sakai.properties from past releases has been superseded by search.enable in 2.4, i.e.

# Enables the search indexer, false by default
#search.enable=false

The following configuration options are new, and have corresponding settings in sakai.properties.

2.4.1 Disable "unjoinable" by site type

# specify site types from which the user can't unjoin
#wsetup.disable.unjoin.count=1
#wsetup.disable.unjoin.1=course

2.4.2 Calendar Summary Settings

# Calendar view (week or month)
# Default: month
#calendarSummary.viewMode = month

# Calendar day background color (as hexadecimal value).
# Default: background-color in tool CSS (.calDayWithActivity) for all priorities
calendarSummary.highPriorityColor = #FF0000
calendarSummary.mediumPriorityColor = #00FF00
#calendarSummary.lowPriorityColor = #0000FF

# Define priorities for calendar events
# Default: all events as low priority
# Note: no need to specify all events, neither all priorities (high, medium, low)
calendarSummary.highPriorityEvents.count=2
calendarSummary.highPriorityEvents.1 = Deadline
calendarSummary.highPriorityEvents.2 = Exam
calendarSummary.mediumPriorityEvents.count=1
calendarSummary.mediumPriorityEvents.1 = Web Assignment
# All calendar events not specified in high and medium priority lists
# are treated as low priority. So, there is no need to specify low
# priority events
#calendarSummary.lowPriorityEvents.count=1
#calendarSummary.lowPriorityEvents.1 = Activity

2.4.3 Mailtool Settings

# Maximum number of allowed attachments per message.
# If below setting is not set, the default is 10000.
# If set to zero, attachment capability will be disabled.
#mailtool.max.num.attachment=10000

# Temp directory for handling attachment files.
# Default is /tmp
mailtool.upload.directory=/tmp/

# Reveal additional config options on "Options" screen for renaming roles.
# Default is false.
# mailtool.show.renaming.role=false

# Roles which should be group-aware in the interface, comma-separated.
mailtool.group.aware.role=Student,access

2.4.4 Tests & Quizzes Settings

# The e-mail settings are for Samigo only. They are used because Sakai
# doesn't support real attachments. Samigo looks to these settings
# instead of the regular Sakai e-mail settings. Also, these settings
# do not override the usual Sakai settings.
#
# outgoing SMTP server (required)
samigo.smtp.server=smtp.somewhere.edu
#
# Bypass SMTP AUTH for outgoing mail (default: false)
# if false, specify username/password
samigo.email.bypassAuth=false
samigo.email.username=SMTP_AUTH_USER
samigo.email.password=SMTP_AUTH_PASSWORD
#
# Temp directory for handling attachment files.
samigo.email.prefixedPath=/tmp/ 

# to allow testing of the Word-2-QTI convertor, the "easy" text editing of question and answer text
# samigo.samliteEnabled=true 

# outgoing SMTP port (default: 25)
samigo.smtp.port=25

2.4.5 Content Review Settings

# Whether or not to add assignment submissions to a queue that will be processed by a content review service.
# assignment.useContentReview=false

2.4.6 Help Content Re-Direct

# An external location for help information.
# If this is set to "sakai" (the default), help information will be displayed as usual.  
# If not, help requests will be redirected to the specified URL.
#help.redirect.external.webapp=

2.4.7 OSP Settings

# The types of reports to generate from the OSP data warehouse.
# Accepts a value of 0,1,2 or 3.  Set to 0 to disable reports, 1 to generate warehouse reports, 
# 2 to generate live reports, and 3 for both warehouse and live reports.  The default value is 1.
#osp.datawarehouse.useWarehouse=1

2.4.8 Search

# Enables the search indexer
#search.enable=false

# Whether or not to build indexes for the search tool.
# Can be set to true or false.
#search.indexbuild=true

2.4.9 FLUID Settings

# Whether or not to attempt to generate a custom stylesheet based on the user preferences.
# Can be set to true or false.
#portal.styleable=false

# Whether or not to attempt to generate javascript to support a custom stylesheet based on 
# the user preferences. Can be set to true or false.
#portal.styleable.contentSummary=false

2.4.10 XML parser

# The classname of the SAX parser to use.
#sakai.xml.sax.parser=

3. What's New

3.1 Tool Promotions

Tools Promoted to "Core":

Messages (Formerly part of Message Center)
Forums (Formerly part of Message Center)
Post'Em

Tools Promoted to Provisional:

See the Tool List for more details.

3.2 Tool Enhancements

Announcements:

Scheduled release (i.e. a future posting date) and retract dates for announcements (SAK-8777)
Added support for show/hide similar to Resources tool; expands on and replaces previous draft functionality. (SAK-8637)

Assignments:

Assignments coming soon

Assignments work done in preparation for 2.4 offered a significant set of feature enhancements, but gradebook integration testing surfaced a tangle of problems during QA, and it was decided that these could not be corrected in time for release. Assignments functionality was therefore rolled back to the 2.3 base, while the enhancements were postponed for a post-release branch of the 2.4 Assignments tool. The feature list below represents a preview.

Allow instructors to enter a grade for students who haven't posted a submission (SAK-6614)
Provide an additional assignment type which doesn't require an electronic submission (SAK-8285)
Send an email to the student to confirm their submission (SAK-271)
Add the ability to upload a zip file containing submissions (SAK-8589)
Due date can be set in 5 minute increments (SAK-7406)
Added an event for viewing assignments

Calendar Summary:

Add week/month view option (SAK-8399)
Use color-coding for event types (SAK-5073) (requires sakai.properties settings)
Small I18N issue (SAK-8541)
Show more event info (attachments, link to schedule event)
Quartz job to add the Calendar Summary to existing sites.

Chat Room:

Chat Overhauled

As noted above, the chat tool was essentially rewritten from the ground up for 2.4, although from the user's perspective very little has changed. While it was vetted in QA and represents significant improvements for performance and stability, it must be admitted that it is still new. Institutions which may prefer to stick with the previous Chat tool can find it in contrib.

https://source.sakaiproject.org/contrib/deprecated/chat/

refactoring which fixed significant stability and performance problems.
Support multiple concurrent chat rooms.
Normalize chat's schema into relational tables (conversion from XML storage). (SAK-8508)
Rewrite UI in JSF. (SAK-8508)
Refactor manager class for easier plug in of other messaging platforms like XMPP.
Now will import any rooms created as well as the synoptic view options. (SAK-5917)

Gradebook:

A per-installation configurable spreadsheet download (SAK-7713)
Section/Group specific spreadsheet downloads based on the user's filter options
Support for course grades indepedent of grade calculation scheme
Simplification/clean up of student view (SAK-7036)
Participation in Sakai migration/archiving service (SAK-7583)
Participation in Sakai Event tracking (SAK-6207)
Allow comments for each assigned grade (SAK-7031)
Expanded services for client tool integration
Fix to critical grade data contention issue (SAK-7407)

Gradebook's "extra" 2.4 release

The gradebook project has never been more active. The project team, led by development work from Indiana University, will be implementing an additional set of feature enhancements (beyond what's listed above) in a post-2.4 release of the tool, some time in June. To see some of the features under discussion for this later release and 2.5 visit the 2.5 Release page in the Gradebook Confluence space.

Help:

Update help content for new functionality in 2.4.
Additional help content for newer tools.
Ability to redirect to an external help webapp (SAK-7619).

Messages/Forums (formerly Message Center):

Split former "Message Center" into two tools, namely Messages and Forums.
Addition of Message Notification synoptic view
Support for importing Forums & topics from other sites added
Group awareness added
Enforce enhanced privacy management settings.
"Quote" feature (Insert original text in forum messages)
Display statistics for user's postings and read messages in Discussion Forums
Ability to expand all discussion forum posts to include body text, not just subject heads
Revamped UI of Forums
Ability to moderate topics

News:

News feed settings will now import. (SAK-5920)
News events (read, update feed) will be logged. (SAK-6212)

Page Order Helper:

Allow Page Order Helper to override toolOrder.xml rather than conflicting with it. (SAK-7341)

Resources:

Content Handlers to mount external resources in CHS and navigate into packaged resources (SAK-4602)
Fix to issue where uploading files take up their entire size in system memory. Now streamed.
Resource "Type" registry for identifying new content types
Move implementation of "Form Items" out of "content" project and use type registry to maintain their presence in Resources tool
Add support for Citations and/or Citation Lists in Resources tool (as a new type registered in the registry)
UI changes to action links in Resources listing
Allow a new root level folder in ContentHosting for private application collections (SAK-7700)

Roster:

Add group/section support to tool. (SAK-6231)
Add new print friendly view. (SAK-7340)
Enforce enhanced privacy management settings.

Search:

The ability to set a single app server for search indexing, while other nodes connect to it via webservices. For performance concerns in larger installations. See sakai.properties settings above. (SAK-7494)
Multi-site search. (SAK-8717)

Section Info:

The automatic creation and representation of SIS-provisioned course structures, metadata and memberships (aka Sections).
Support for multiple meeting places and times per Section.
UI refinements for filtering view.
Configurability to ensure that the application functionality and UI match local institutional needs and SIS data.

Syllabus:

Print-friendly view. (SAK-8548)

Tests & Quizzes:

Added email functionality to allow instructors to email invididual sudents from 'Scores' screens, (SAK-7094)
Allow instructors to give individual students permission to re-take the assessment. (SAK-7093)
A disable/enable toggle of all FCK Editors in Authoring screen. (SAK-5904)
Random questions and multiple attempts: added flavor of randomization selection for random parts. (SAK-7696)
Allow Samigo contents to be imported from other Sakai Sites using the Site Info tool's 'Import From Site' link. (SAK-7378)
Allow instructors to change feedback settings for after assessments are published. (SAK-3943)
Change the 'copy' function in question pool to be a deep copy, rather than a link. (SAK-3526)
Implemented IMS content packaging to allow import/export of assessments with attachments (SAK-5419)
Allow importing of Samigo assessments to Question Pool. (SAK-6993)
Importing simple text formatted assessments to Samigo using Word-2-QTI converter. (SAK-8642)
i18n Internationalization/localization support implemented. (SAK-8643)

Also see the Tests & Quizzes Release Notes.

Web Content:

Now imports with title and URL intact. (SAK-5919)

Wiki:

auto-save feature
includes now supported
various UI improvements (SAK-4679)

Worksite Setup/Site Info:

Updated course creation process.
Integration with new CourseManagementService.
Ability to search for a course.

3.3 General Enhancements

Default Skin (CSS):

Eliminate default margin-bottom and padding-bottom on h3, h4, h5 tags in tool.css
Show column borders on sortable lists in tool.css
Add underlines to default links in tool.css
Replace black-and-white folder icons with manilla-colored ones

Portal:

Pluto 1.1.1 integration.
Support for JSR-168 portlets using Pluto 1.1

JSF:

Classes added to support generic spreadsheet formatting. (Mostly not JSF-specific.)
The Pager can be fully internationalized.
The Pager and other JSF components can now follow standard Sakai locale support.
Toolbar separators can now be customized.

WYSIWYG Editor:

Upgraded to FCK Editor 2.4.1 to address a variety of issues, such as IE7 compatibility.

Internationalization:

Complete localization of all core tools
Updates to existing translations (Catalan, French, Japanese, Spanish, Swedish)
Additional translation in Arabic (requires RTL skin)
Internationalized date/time input widgets available to tools
Internationalized Tool Titles & Descriptions

Component:

Full spring lifecycle support
Demo optional components

Content Review:

Adding a generic content-review service API which can be used by any tool (in trunk).
Adding support for the content-review service in the Assignments tool (in trunk).
Adding an implementation of content-review for the TurnItIn service (in contrib).

Course Management API:

The default group provider in 2.4 is backed by the CM service.
Performance improvements.

Database:

Better transaction support
Enhanced cross-vendor feature support (SAK-6039)

Authz:

Some ease-of-use enhancements for developers (e.g. SAK-8557)
New ability for enterprise-defined roles which cannot be overridden in Site Info - the enterprise provider alone has this authority
Improved transaction handling

4. Fixes included in this release

Sakai 2.4.0 fixes the following issues:

Fixes (2.4)

5. Open Issues

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

Open Issues (2.4)

6. 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.

Complete information on the fixes included in the 2.4 maintenance branch, as well as db schema changes and conversion script details, may be found at: Sakai 2.4.x Maintenance Branch.

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

svn co https://source.sakaiproject.org/svn/sakai/branches/sakai_2-4-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, 2.4.x Branch Manager.

7. Post-2.4 Assignments Tool

The Assignments tool had some difficulties hitting its target for the Sakai 2.4 release, and several anticipated pieces of functionality were not working correctly and had to be removed prior to the release. This left the Assignments tool with the same functionality it had in the Sakai 2.3 release, but included a number of bug fixes that had accumulated since that release. The version of Assignments in the 2.4.x maintenance branch, however, was not properly reverted and ended up in a corrupt state. Unfortunately this error wasn't caught in time and application of subsequent bug fixes to Assignments in 2.4.x has not been possible. So while the 2.4.x maintenance branch is definitely the reliable place to go for bug fixes to all other components of Sakai, you should not be using the 2.4.x version of Assignments.

7.1 Upgrade Recommendations

At this time the Assignment Project Team is recommending that anyone running Sakai 2.4 should consider migrating to the post-2.4 Assignment tool. The migration process requires patches to the code, a database conversion, and post-2.4 Assignments does include new functionality. Further details are provided below. The version of Assignments being recommended as the starting point is post-2.4-c, which was tagged from the post-2.4 branch at revision 40127.

If you are running Assignments 2.4.0 or 2.4.1, you do not have to upgrade to post-2.4, but it is recommended. If those versions are working for you now, then you can keep running them. Post-2.4 Assignments, however, does include over 100 bug fixes for known issues with Assignments in 2.4.0/2.4.1, including significant performance improvements. (As noted above you cannot rely on the 2.4.x maintenance branch for fixes to Assignments, though it is still the right place to go for bug fixes for all other parts of Sakai.)

If you are running Assignments 2.4.x, then you should migrate to post-2.4. You are likely to have serious issues running the 2.4.x version of Assignments due the corrupt state of the branch, particularly
around Assignments-Gradebook integration. You will also not be able to rely on the 2.4.x branch as a continuing source of bug fixes for Assignments. There was only a limited number of bug fixes that were
merged into 2.4.x before problems were encountered, and no additional bug fixes are being merged there due to the corrupt nature of the branch. (Assignments 2.4.x will likely be removed in the near future from the 2.4.x maintenance branch to help alleviate the potential for confusion and problems with that version.)

In any case, bug fixes are only being merged into the post-2.4 Assignments branch at this point. So, if you need a 2.4-compatible branch as a source of bug fixes – rather than trying to merge them yourself from trunk – you need to migrate to using the Assignments post-2.4 branch. The Assignments Project Team plans to continue supporting and providing bug fixes to the post-2.4 branch through at least mid-2008.

The University of Michigan and others are already running the post-2.4-c tag or a more recent revision of the post-2.4 branch in production. A number of schools have also already successfully tested the db conversion script that is required for the migration to post-2.4 Assignments.

7.2 New Features

Assignments post-2.4 is a Feature Branch, so while it is compatible with a Sakai 2.4 deployment, it also brings with it new functionality. The new functionality means you may need to update your local documentation and training materials as part of a switch to post-2.4 Assignments. The new functionality includes:

Grade Non-Submitted – Allow instructors to enter a grade for students who haven't posted a submission.

Non-Electronic Submissions – Provide an additional assignment type which doesn't require an electronic submission.

Submission Confirmation – Send an email to the student to confirm their submission.

Upload All – Add the ability to upload a zip file containing all submissions.

7.3 Migration Information

Detailed instructions and technical information for migrating to Assignments post-2.4-c are available in the post-2.4 branch. Please see the following file:

https://source.sakaiproject.org/svn/assignment/branches/post-2-4/runconversion_readme.txt

Here is a brief summary of the information in the file:

A dependency exists on the util module, so you will also need to upgrade to r38224 or later of util from the 2.4.x maintenance branch.

A dependency exists on OSP/Data Warehouse, so you will also need to apply the patch attached to SAK-12348. (This patch is only appropriate for post-2.4 Assignments users, and it will not be merged in 2.4.x, as it would break OSP for those still running Assignments 2.4.0/2.4.1/2.4.x).

A database conversion is required when upgrading from Assignments 2.4.0/2.4.1/2.4.x to Assignments post-2.4-c. (As post-2.4 and 2.5 Assignments share the same database schema, there should be no additional conversion required, if and when you upgrade to Sakai 2.5.)