Skip to main content
Pentaho Documentation

Import Data to BA Server 5.x.x


Importing data into BA Server, version 5.x.x.

After you have exported your data from the 4.8.x server and into the migration bundle file, import the data in the migration bundle file into the 5.x.x server. 

Stop 5.x.x Version of BA Server

 Stop the 5.x.x version of the BA server, as well as the web application server. To do this, complete these steps.

  1. Log into the User Console on the 5.x.x version of the server and ensure that any scheduled reports are paused. The reason that you pause the reports is to ensure that when you migrate the reports into the 5.x.x BA Server, they will not start running before you have had a chance to verify that migration has occurred properly.
  2. Log out of the User Console and stop the server.
  3. Ensure the web application server on which the server is deployed has also been stopped.  

Ensure 5.x.x BA Repository Database Is Running

 Ensure the database that houses the 5.x.x version of the BA Repository is running. If it is not, start it.

Use Migration Tool to Import Data to 5.x.x Server

Use the Migration Tool to import the migration bundle file to the 5.x.x server. The migration bundle file was generated in the previous step. To use the Migration Tool to import data, complete these steps.

  1. If you have not done so already, identify the paths to the pentaho-solutions directory, the pentaho directory that is on your web application server, as well as paths to additional servlets or jar files that you want to export.
  2. Open a Terminal or Command Prompt window, then navigate to the directory where the Migration Tool is installed.
  3. Issue a command in the Terminal or Command Prompt windows that indicates the action you want the Migration Tool to perform, as well as the locations to the pentaho-solutions directory, the pentaho directory that is on the web application server, and optionally any additional servlets and jar files that you want to migrate. Also indicate where you want the Migration Tool to place the migration bundle file. Complete these steps based on your operating system.  The Migration Tool command contains these parameters.
Parameter Description
import Indicates this is an import command. This parameter is required if you want to import a migration bundle file.
temp-dir Specifies the location on the file system to extract the migration bundle to. If the parameter is omitted, the original behavior will be used and the system default temporary directory will be used.
migration-bundle-file Specifies the directory where you want the migration file to be stored. This parameter is optional. If you do not supply it, the migration bundle file is stored in the same directory where the Migration Tool is installed.
pentaho-solutions-dir Indicates the path to the pentaho-solutions directory for the 5.x.x version of the BA Server. This parameter is required.
pentaho-war Indicates the path to pentaho subdirectory in the webapps directory for the 5.x.x version of the BA Server. This parameter is required.
extra-paths Indicates the files in your classpath that are needed to run the BA Server. Files in the classpath include JDBC drivers, the servlet.api file, and any relevant configuration folders. Whether you include this parameter depends on the platform on which your BA Server is deployed. If your BA Server is deployed on Tomcat, do NOT include the extra-paths parameter because the classpaths  are sensed by the Migration Tool when you run it. If your BA Server is deployed on another web application server, use the extra-paths parameter to the files indicated in your classpath.

Windows: Enter a command that follows this format in the Command Prompt window. Make sure you specify a unique, but descriptive, name for the migration bundle. Make it different from the one you used during the export process. The command should be formatted like this.

migrator.bat --import --migration-bundle-file=C:\ --pentaho-solutions-dir=C:\Users\pentaho\biserver-5.0\biserver-ee\pentaho-solutions --pentaho-war=C:\Users\pentaho\biserver-5.0\biserver-ee\tomcat\webapps\pentaho

Linux: Enter a command that follows this format in the Terminal window. The command should be formatted like this. 

./ --import --migration-bundle-file=/Users/mycompany/ --pentaho-solutions-dir=/Users/mycompany/biserver-4.8/biserver-ee/pentaho-solutions --pentaho-war=/Users/mycompany/biserver-4.8/biserver-ee/tomcat/webapps/pentaho
  1. The Migration Tool runs. The progress of the tool is displayed in the Command Prompt or Terminal window.

