Home › Support › Knowledge Base ›

Academus migration to open source Toro Portal

Knowledge Base: Academus, Academus 2.0, Academus 2.1, Upgrade
Updated: August 8, 2008
How can I migrate from Academus 2.x to uPortal 2.6.1-GA and the open source Toro components?
Note that this tool is still going through the QA process and only the Windows platform has been verified with release candidate 6.


Note also that this tool will only migrate ONE ldap configuration with respect to the general LDAP, Person Directory and Authentication Services (ldap.xml, personDirectory.xml and security.properties configuration files).


This only migrates sphinx48 and toro13 installations. Earlier versions will require upgrading prior to running the migration.


We have created a migration tool that will aid in migrating from Academus to uPortal 2.6.1-GA. The goal of this tool is to:

* Install Tomcat 5.5.26
* Install uPortal 2.6.1
* Install All "Toro Portal" components (http://www.unicon.net/opensource/toro)
* Migrate the existing Academus database
* Configure uPortal to use DLM as the layout manager and provide four default layout owners/fragments:
  default-lo, admin-lo, content-lo and groupware-lo

This tool will NOT do the following:

* Install or migrate the Academus Forums or Group Chat channels
* Migrate ANY user layouts
* Install any new DLM themes or skins
* Install the required JDK 1.5

Throughout, this article refers to an environment variable named INSTALLDIR. This refers to the directory into which the Academus product was installed. It will have the directory path unicon/Academus directly beneath it.

Preparations

There are a few things that need to be done to ensure a successful migration. This article describes these necessary steps.

Migration Tool

This tool will handle most of the migration duties automatically. But it does depend on the installation not having much custom add-ons. It can only handle what it knows about. Anything (custom servlets, etc.) that doesn't get migrated automatically will need to be manually migrated. Also, if for any reason, the migration tool encounters something unexpected (files moved, renamed, etc.) it will abort. If this happens, the end of this article describes everything the tool does. You would need to view the migrator.log and see where it left off and continue by hand.

When installing the new bundled Tomcat, it will backup the old Tomcat installation and call it portal-tomcat-a.old. Be sure this directory doesn't already exist.

Be sure to Back up your database. This tool will make changes to the database and in the event it fails in the middle of migrating the database, it will only be able to re-migrate the database from a Academus 2.x version.

Windows users will need to shutdown both Tomcat and IIS to perform the migration.

1) Download the migration tool Migrator. (Note the tool is a large file ~166MB)

2) Set JAVA_HOME environment variable to INSTALLDIR/unicon/tools/j2sdk.  It must at this location.

3) Unix users will need to setup a workspace outside of /tmp. Create a directory at 
INSTALLDIR/work or anywhere you like outside of /tmp.

4) As root, start the migration tool by executing
JAVA_HOME/bin/java -Djava.io.tmpdir=INSTALLDIR/work -jar toro-migrator-1.0.0-rc-6.jar INSTALLDIR

Re-trying a migration

1) Make sure INSTALLDIR/unicon/Academus/portal-tomcat-a.old exists then
delete INSTALLDIR/unicon/Academus/portal-tomcat-a.

2) Rename INSTALLDIR/unicon/Academus/portal-tomcat-a.old
to INSTALLDIR/unicon/Academus/portal-tomcat-a

3) Restore the database to the state prior to invoking the migration tool.

4) Start the migration tool again with
JAVA_HOME/bin/java -Djava.io.tmpdir=INSTALLDIR/work -jar toro-migrator-1.0.0-rc-6.jar INSTALLDIR

Custom Theme Modifications

When developing custom themes, there needs to be some modifications so that the Toro channels and portlets will render and function propertly. See this KBA for the details.

Manual Migration Procedure

If for any reason the migration tool fails, this article describes the steps the tool performs to execute the migration.

Known Issues

SendMercuryMessage servlet does not get migrated properly

In $TOMCAT_HOME/webapps/portal/WEB-INF/classes/properties/academus-portal.properties, the property net.unicon.portal.common.service.notification.NotificationServiceMercuryImpl.service_location needs to be updated so channels can send notifications. Changing 'AcademusApps' to 'toro-portlets-common' should be sufficient to resolve this.

Windows - portal-tomcat-a directory is in use

This problem arises if any other processes are accessing this directory. To resolve this, quit any program that may access it (e.g. Tomcat, IIS)

Channels in the default layout are failing to render

This is most likely to not cleaning up the channel publications as outlined in the Preparations section. The workaround is simply to delete the affected channels from the layout and re-subscribe them.

'Username' cannot be null

If a channel fails to render and produces this error message, it is most commonly caused by an incorrect person directory attribute mapping for username. Replace any mapping in personDirectory.xml to 'username', user.login.id, password with:

<entry key="USER_ID_ATTRIBUTE">
    <set>
        <value>username</value>
        <value>password</value>
        <value>user.login.id</value>
    </set>
</entry>

Where USER_ID_ATTRIBUTE is the ldap attribute for unique user identifier (i.e. sAMAccountName, uid, etc.).