Skip to main content
Pentaho Documentation

Prepare BA Migration Plan

Overview

Helps you plan to migrate your BA system.

Planning essential for a successful migration experience. As you formulate your strategy, consider these questions.

Should You Migrate To Version 5.x.x?

As you determine whether to migrate your system to this version of the software, consider these questions.

  • Does this version of the software contain new features or bug fixes that your organization needs?
  • Is your current system near or at End of Life? See the Support section of the Pentaho Website to determine if your version of the system is still being supported.

What Resources Do You Need?

Resources are a key component in a migration plan. Consider both technical and human resources.

  • Do your systems meet the hardware and software requirements indicated in the Supported Components matrix?
  • Who should be involved in the migration process? Smaller systems that are housed on a single computer can sometimes be migrated by one person. But, larger or geographically distributed systems might involve more people. For example, the web application server and security might be handled by one group while reporting databases might be handled by another. List those who can provide needed information or help troubleshoot problems. Remember to include stakeholders.
  • Who will help verify that data has been migrated correctly? Keep in mind that some information, such as user favorites, are sometimes best verified by end users.
  • You will need to download the Migration Tool from our site. You also need a text editor, and a tool to compare the differences between text files.

How Much Time Will The Migration Process Take?

The amount of time it takes to perform the migration process varies based on how much data you have and how much you have configured the 4.8.x system. Allot time to install and configure the licenses for the 5.x.x system, run the Migration Tool, perform manual configuration tasks, and to test and troubleshoot the system. After testing, allow time to configure the 5.x.x system, deprovision the 4.8.x server, and provision the 5.x.x one.  Use these time estimates as a rough guide.

Table 1. Migration Process Time Estimates
Task

Time Estimate

Description
Installing 5.x.x system, licenses, and the Migration Tool 1 to 3 Hours If you decide to use the installation wizard to 5.x.x server, allot about one hour to run the installation wizard and the license, and to also download and unpack the Migration Tool.  If you need to customize your BA Repository database, web application server, or both, set aside anywhere from one to three hours to work through the custom or manual installation procedures, install licenses, and to download and unpack the Migration Tool.
Run Migration Tool 30 minutes to several hours. 1 second per solutions and generated content file in the pentaho-solutions directory. For small to mid-sized systems, set aside approximately one hour to extract data from the 4.8.x system and one hour to migrate the data to the 5.x.x system. For greater accuracy, allow approximately one second per content file in the pentaho-solutions directorry. Include associated files such as graphics, .xaction, .xml, and report files.) Add approximately 20 to 30 minutes to migrate other types of data.
Verify Migration 1 Hour to Several Days Plan to spend anywhere from a few hours to several days for validation testing.   The amount of time that you spend depends on your content, the numbers of users you have, and how exhaustively you want to test the system.

When Should You Migrate?

Once you have identified your resources and have estimated how much time it might take to migrate your system, consider appropriate timeframes for migration.

  • Some parts of the process require that the 4.8.x and 5.x.x servers be offline. How much downtime does your organization allow?
  • Consider performing the migration process during off-peak hours.  
  • Consider organizational events and seasonal reporting needs as you select a timeframe.

What Data Will Be Migrated with the Migration Tool?

It is important to understand what types of data is migrated from the 4.8.x system to the 5.x.x one. Much of the data from the 4.8.x server can be migrated automatically using the Migration Tool, but some must be migrated manually.  The Migration Tool is a standalone utility that you can download from our website. If you use the Migration Tool, it will attempt to migrate all of the data in the following BA Data Migrated by the Migration Tool table. You cannot choose to only migrate some of the data at a time; the tool migrates all of it at one time.

Table 2. BA Data Migrated by the Migration Tool
Type of Data Data Migrated with the Migration Tool

Exceptions

