Contents README Changelog FTL Changelog Known Issues pdf

This document describes how to upgrade to the latest versions of Clearspace from previous versions of Clearspace. It also includes information on how to migrate from other Jive Software products, including Knowledge Base, Forums, and Integrated server.

If you're a developer looking for information on upgrading your plugin and customization code, check out Upgrading Extensions to Version 2.

Important Note Make sure to backup your jiveHome directory and backup your database before doing an upgrade. Also, be sure to read the Known Issues section of this guide.

Sections in this Topic

Upgrading from the Standalone Distribution to the Installer Distribution
Upgrading the Standalone Distribution
Upgrading the WAR Installation
Upgrading the Source Build
Migrating from Other Jive Products
Migrating from One DBMS to Another
Back Up Your jiveHome Directory
Back Up Your Database
Clearspace Upgrade Philosophy
Known Issues

Upgrading from the Standalone Distribution to the Installer Distribution

  1. Verify you've backed up your jiveHome directory and database.
  2. Back up your CLEARSPACE_HOME/server/lib directory (or CLEARSPACE_HOME/server/shared/lib on versions prior to version 2). After running the installer, if you're not using the embedded database, you will need to copy the JDBC driver you've been using into the newly installed server/lib directory. In either case the JDBC driver needs to be in this directory before starting the new instance.
  3. Run the installer.
  4. Rename the newly installed jiveHome/ directory to something other than jiveHome; instead, you'll use the jiveHome directory you were using before. At the command line, you can run a command such as mv jiveHome/ jiveHomeUnused/).
  5. Copy your existing, permanent jiveHome into the new Clearspace directory. Or, if you prefer, you can create a symbolic link inside that directory to your permanent jiveHome:
  6. You will need to copy your database JDBC driver back into the server/lib directory before starting the newly installed Clearspace instance.
  7. Start Clearspace using the Start menu command or desktop shortcut you installed.

Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Note: Be sure to see Evaluation Database to Oracle with Active Directory under known limitations below.

Upgrading the Standalone Distribution

  1. Verify you've backed up your jiveHome directory and database.
  2. Backup your CLEARSPACE_HOME/server/lib directory (or CLEARSPACE_HOME/server/shared/lib on versions prior to version 2) or, alternatively, after unzipping your new Clearspace download, you will need to copy the appropriate JDBC driver into the server/lib directory. In either case the JDBC driver needs to be in this directory before restarting the standalone instance.
  3. Unpack the new distribution of Clearspace.
  4. Rename the jiveHome/ directory that comes with this distribution to something other than jiveHome, you won't be using this directory (for example, mv jiveHome/ jiveHomeUnused/).
  5. Create a symbolic link inside the unpacked distribution to your permanent jiveHome:
    • UNIX/Linux: Create a symbolic link to your permanent jiveHome directory in the Clearspace directory called jiveHome (for example, ln -s /opt/jiveHome jiveHome)
    • Windows: You can also create a symbolic link to your jiveHome directory if you have Junction installed (http://www.microsoft.com/technet/sysinternals/utilities/Junction.mspx), or copy your permanent jiveHome into the Clearspace directory.
  6. You will need to copy your database JDBC driver back into the server/lib directory before restarting the standalone Clearspace instance
  7. Issue the command start-clearspace.sh or start-clearspace.bat

Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Note: Be sure to see Evaluation Database to Oracle with Active Directory under known limitations below.

Upgrading the WAR Installation

  1. Verify you've backed up your jiveHome directory and database. (If you're using MySQL, be sure to see the note under known issues.)
  2. Delete or move your previous WAR (and exploded WAR files) from your application server's web application directory (usually webapps/).
  3. Unpack the new distribution of Clearspace.
  4. You will need to point your Clearspace instance at your permanent jiveHome directory (which you have already backed up), this can be done in a few different ways:
    • Option 1: Use the setup tool. Use the Clearspace setup tool to set the value. After you deploy the web application you will have to run through the setup tool again, but you can point Clearspace at your current jiveHome and all your previous settings will be retained. Caution: When resetting the jiveHome location be sure that you click Continue and not Create Directory— you do not want to overwrite your jiveHome.
    • Option 2: Use the EditWAR tool. The EditWAR tool is a small application which will modify the packaged web application (clearspace.war) to point to the jiveHome directory. The clearspace.war file is also in the base directory of this distribution.
      To invoke the EditWAR tool, open a command prompt in the base directory of this distribution and execute this command:
      java -jar EditWAR.jar clearspace.war
      The tool will then lead you through the process of updating the WAR.
    • Option 3: Set a JNDI value (advanced). Set the location of the jiveHome directory via JNDI. In your app server, you can set a JNDI value of java:comp/env/jiveHome with a String value of the path to your jiveHome directory.
    • Option 4: Set with a system property (advanced). Set the location of the jiveHome directory manually by passing in a Java system property to your appserver. Set a property with the name of "jiveHome". Most app servers allow you to pass in an environment variable in the startup script. That might look like this:
      java -DjiveHome=/usr/foo/jiveHome -cp . com.myappserver.Server
  5. Copy the new clearspace.war into application server's web application directory, or redeploy the WAR using your application server's administration console.
  6. Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Upgrading the Source Build

  1. Verify you've backed up your jiveHome directory, database, and Clearspace_HOME/custom directory if you have added any of you own custom source code.
  2. Delete or move your previous WAR (and exploded WAR files) from your application server's web application directory (usually webapps/).
  3. Unpack the new distribution of Clearspace.
  4. Rebuild the Clearspace source as detailed in the Clearspace Source Build.
  5. You will need to point your Clearspace instance at your permanent jiveHome directory (the one you backed up), this can be done in a few different ways:
    • Option 1: Use the setup tool. Use the Clearspace setup tool to set the value. After you deploy the web application you will have to run through the setup tool again, but you can point Clearspace at your current jiveHome and all your previous settings will be retained. Caution: When resetting the jiveHome location be sure that you click Continue and not Create Directory as you do not want to overwrite your jiveHome.
    • Option 2: Use the EditWAR tool. The EditWAR tool is a small application which will modify the packaged web application (clearspace.war) to point to the jiveHome directory. The clearspace.war file is also in the base directory of this distribution.
      To invoke the EditWAR tool, open a command prompt in the base directory of this distribution and execute this command:
      java -jar EditWAR.jar clearspace.war
      The tool will then lead you through the process of updating the WAR.
    • Option 3: Set a JNDI value (advanced). Set the location of the jiveHome directory via JNDI. In your app server, you can set a JNDI value of java:comp/env/jiveHome with a String value of the path to your jiveHome directory.
    • Option 4: Set with a system property (advanced). Set the location of the jiveHome directory manually by passing in a Java system property to your appserver. Set a property with the name of "jiveHome". Most app servers allow you to pass in an environment variable in the startup script. That might look like this:
      java -DjiveHome=/usr/foo/jiveHome -cp . com.myappserver.Server
  6. Redeploy the new clearspace.war into application server's web application directory, or redeploy the WAR using your application server's administration console.
  7. Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Migrating from Other Jive Products

