Skip to main content
Pentaho Documentation

Upgrade Pentaho Servers and Design Tools (JBoss)

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:

  • Copy and Save Files from Your 5.x or 6.0 BA Installation
  • 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

For the manual upgrade process, you will need to copy and save some files into a temporary location, such as a folder on your desktop. Later in Step 3, you can either drop them back into the respective directories or manually merge the files.

If you are using JBoss, you will also need to save a copy of your standalone.xml file.

When you are done saving these files, make sure that the Application Server can still access your .installedLicenses.xml.

These are the files that you will need to work with:

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

Step 2: Install Pentaho Business Analytics 6.1

A fresh manual installation of the Pentaho BA 6.1 package is needed as part of the upgrade process if you plan to use JBoss, 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.

Next, do these tasks from the Prepare Your Environment section of the manual 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. 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

You can either drop and replace the files back into their appropriate directories or use a diff tool and manually merge your configuration and solutions files.

If you are upgrading from Pentaho 5.x to 6.1, you will need to manually merge the jboss-deployment-structure.xml file that you copied from the pentaho.war.

Make sure to update the pentaho-solutions directory path in your web.xml file so that it points to your Pentaho 6.1 directory.

If you aren't going to enable logging after 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 before 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:

  • Copy and Save Files from your 5.x or 6.0 DI Installation
  • 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

For the manual upgrade process, you will need to copy and save these files into a temporary location, such as a folder on your desktop. Later in Step 3 you can either drop them back into the respective directories or manually merge the files.

If you are using Jboss, you will also need to save a copy of your standalone.xml file.

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

Step 2: Install Pentaho Data Integration 6.1 

A fresh manual installation of the Pentaho DI 6.1 package is needed as part of the upgrade process if you are using JBoss, 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.

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. 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

You can either drop and replace the files into the appropriate directories or use a diff tool and merge your configuration and solutions files.

If you are upgrading from Pentaho 5.x to 6.1, you will need to manually merge the jboss-deployment-structure.xml file that you copied from the pentaho.war.

Make sure to update the pentaho-solutions directory path in your web.xml file so that it points to your Pentaho 6.1 directory.

If you aren't going to enable logging after 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.