Forums Importer

Version 3
    Powered by Jive Software

    Importing Data from Another Jive Product

    Version 2.5.2

    This plugin makes it possible for you to migrate data from another Jive product to Clearspace. The plugin adds the migration feature, including admin console user interface you can use to begin the migration.

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

    • Only the following Jive product versions are supported:                          
      • Source: Forums 5.5.16 or later.

        Import is currently only supported from product instances using MySQL 5.x (or later) or PostgreSQL 8.x or later. (Note that while the importer has been tested on PostgreSQL 8.3, earlier versions for the source database will probably work fine. Keep in mind that, as noted below, the Clearspace classpath must have both source and destination driver libraries on its classpath in order for the import to run.)
      • Destination: Clearspace 2.5.2 or later.

        Import is currently only supported on a supported Postgres database. For the latest information on platform components supported for Clearspace, see the Clearspace Installation Guide.
    • Back up your existing Jive product data before migrating it to Clearspace.
    • The Clearspace instance that is your migration destination must be a fresh, empty instance.
    • Note the other import limitations listed below.
    • Import to a Clearspace test instance and ensure that the results are as you want before moving the instance to production.
    • Be sure to read the Known Issues section.

    Note: You'll find Clearspace documentation at the Jive web site.

    Limitations Common to Import

    • Importers require a clean database to import into.
    • The importer must be able to directly connect via JDBC to the database of the system being imported from.
    • If your existing instance uses a custom user/group manager, you'll need to migrate that code so that it works with Clearspace. The import tool will import user data, including entries for each user, but work done by your custom manager must be migrated separately.
    • Statistical information is not copied into Clearspace. This includes logged search queries and read statistics.
    • Report data is not migrated.
    • Watch email templates are not migrated. The Clearspace System Administrators' Guide describes how to manage email templates.
    • Custom database tables/columns are not migrated.
    • The system being imported from should be shut down while the importer is active.
    • The import process copies data from one database to another and as such can take a fair amount of time. For large databases, it can take several hours.
    • Only a few Jive properties are migrated, such as email server information. Other properties such as cron tasks, event listeners, and so on will most certainly have to be rewritten to take into account the fact that Clearspace's API is quite different from the other products'.

    Jive Forums Import Limitations

    • Themes are not migrated. See the Clearspace documentation for information on how to create themes.
    • Community everywhere data is not migrated.
    • Localized properties are not migrated.
    • Rating and reward data is not migrated.
    • User status points for each user are imported; status level ranges (and their names and symbols) are not imported. Ranges will follow Clearspace defaults until you change them.
    • Permissions aren't migrated. After importing, you'll need to use the Clearspace admin console to set up permissions for your users.
    • Moderation state is not imported. After import, Clearspace moderation queues won't include items awaiting moderation in Forums. Be sure to resolve your Forums moderation requests before importing Forums data. For more on moderation in Clearspace, see Moderating Content in the latest Clearspace documentation.
    • Communities created from categories and forums do not, by default, have community blogs enabled. If you want blogs in those communities, use the Clearspace admin console to create them. In the console, for each sub-community for which you want a community blog, go Communities > Settings > Community Settings. At the bottom of that page, next to Allowed Content Types, select Blog Posts, then click Save Changes. Next, go to the Community Permissions page, select the Create Blog Post permission to grant it, then click Save Changes.

    Things to Do After Importing

    • Migrate your themes. Theming is different on Clearspace than it is on the instance you imported. If you want to achieve the same look and feel on Clearspace, you'll want to create a Clearspace theme that corresponds to the one you've been using.
    • Create blogs where needed. If you want to take advantage of the Clearspace blog feature, you might want to consider enabling blogs, such as in some of your sub-communities.
    • Configure permissions. You'll need to configure Clearspace permissions. Generally, you'll want to set them up so they correspond to those you had on the instance whose data you imported.
    • Configure community everywhere if you were using it previously.
    • Configure Clearspace status level ranges.
    • Confirm that watch email templates will work for your Clearspace users.
    • Configure moderation. If you were using moderation in the instance you imported, or if you want to ensure that content is moderated before it's published for all to see, be sure to set up moderation in Clearspace. For more about moderation, see Moderating Content in the latest Clearspace documentation.

    Importing Data from Another Jive Product

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

    1. Be sure to read the list of common importing limitations. They 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, 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. Shut down Clearspace, rather than restarting it.
    6. See the Database Preparation steps to take before importing.
    7. Start the admin console.
    8. In the console, go to System > Plugins > Add Plugin. Click Browse to locate the import plugin JAR file you downloaded.

      For the latest documentation on managing plugins, see the Clearspace System Administrator's Guide.
    9. Click Upload.
    10. Restart Clearspace.
    11. In the console, go to System > Data Importer.
    12. Under Import, select the Jive product from which you're importing, then click Configure.
    13. 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 application 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 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 source application 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.
    14. Enter the full path to the jiveHome directory for the product whose data you're importing. This must be on the same server as your Clearspace instance, or must be addressable by the file system.
    15. Click Start Import.
    16. After import has finished, you might want to review the import_verification.log file (in the Clearspace jiveHome/logs directory).

      For example, look for the word "FALSE" to identify problems during the import. Problems could include dropped database connections, name collisions where duplicate data existed from the imported instance. Depending on the error, running the import again could resolve it. (Keep in mind you'll need to start again with a clean database.) It's more likely, though, that you'll find a limited set of warnings that you can handle manually.
    17. Shut down Clearspace after the import is complete.
    18. See the Database Preparation steps to take after importing.
    19. Start Clearspace.
    20. In Clearspace, examine the imported data to ensure that the results are correct.
    21. Read Things to Do After Importing!

    Database Preparation

    You'll need to run scripts to prepare the database that Clearspace will use after you've imported data. There are two scripts — one to run before you import and one to run afterward — and it is very important that you run both.

    You'll find the scripts you need in the database directory of the importer's JAR file.

    PostgreSQL

    Before importing — after you install Clearspace and set it up with its setup tool:

    1. Stop the application server.
    2. Run the before_postgres.sql script against your database to remove constraints and indexes.
    3. Start the application server and continue as described in the instructions.

    After importing — after you've finished running the importer:

    1. Stop the application server.
    2. If you ran the before_postgres.sql script, you must now run after_postgres.sql to add constraints and indexes.
    3. Start the application server and continue with the instructions.

    Known Issues

    Here are the issues known at this release.

    • There are known performance issues with importing very large datasets.
    • Currently, import success reporting includes entries for tables that were empty in the original database. This makes it harder to read than it could be.
    • When importing from MySQL, the final page prints its statistics in triplicate.
    • Logins that are banned permanently from Forums are negated in Clearspace. The workaround is for an admin to ban the users again in Clearspace.
    • Private message drafts are not imported.
    • Private messages are disabled.
    • If a space has a blog added, the admin may have to unset and reset "create blog post" permissions for it.