Review Import Logs

 To verify that the import occurred properly and that data was imported, do these things.

  1. Open a Terminal or Command Prompt window and navigate to the directory where the Migration Tool was installed. The migrator.log file should appear. The migrator.log file contains a log of the import process.
  2. Open the migrator.log file and note any failures or errors. If any failures or errors exist, you might need to migrate that data manually. 
  3. Close the file, then rename the migrator.log file to something else. 

Manually Migrate Additional Data

These types of items must be manually migrated to the 5.x.x server.

  • Migrate JDBC Drivers
  • Migrate Memory Settings
  • Additional Configuration File Changes
  • Other Possible Customizations

Manually Migrate JDBC Drivers

You must manually copy design tools JDBC dirvers from the 4.8.x location to the 5.x.x one. The following table lists the driver, 4.8.x location, and the 5.x.x one.

Design Tool Location in Version 4.8.x Location in Version 5.x.x
BA Server  pentaho/server/biserver-ee/tomcat/lib/   pentaho/server/biserver-ee/tomcat/lib/
Report Designer 
pentaho/design-tools/report-designer/lib/jdbc/   pentaho/design-tools/report-designer/lib/jdbc/ 
Schema Workbench 
pentaho/design-tools/schema-workbench/drivers/   pentaho/design-tools/schema-workbench/drivers/ 
Aggregation Designer  pentaho/design-tools/agg-designer/drivers/   pentaho/design-tools/aggregation-designer/drivers

Metadata Editor 


Manually Adjust Memory Settings

If your memory settings for the BA Server is greater than the default, you will need to adjust it. For information on how to adjust memory settings, see the Changing the Java VM Memory Limits section.

Manually Adjust Custom Security Settings

If you are using a custom security provider such as LDAP or MSAD for your Pentaho system, there are a couple of settings that you will need to update in order to finish your migration successfully.

  1. Locate the pentaho-solutions/system directory and open the file with any text editor.
    1. Change the property for the singleTenantAdminAuthorityName to match the administrator role that you defined for your custom security provider.
    2. Change the property for the singleTenantAdminUserName to match the administrator user user you defined for your custom security provider.
  2. Save and close the file.
  3. Locate the pentaho-solutions/system/data-access directory and open the settings.xml file with any text editor.
    1. Find the sections for data-access-roles and data-access-view-roles.
    2. Add the custom roles that you want to grant access to as shown here: 
 <!-- roles with data access permissions -->
  <data-access-roles>[Your Custom Role(s)]</data-access-roles>
  <!-- users with data access permissions -->
  <!-- roles with datasource view permissions -->
  <data-access-view-roles>Authenticated,[Your Custom Role(s)]</data-access-view-roles>
  1. Save and close the settings.xml file.

Manually Migrate Additional Configuration Settings

Configuration settings are migrated by the Migration Tool as indicated in the What Is Migrated subsection in Prepare BA Migration Plan . If there are additional customizations that you want to migrate, complete these steps.

  1. Back up copies of your 4.8.x and 5.x.x configuration files.
  2. Use the File Diff tool of your choice to compare the 4.8.x and 5.x.x versions of the configuration file.
  3. If there are specific customizations that you made in the 4.8.x version of the configuration file that did not migrate, manually make them in the 5.x.x file. Proceed with caution when doing this.

Manually Migrate Other Customizations

Because of the nature of the software, many customizations can be made. The following presents examples of other customizations you might have made to the 4.8.x system that would need to be migrated to the 5.x.x one.

  • Custom scheduler: If you are using a different implementation of user settings or a scheduler that you have written or have customized, you will need to migrate those manually.
  • Community plugins: If available, you will need to install 5.x.x versions of these plugins. If you have written a plugin, thoroughly test the plugin to ensure that it works with the 5.x.x version of the system.
  • Other web applications: If you have other web applications that have been installed with Pentaho, you must manually update them.