Skip to main content
Pentaho Documentation

Upgrade Pentaho Servers and Design Tools

The upgrade process is similar whether you are upgrading the entire Pentaho Business Analytics (BA) suite or the Data Integration (DI) pieces only.

Upgrade the Pentaho Business Analytics Server

After you finish the prerequisite tasks located in Prepare Your Pentaho Server for Upgrade, there are a few tasks that you will need to complete in order to upgrade to Pentaho 6.1 successfully.

These sections will guide you through the remaining steps of the Pentaho BA upgrade process:

  • Backup Your BA Server Configuration and Solutions Files
  • Install Pentaho Business Analytics 6.1
  • Restore Your BA Server Configuration and Solutions Files
    • Enable Logging Before Restoring Files
  • Test Your BA Server
  • Update Your Pentaho Client Tools

Step 1: Backup Your BA Server Configuration and Solutions Files

The backup utility copies your Pentaho configuration and solutions files, then stores the created .zip files in your user's home directory. You will need to merge your customizations if you have previously customized any of these things: server.xml, startup and shutdown scripts, or system listeners. We recommend making complete backups of your Quartz, Hibernate, and Jackrabbit databases before continuing with the upgrade process.

  1. Stop the BA Server.
  2. Connect to the cmd line terminal for the BA Server.
  3. At the prompt, run the correct BAServerConfigAndSolutionsBackup utility for your operating system.

Optional: You have the option of manually setting a version parameter here. If a valid version is not automatically found during back-up, the process will be aborted. You will then be prompted to provide the version information as an argument to the utility.

Windows

BAServerConfigAndSolutionsBackup "C:\Program Files\pentaho\server\biserver-ee"

Linux

./BAServerConfigAndSolutionsBackup.sh /opt/custom software/pentaho/server/biserver-ee

The next step is to install a new instance of the Pentaho 6.1 software. 

Step 2: Install Pentaho Business Analytics 6.1

A new archive installation of the Pentaho BA 6.1 package is needed as part of the upgrade process, after you have finished the upgrade prerequisites and backed up your Pentaho BA configuration and solutions files.  You'll need this in order to get all of the required updates.

Make sure to install the new instance of Pentaho on the same server.

Next, do these tasks from the Prepare Your Environment section of the archive installation guides. Make sure that you leave your Pentaho 5.x instance "as is" and unpack Pentaho 6.1 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 6.1 that you should be aware of. Change the Port Numbers for the BA Server has information and steps for how to do both of these things in Pentaho 6.1.

Step 3: Restore Your BA Server Configuration and Solutions Files

After you have unpacked your Pentaho 6.1 bundle, restore your Pentaho files to your 6.1 instance using the restore utility tool. 

If you do not wish to upload or replace your current sample data, it is recommended that you rename the files located in the pentaho-solutions/system/default-content directory prior to restarting the server. These files may include pentaho-operations-mart-etl, pentaho-operations-mart-operations, plugin-samples-zip, and samples-zip.

  1. Open a cmd prompt on the BA Server host machine.
  2. In the prompt, run the BAServerConfigAndSolutionsRestore utility to restore your data from the .zip files located in your user home folder. 

    Windows

    BAServerConfigAndSolutionsRestore "C:\Program Files\pentaho\server\biserver-ee"
    

    Linux

    ./BAServerConfigAndSolutionsRestore.sh /opt/home/pentaho/server/biserver-ee
    

If you are upgrading from Pentaho version 5.4 to 6.1, you must make the modifications specified in the OSGi Modifications for 6.1 section to enable OSGi before starting the BA Server.

  1. If you aren't going to enable logging before restoring files, start the BA Server

Make sure not to interrupt the BA Server the first time you start it after restoring your data.

Optional: Enable Logging before Restoring Files

Before you restore your BA Server configuration and solutions files, enable logging in the logging configuration file:

  1. Locate the /biserver-ee/tomcat/webapps/pentaho/WEB-INF/classes directory and open the log4j.xml file with any text editor. 
  2. Find the parameter for Threshold and change the value as shown here:
