ETL Migration Using Jetspeed 2.1.3/2.1.4+, 2.2.1+ and 2.3.+ Installers

To facilitate ETL based migration or data manipulation strategies, the Jetspeed installer includes the ability to export, initialize, and import a Jetspeed database. In addition to basic portal data, these operations also will include database PSML and user preferences stored in the Jetspeed database. The installer does not require a Jetspeed portal build or runtime environment to execute these operations.

The binary installer can be obtained from the download page, (Download), both the minimal and demo installers include the neccessary data operations. In addition to the installer, the appropriate JDBC driver for the installation and access to the database will be required.

Exporting a Jetspeed database

The first step in migrating a database is to export its contents into a file based representation. It is best to perform this step on quiescent or shutdown portal instance. Once the binary installer for the existing Jetspeed release and JDBC drivers have been gathered, invoke the installer using the following shell command:

        java -jar <Jetspeed installer JAR file>
      

To run the installer in the console without a GUI, append the text argument to the shell command:

        java -jar <Jetspeed installer JAR file> text
      

After starting the installer and advancing through the splash and license pages, select the Export Jetspeed Portal Database installer operation and continue. The installer will then prompt for the following information:

Installer Prompt Description
Export data files location Select a new directory where the export is to write the database XML files. Existing files and directories in the selected directory will be removed when the export operation is complete.
Temporary installation location If the default temporary location is not vaild, select a new temporary directory where the installer Jetspeed instance can be unpacked, (it is removed after the installation is complete).
JVM memory size Export operations can consume a large chunk of memory as the database is traversed. Enter a larger JVM maximum memory size in megabytes as necessary for the installer Jetspeed instance invocation.
Database selection Select the current portal database type. DB2, MSSQL, MySql, PostgreSQL, Oracle, and SapDB are supported. Note that Derby is not currently supported.
Database connection parameters Enter or validate the current portal database user, password, connection string, driver class, and driver JAR archive file.

After configuring the export operation, the installer will test the database connection before proceeding to the confirmation page. Continue the installation process as instructed. When it has finished, be sure to review the Show Details tab to ensure the export has completed as expected. The following files should appear in the export data files location specified during the installation:

  • j2-data.xml file
  • j2-prefs-data.xml file, (2.1.X installers only)
  • pages directory, (if database Page Manager enabled)
If the installation fails or errors occur in the detail output, the export has probably failed.

Editing the Jetspeed database Exported XML Files

Exported Jetspeed database XML files can be edited, provided the original format and all dependencies are maintained. The formats and files that make up a release do change between releases, so care must be taken to keep the syntax and files consistent with the export release version. No editing should be required to migrate between dataabase vendors.

Multiple imports can be performed in an additive fashion to merge slices of data cut from individual exports. However, individual objects in the data model are replaced with new versions loaded during the latest import; merging does not take place at the object level. Bulk edits may also be performed to modify data during migration to complement the portal upgrades if desired.

Initializing a Jetspeed database

Full exports are designed to be imported into an empty Jetspeed database. Creating databases is left to the datbase administrator, but the loading of the Jetspeed database schema can also be accompished using the Jetspeed installer. Databases that contain instances of older Jetspeed portal schemas should be cleaned by dropping all Jetspeed tables prior to reinitialization by the installer. All information within the database will be removed when the Jetspeed database is initialized.

To initialize a new database, the installer should be obtained and started for the target Jetspeed release version as documented above for the export operation, except the Initialize Jetspeed Portal Database operation must be selected. The installer will then prompt for the following information:

Installer Prompt Description
Temporary installation location If the default temporary location is not vaild, select a new temporary directory where the installer Jetspeed instance can be unpacked, (it is removed after the installation is complete).
Database selection Select the current portal database type. DB2, MSSQL, MySql, PostgreSQL, Oracle, and SapDB are supported. Note that Derby is not currently supported.
Database connection parameters Enter or validate the current portal database user, password, connection string, driver class, and driver JAR archive file.

After configuring the initialization operation, the installer will test the database connection before proceeding to the confirmation page. Continue the installation process as instructed to load or reload the Jetspeed database schema. When it has finished, be review the Show Details tab to ensure the export has completed as expected. If the installation fails or errors occur in the detail output, the initialization has probably failed. This normally indicates that the database was not clean before the initialization was attempted or sufficient permissions were not granted to the specified database user.

Importing a Jetspeed database

Previously exported Jetspeed database XML files can be reloaded using the installer import operation. Full exports are normally loaded into empty databases, but multiple imports can be used to load partial export data slices as necessary. Data in these slices can only be dependent on information contained within the export or the export files themselves. Individual objects in the XML data files are fully replaced upon load; object instance merging is not supported by import. All data objects imported to the database will replace any existing objects in the Jetspeed database on import.

The installer will expect the following files to appear in the import data files location directory specified during the installation:

  • j2-data.xml file
  • j2-prefs-data.xml file, (2.1.X exports only)
  • pages directory, (assumes Page Manager to be enabled)
All other files in the import data files location directory will be ignored.

Jetspeed database import operations should only be attempted on a shutdown portal instance; imports on a running portal may lead to unexpected results and is not supported. If the import is to merge with data already loaded in the database, performing a full backup before the import is highly recommended.

To import an existing database export file set, the installer should be obtained and started for the target Jetspeed release version as documented above. The Import Jetspeed Portal Database operation must be selected. The installer will then prompt for the following information:

Installer Prompt Description
Import data files location Select an existing directory that contains the exported Jetspeed database XML files.
Temporary installation location If the default temporary location is not vaild, select a new temporary directory where the installer Jetspeed instance can be unpacked, (it is removed after the installation is complete).
JVM memory size Import operations can consume a large chunk of memory as the database is loaded. Enter a larger JVM maximum memory size in megabytes as necessary for the installer Jetspeed instance invocation.
Database selection Select the target portal database type. DB2, MSSQL, MySql, PostgreSQL, Oracle, and SapDB are supported. Note that Derby is not currently supported.
Database connection parameters Enter or validate the target portal database user, password, connection string, driver class, and driver JAR archive file.

After configuring the import operation, the installer will test the database connection before proceeding to the confirmation page. Continue the installation process as instructed. When it has finished, review the Show Details tab to ensure the export has completed as expected. If the installation fails or errors appear in the detail output, the import has probably failed and the database has been corrupted. The import operation(s) will have to be attempted again from a clean or known database backup state. Problems are normally caused by data incompatabilities/overlap between multiple import data slices or insufficient database permissions granted to the specified database user.