You can use the Clearspace admin console to migrate data from other Jive products to Clearspace. To get your data into Clearspace version 2, you must first migrate your application data to Clearspace version 1.x (preferably the latest version), then upgrade to version 2.

Note: Migrating data from another Jive application directly to Clearspace version 2 is not yet supported.

Before you begin, keep in mind the following notes and best practices:

Importing Data from Another Jive Product

To migrate data from another Jive product to Clearspace version 1.x, you use the admin console. Use the following steps:

  1. Be sure to read the list of common importing limitations. Also, read the limitations specific to each product. These lists are provided below.
  2. Start with a clean database to receive the imported data. In other words, your newly installed Clearspace instance should not include any user, community/space, or content data.
  3. Shut down the system from which you're importing.
  4. Start Clearspace and complete its setup tool if you haven't yet.
  5. Start the admin console, then navigate to Spaces/Communities > Management > Import Content.
  6. Under Import, select the Jive product from which you're importing.
  7. Be sure to read the notes on the import page. Before you import content from a source application into a Clearspace instance, you should:
    • Shut down the source application while the importer is running.
    • Ensure that the source applicaiton database has not been customized so that its schema is different from the default. The importer will not copy custom tables into Clearspace; depending on the modifications, the importer might not work at all. If your customizations have been made by Jive's professional services team please contact your service representative to determine whether the customizations will affect the importer. Otherwise, please contact Jive Support to find out more about potential issues and solutions.
    • Be prepared to copy user and group details from the source application to Clearspace. This importer tries to do that automatically, but in some cases it can't. The importer will test the copy and inform you if it can't copy user and group details. If it can't, you must copy that information before you finish running this importer.
    • Be sure this importer will have access to the source application's jiveHome directory. For example, if this Clearspace instance is not on the same server as the source application, you must either copy the jiveHome directory over to this server or link the jiveHome directory remotely to a drive and path on this server (by using nfs, Windows share, or some such).
    • Note that this import process doesn't support using a shared drive for storing the source application's attachments. Such a mechanism might be used in some clustered installations, where the drive is set through the "attachments.directory" property in the jiveHome/jive_startup.xml file. Instead, source application attachments must be stored in the jiveHome/attachments directory or in the database that will be imported.
    • Be sure that the Clearspace classpath includes the driver library for the database that the source application is using (such as postgresql.jar). For example, if Clearspace and the sourcea pplication are using different databases, you could copy the source application's driver library to the Clearspace WEB-INF/lib directory. This importer will try to connect to the source application's database using the database connection information in the source application's jiveHome/jive_startup.xml file.
  8. Enter the full path to the jiveHome directory for the product you're importing. This must be on the same server as your Clearspace instance.
  9. In the data list, select No for any kind of data you don't want to have imported.
  10. Click Continue to start importing.
    After a few seconds, Clearspace will begin importing your data. Progress will be displayed in both the Clearspace user interface and in the Clearspace log file.
  11. Restart Clearspace after the import is complete.
  12. Rebuild the main and user search indices. In the admin console, click System > Settings > Search, then click the Index Tasks tab. To rebuild the main index, click Rebuild Index; to rebuild the user search index, click Rebuild User Index.
  13. In Clearspace, examine the imported data to ensure that the results are correct.