Old param value
<param name="Threshold" value="ERROR"/>
New param value
<param name="Threshold" value="INFO"/>
  1. Add this category:
<category name="org.pentaho.platform.engine.core.system.status">
<priority value="INFO"/>
</category>
  1. Save and close the log4j.xml file.
  2. Start the BA Server

Make sure not to interrupt the BA Server the first time you start it after restoring your data.

Step 4: Test Your BA Server

The last thing that you will need to do before testing is to clear the cache from your web browser.

While starting the BA Server, it initializes by installing all the Karaf features. The system waits for these features to be installed before timing out. The default wait befiore timing out is 2 minutes. If you modify any Karaf feature, you should consider changing the Karaf startup timeout setting

Here are some of the things that you might want to do to verify that your content has been restored to the BA Server:

  • Navigate to the your Pentaho URL and make sure the login screen appears.
  • Log into PUC and verify that you can run your old BA content.
  • Verify that your schedules exist and are working properly.
  • Make sure that your Pentaho plugins are installed and functional:
    • Open a report that requires no user prompts and a parameterized report.
    • Create a test report for Interactive Reporting and one for Analyzer, as appropriate.
    • Open a dashboard in Dashboard Designer.
    • Publish a report in Report Designer.
    • Publish an analysis schema from Spoon.
  • Check your application server log. 

Step 5: Update Your Pentaho BA Design Tools

The Pentaho BA design tools are stand-alone tools and are easily updated on your workstations. Pentaho design tools can be found in the Pentaho/design-tools directory.

  1. Stop the design tool, if it is currently running.
  2. Move the old design tool out of the Pentaho folder structure to a temporary folder.
  3. Copy the new version of the design tool into the Pentaho folder structure.
  4. Restart your design tool.

Upgrade the Pentaho Data Integration Server

After you finish the prerequisite tasks located in Prepare Your Pentaho Server for Upgrade, there are a few tasks that you will need to complete in order to upgrade to Pentaho 6.1 successfully.

These sections will guide you through the remaining steps of the Pentaho DI upgrade process:

  • Backup Your DI Server Configuration and Solutions Files
  • Install Pentaho Data Integration 6.1 
  • Restore Your DI Server Configuration and Solutions Files
    • Optional Step: Enable Logging Before Restoring Files
  • Update Your Pentaho DI Client Tool
  • Test Your DI Server

Step 1: Backup Your DI Server Configuration and Solutions Files

The backup utility copies your Pentaho configuration and solutions files, then stores the created .zip files in your user's home directory. You will need to merge your customizations if you have previously customized any of these things: server.xml, startup and shutdown scripts, or system listeners. We recommend making complete backups of your Quartz, Hibernate, and Jackrabbit databases before continuing with the upgrade process.

  1. Stop your DI Server.
  2. Connect to the cmd line terminal for the DI Server. 
  3. At the prompt, run the DIServerConfigAndSolutionsBackup utility for your operating system.

Optional: You have the option of manually setting a version parameter here.If a valid version is not automatically found during back-up, the process will be aborted. You will then be prompted to provide the version information as an argument to the utility.

Windows

DIServerConfigAndSolutionsBackup "C:\Program Files\pentaho\server\data-integration-server"

Linux

./DIServerConfigAndSolutionsBackup.sh /opt/custom software/pentaho/server/data-integration-server

The next step is to install a new instance of Pentaho DI 6.1 software.

Step 2: Install Pentaho Data Integration 6.1 

A new archive installation of the Pentaho DI 6.1 package is needed as part of the upgrade process, after you have finished the upgrade prerequisites and backed up your Pentaho DI configuration and solutions files.  You'll need this in order to get all of the required updates.

Make sure to install the new instance of Pentaho on the same server.

Next, do these tasks from the Prepare Your Environment section of the archive installation guides. Make sure that you leave your Pentaho 5.x or 6.0  instance "as is" and unpack Pentaho 6.1 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 6.1 that you should be aware of. Changing Ports and URLs has information and steps for how to do both of these things for the DI Server in Pentaho 6.1.