Solution Content All solution content in the pentaho-solutions directory.   This includes all report files, including all associated property, graphic, xactions, javascript, XML, and other files. Localization files for directories and content files are also migrated, as are permission settings for the solution content files. If you have the sample steel-wheels directory and steel-wheels directories present, those are migrated as well. The following subdirectories that are in the pentaho-solution directory are NOT migrated: Admin, Systems, and Temp. Any Pentaho system localization data is not migrated. Audit information is not migrated.
Generated Content All generated content, such as PDF copies of reports. N/A
Data Sources: Data Wizard, JDBC, Metadata, and Mondrian Connection name, settings (host name, database name, port number, user name, password), database type, access type, advanced options, pooling, and other options such as maximum active connections, driver class, idle connection, query, and wait values. Mondrian catalogs are also migrated as are Mondrian schemas that are not registered in the datasource.xml file but that are part of solution content. N/A
Schedules Public and private schedules. Public schedules that have no subscribers.
System Configuration Information in these files: applicationContext-security-ldap.properties, applicationContext-spring-security-hibernate.properties, pentaho-spring-beans.xml, pentaho.xml, quartz.properties, mondrian.properties, settings.xml for various plugins, analyzer.properties, email_config.xml. Also migrated are the following tomcat files: web.xml, context.xml, classic-engine.properties, logging.properties, log4j.xml. settings.xml files for dashboards, analyzer, data-access, kettle, pentaho geo, and reporting are migrated as well. JNDI data sources named "Hibernate" or "Quartz" will not be migrated. Only the following web.xml settings are migrated: Solution-path, Base-url, Fully-qualified-server-url, Locale-language, contextClass, contextConfigLocation, pentahoObjectFactory, encoding, hsqldb-databases, Proxy Trusting Filter, TrustedIpAddrs. No custom servlets or filters will be migrated.   Note also that the audit files are not migrated because there is a different auditing mechanism used in the 5.x.x version of the system.
User Preference Settings Recent files list, global settings, and whether to show the tooltips in the User Console page are migrated. If you have set up favorites in Mobile, then favorites are migrated and appear in the User Console. N/A
Users and Roles Usernames, passwords, username description field information, role names, role descriptions, user role assignments are migrated. This data is only migrated if the system is using Pentaho Security to authenticate users.  Note that role permissions are not migrated, regardless of authentication method, and must be manually reset. Instructions for how to do this appear in the Verify BA Migration section of this documentation.

As indicated in the previous table, some configuration files are processed by the Migration Tool. Each configuration file is processed in one of four ways.

  • Overwrites 5.x.x File: The Migration Tool exports a copy of the file from the 4.8.x system, then saves it to the migration bundle. Then, when you import migration data, it replaces the 5.x.x version of the file with the 4.8.x version of the file. The Migration Tool processes configuration files in this way when there were no changes made from version 4.8.x to version 5.x.x of the file, but the file might have been customized by the customer.
  • Adds New Properties to 5.x.x File: The Migration Tool exports a copy of the file from the 4.8.x system, then saves it to the migration bundle. Then, when you import migration data, it finds the properties that exist in the 5.x.x version of the file and adds them to the copy of the 4.8.x version of the file that is in the migration file bundle. The existing 4.8.x version file comments are preserved, in property name order. The Migration Tool processes configuration files in this way when new properties were added to the 5.x.x version of the file.
  • Updates 5.x.x File with 4.8.x Changes: The Migration Tool exports a copy of the file from the 4.8.x system, then saves it to the migration bundle. Then, when you use the tool to import migration data, the Migration Tool adds the new 5.x.x properties and code to the 4.8.x version of the file. This new file then replaces the 5.x.x version of the file that was in the server’s file system, prior to the migration process. The Migration Tool processes configuration files in this way when there were significant changes made to the version 5.x.x configuration files.
  • Updates 4.8.x file with 5.x.x Changes: The Migration Tool exports a copy of the file from the 4.8.x system, then saves it to the migration bundle. Then, when you use the tool to import migration data, the Migration Tool adds 4.8.x properties and code to the 5.x.x version of the file. This file then replaces the 5.x.x version of the file that was in the server’s file system, prior to the migration process. This approach was taken when there were few changes made to the version 5.x.x configuration files.

The following table indicates how the Migration Tool has processed specific configuration files.