Limitations Common to Import from Any of the Products

Jive Knowledge Base Import limitations

Jive Forums 5.0.x Import Limitations

Jive Forums 5.5 Import Limitations

Jive Integrated Server Import Limitations

Migrating from One DBMS to Another

You can use the Clearspace admin console to migrate Clearspace data from one database management system to another. Clearspace supports the following DBMSs as either source or destination systems (supported versions are those that are supported for installation; see the Clearspace Installation Guide for more details):

In the admin console, go to System > Import/Export > Database Migration. The database migration tool will migrate your Clearspace instance from one database server to another. Before beginning the migration, you must:

Note: If you begin migration but don't finish, it's possible to put Clearspace into a in-between state. In this state, you'll receive an "in-progress" message even though you're no longer migrating. If this happens, you can fix it in the admin console. In the console, go to System > Management > System Properties, scroll to locate the skin.default.maintenace.enabled property, then click its delete button. After you do this you should be able to refresh your browser to view the Clearspace UI.

Note: Be sure to see Evaluation Database to Oracle with Active Directory under known limitations below.

Back Up Your jiveHome Directory

The jiveHome directory is the place where Clearspace stores a number of things about your environment. The database connection information is stored there as well as logs, cached attachments, your license file, and the evaluation database files (if used).

You should back this up before upgrading and you should get in the practice of backing up this directory on a regular basis. The easiest way to back up the directory is to use a ZIP or TAR application or script to package the directory.

Back Up Your Database

You should back up your database on a regular basis and before upgrades. For now, the best way to manage database backups is to follow the recommendations of your DBA or the recommendations of your database software. There are a number of tools built in to various databases. Here are a few example:

There are many tools for each database; try to pick one that suits your environment.

Clearspace Upgrade Philosophy

Upgrading web applications doesn't have to be hard. We've made every effort for this to be a seamless process. If you have feedback or suggestions for this process, we'd love to hear it.

In general, upgrading between revision releases will be easy (ie, 1.0.0 to 1.0.1, or 1.0.0 to 1.0.5). Upgrades between minor releases (ie, 1.0 to 1.1, or 1.0 to 1.3) might require a bit more work but we have an upgrade wizard in the application to assist.

Known Issues

Evaluation Database to Oracle with Active Directory

If you are currently using the evaluation database and wish to upgrade from version 1.4, 1.5, or 1.6 and switch to running Oracle with Active Directory there is an extra step you must perform in order to work around an issue within Oracle.

  1. The first step is to upgrade Clearspace to 1.7. If you are currently running on the evaluation database and using Active Directory, or if you are currently running Oracle, and want to switch from Default to Active Directory for user authentication, don't change the database or authentication settings during the upgrade process. Keep everything the same and simply run through the upgrade tasks.
  2. Once you have upgraded Clearspace, stop your application server, edit <jiveHome>/jive_startup.xml, and change <setup>true</setup> to <setup>false</false>, and restart the application server.
  3. You will be forced to re-run the setup tool, but this time you can set your new database and user authentication options to use Oracle and Active Directory.

Upgrades Using MySQL Will Convert MyISAM Tables to InnoDB

In order to support transactions in version 2, MyISAM MySQL database tables will be converted to InnoDB during upgrade. The upgrade process will handle this conversion; there is no action required on your part.

Clear the Tomcat work Directory After Upgrading

After you finish the upgrade process, be sure to clear the clearspace subdirectory of Tomcat work directory before starting the application and viewing the admin console. You'll likely find this subdirectory at <tomcat_root>/work/.../clearspace. If you don't clear the directory (which contains cached application components), you might see errors when you try to view application pages.