Database Changes

Owned by Jen Bourey
Last updated: Aug 02, 2018 by Jim HelwigVersion comment

Database Schema Changes

Historically, performing a major- or minor-version migration in uPortal required a complete database re-initialization.  In other words, the only supported way to have a portal database for your chosen minor release (e.g. 3.1, 3.2, or 4.0) was to run $ant initportal or $ant initdb with the correct/same version of the source code.  The current intent within the uPortal developer community is for uPortal 4.1 to be the last minor release for which that is the case.  (Major releases will still require database re-initialization.)

Migrating from uPortal 3.x to uPortal 4.1 certainly requires database re-initialization.  Migrating from uPortal 4.0 to uPortal 4.1 officially requires it, but you may succeed in running uPortal 4.1 against a database that was functioning properly with a late uPortal 4.0.x release (e.g. 4.0.12).  

Even if you could run uPortal 4.1 against your existing portal database, it may be a good idea to perform a full migration anyway.  Each new major- and minor-version of uPortal brigs exciting new features.  More often than not, these features are implemented with data.  In addition to the data changes driven by new features you want, there are often data changes driven by old data that you don't need any longer.  When you're making a substantial portal update, it's often very pragmatic to choose a fresh start with portal data.  uPortal 4.1, moreover, contains some pretty significant updates, including Respondr and Regions for portlets.

Use $ant data-export to get data from your existing portal, then selectively include elements of that data in the new, 4.1 portal.

uPortal 4.1 introduced an optional feature Entity-based PAGS which has new database tables.  The default in uPortal 4.1 is XML-based PAGS.  Multi-tenancy requires Entity-based PAGS.  Refer to the Entity PAGS section below and the Person Attribute Group Store (PAGS) Overview documentation for more information.

uPortal 4.2-specific

Migrating from 3.x or 4.0.x to uPortal 4.2 generally requires an initdb as uPortal 4.2 does not support the universality theme anymore in favor of Respondr.  Though you could retain most data and make layout adjustments to get your portal to look reasonable in Respondr without wiping out other data, switching the theme to Respondr is generally sufficient reason to take the opportunity to reboot your portal look and discard old data.

There are no additional tables between 4.1 and 4.2.  

Topics for uPortal 4.1 Migration

Below are some data migration notes of particular relevance to uPortal 4.1.

Channels

As of uPortal 4.0, IChannel content is no longer supported.  If you're migrating from uPortal 3.x – particularly if you've had a uPortal implementation for a long time – some of your content may be in the form of channels.  Although there is no automated path for updating channel-based content to portlet-based content, the community-provided IChannel software can quickly be replaced with their Portlet equivalents (e.g. Webproxy, RSS/News Reader, Announcements, etc.).

Entity PAGS

Starting with uPortal 4.1, Person Attributes Group Store (PAGS) comes in 2 flavors:  original (configured in PAGSGroupStoreConfig.xml) and Entity (JPA-managed database entities).  Both approaches are functional and behave similarly.  Consider switching to Entity PAGS now;  in the future, Entity PAGS will allow uPortal to support management of PAGS groups through an administrative UI, without a re-build, re-deploy, and re-start of Tomcat.

Topics for uPortal 4.2 Migration

Below are some data migration notes of particular relevance to uPortal 4.2.  If upgrading from a version earlier than 4.1, also see Topics for uPortal 4.1 Migration above.

Entity PAGS

Entity-based PAGS becomes the default configuration in uPortal 4.2.0.  There is a new groovy-based script that can also be invoked from ant that converts an existing XML PAGS file to entity files and creates a SQL updae script that can be executed to upgrade a uPortal 4.1 database from XML PAGS to Entity PAGS.  See  UP-4436 - Getting issue details... STATUS  for more information.

# dir specifies the target directory to write out entity PAGS files to. Typically your institution-modified copy of quickstart_entities
ant -Dmaven.test.skip=true -Ddir=uportal-war/src/main/data/myInstitution_entities/pags-group pagsXmlToEntity
 
# As detailed in script output:
# - There are a few redundant entity PAGS files you can delete since they duplicate information in required_entities.
# - Also to upgrade an existing 4.1 database, you will need to import the entities, insure compositeGroupService.xml is configured to use Entity PAGS (default in 4.2.0) and run a generated SQL script against your existing 4.1 database.