Table 3. BA Server Configuration Files Migrated by the Migration Tool and Migration Strategy
Path 4.8.x BA Server 5.x.x BA Server Migration Strategy
system\ applicationContext-security-ldap.properties applicationContext-security-ldap.properties Add New Properties to 5.x.x File
system\ applicationContext-spring-security-hibernate.properties applicationContext-spring-security-hibernate.properties Add New Properties to 5.x.x File
system\ pentaho.xml pentaho.xml Update 4.8.x File with 5.x.x Changes
system\ pentaho-spring-beans.xml security.properties Update 5.x.x File with 4.8.x Changes
system\analyzer\ analyzer.properties analyzer.properties Add New Properties to 5.x.x File
system\analyzer\ settings.xml settings.xml Update 4.8.x File with 5.x.x Changes
system\dashboards\ settings.xml settings.xml Update 4.8.x File with 5.x.x Changes
system\data-access\ settings.xml settings.xml Update 4.8.x File with 5.x.x Changes
system\kettle\ settings.xml settings.xml Overwrite 5.x.x File
system\mondrian\ mondrian.properties mondrian.properties Add New Properties to 5.x.x File
system\pentaho-geo\ settings.xml settings.xml Overwrite 5.x.x File
system\pentaho-interactive-reporting\ settings.xml settings.xml Update 4.8.x File with 5.x.x Changes
system\reporting\ settings.xml settings.xml Update 4.8.x File with 5.x.x Changes
system\smtp-email\ email_config.xml email_config.xml Overwrite 5.x.x File
webapps\pentaho\WEB-INF\ web.xml web.xml Update 5.x.x File with 4.8.x Changes
webapps\pentaho\WEB-INF\classes log4j.xml log4j.xml Update 4.8.x File with 5.x.x Changes
webapps\pentaho\WEB-INF\classes classic-engine.properties classic-engine.properties Add New Properties to 5.x.x File
webapps\pentaho\WEB-INF\classes logging.properties logging.properties Add New Properties to 5.x.x File
webapps\pentaho\META-INF\ context.xml context.xml Update 5.x.x File with 4.8.x Changes

What Data Must Be Migrated Manually?

Data that must be migrated manually includes:

  • JDBC Drivers for your data sources.
  • Memory settings for the server.
  • Any additional JSPs, servlets, custom libraries, plugins, java API extensions that require a change to the pentaho-objects-spring.xml file, themes, or other resources integrated as part of the custom pentaho system.
  • Pentaho system localization information.
  • Generated content for deleted or otherwise inactive users.

Where Are The Components In The 4.8.x System Located?

Identify the paths to the these components so that you can supply them when you export data from the 4.8.x server.

  • Web Application Server
  • BA Repository Database
  • Pentaho web application directory on the web application server
  • Any additional files in the classpath that are needed to boot the BA Server. You only need this information is you have NOT deployed the BA Server on Tomcat

Obtain the location of design tools that are not on the server.

Where Will The Components In The New System Be Located?

Identify the paths to the these components so that you can supply them when you import data into the new server.

  • Web Application Server
  • BA Repository Database
  • Pentaho web application directory on the web application server
  • Any additional files in the classpath that are needed to boot the BA Server. You only need this information is you did NOT deploy the BA Server on Tomcat

Additionally, obtain the location of design tools that are not on the server.

Note: After you migrate the data from the 4.8.x server into the new one, you must verify that the data in both systems match. This is easier to do if you can see the user interfaces for the 4.8.x and new versions of the server at the same time.

How Will You Prepare Users For The Migration?

Consider how you will communicate with users, obtain feedback, and provide training.

  • How will you handle customer feedback about the migration process?
  • How you will communicate with internal and external customers?
  • How much advanced notice will you provide?
  • How will you train users? Note that tutorials and documentation are available in the Infocenter. Additionally, Pentaho offers professionally-led training classes on many aspects of the new system. See the Pentaho website for details.

How Will You Document Your Migration Plan?

Documenting your responses to the questions raised in this section can be an invaluable troubleshooting aid should you need to contact technical support.

  • How will you document the migration plan?
  • Who will have access to the plan and where will it be located? How will this plan be updated throughout the process?