Step 3:  Restore Your DI Server Configuration and Solutions Files

After you have unpacked your Pentaho 6.1 bundle, restore your custom data to your 6.1 instance. 

  1. Open a cmd prompt on the DI Server host machine.
  2. In the prompt, run the DIServerConfigAndSolutionsRestore utility to restore your data from the .zip files in your user home folder. 

    Windows

    DIServerConfigAndSolutionsRestore "C:\Program Files\pentaho\server\data-integration-server"
    

    Linux

    ./DIServerConfigAndSolutionsRestore.sh /opt/custom software/pentaho/server/data-integration-server
    

If you are upgrading from Pentaho version 5.4 to 6.1, you must make the modifications specified in the OSGi Modifications for 6.1 section to enable OSGi before starting the BA Server.

  1. If you aren't going to enable logging before restoring files, start the DI Server

Make sure not to interrupt the DI Server the first time you start it after restoring your data.

Optional: Enable Logging before Restoring Files

Before you restore your DI Server configuration and solutions files, enable logging in the logging configuration file:

  1. Locate the /data-integration-server/tomcat/webapps/pentaho-di/WEB-INF/classes directory and open the log4j.xml file with any text editor. 
  2. Find the parameter for Threshold and change the value as shown here:
Old param value
<param name="Threshold" value="ERROR"/>
New param value
<param name="Threshold" value="INFO"/>
  1. Add this category:
<category name="org.pentaho.platform.engine.core.system.status">
<priority value="INFO"/>
</category>
  1. Save and close the log4j.xml file.
  2. Start the DI Server.

Make sure not to interrupt the DI Server the first time you start it after restoring your data.

Step 4: Update Your Pentaho DI Client Tool

The Pentaho DI client tool, Spoon, is easily updated on your workstations.

  1. Stop Spoon, if it is currently running.
  2. Move the old design tool out of the Pentaho folder structure to a temporary folder.
  3. Copy the new version of the design tool into the Pentaho folder structure.
  4. Restart your design tool.

Step 5: Test Your New DI Server

The last thing that you will need to do before testing is to clear the cache from your web browser. Pentaho design tools can be found in the Pentaho/design-tools directory.

While starting the DI Server, it initializes by installing all the Karaf features. The system waits for these features to be installed before timing out. The default wait before timing out is 2 minutes. If you modify any Karaf feature, you should consider changing the Karaf startup timeout setting.

Make sure that the DI Server and Spoon are running, then use this list to verify that your content has been restored to the DI Server.

  • Open old jobs and transformations and ensure that they execute properly.
  • Create a new job, transformation, and/or Agile BI analysis schema and save it as you normally would.
  • Schedule a job or transformation and ensure that the schedule executes properly.
  • Ensure that existing schedules are still valid.
  • If you are using an enterprise repository, share a job or transformation between PDI users and verify that both can access it.
  • Physically restart the server and ensure that the DI Server are automatically started as services.

OSGi Modifications for 6.1

 If you are upgrading from Pentaho version 5.4 to 6.1, you must make the following modifications to enable OSGi:

  1. Locate the  pentaho-solutions/system/pentahoObjects folder and open the spring.xml file with any text editor.
  2. Find the bean element and change the value as shown here:
Old value <bean id="IPluginManager" class="org.pentaho.platform.plugin.services.pluginmgr.DefaultPluginManager" scope="singleton"/>
New value

<bean id="IPluginManager" class="org.pentaho.platform.plugin.services.pluginmgr.PentahoSystemPluginManager" scope="singleton"/>

  1. Save and close the file.
  2. Locate the tomcat/webapps/pentaho/WEB-INF folder and open the web.xml file with any text editor.
  3. Find the comment <!-- insert additional servlets --> and replace it with the following code:
<servlet>
    <servlet-name>proxy</servlet-name>
    <servlet-class>org.apache.felix.http.proxy.ProxyServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<!-- insert additional servlets -->
<servlet-mapping>
    <servlet-name>proxy</servlet-name>
    <url-pattern>/osgi/*</url-pattern>
</servlet-mapping>
  1. Save and close the file.