Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation


This guide describes how to upgrade the Pentaho Server from the manual installation of Pentaho version 7.0 to Pentaho 7.1.

  • If you are currently using Pentaho 6.x with a BA Server and/or DI Server, use the Upgrade from 6.x to 7.1 upgrade instructions.

This upgrade documentation assumes that you are upgrading to 7.1 on the same server as your current manual installation.

Get Started with the 7.1Upgrade

To perform this upgrade process, you need to know how to access the Pentaho Server as an Administrator from a command line. You must also perform the following prerequisites:

  1. Verify your current version of Pentaho Suite and PDI. Start with a working installation of Pentaho Server 7.0.
  2. Verify your system components are current. Ensure that your system components, such as web browsers or repository databases, are up-to-date for Pentaho.
  3. Create backups of all the following Pentaho databases:

    • hibernate

    • quartz

    • jackrabbit

  4. For Linux installations only, verify Info-ZIP has been installed and configured. If needed, you can Download, install, and configure Info-ZIP open source compression utility using the Info-ZIP documentation. Info-ZIP is available at‐ A BSD-style license is provided for most Linux and Unix variants. A Windows version of Info-ZIP is preconfigured and included in the Pentaho update package.

  5. Verify no users are logged into the server. The upgrade process should be performed during off-business hours to minimize impact to your day-to-day operations.

We recommended you review the following 7.1 updates to understand how our products have changed since 7.0:

Get the Pentaho Upgrade and Utility Files 

The upgrade process involves utility and installation files you must download from the Pentaho Customer Support Portal

  1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet. 
  2. Click Downloads, then click Pentaho 7.1 GA Release in the 7.x list. 
  3. On the bottom of the Pentaho 7.1 GA Release page, browse the folders in the Box widget to find the files you need, including the file in the Utilities and Tools folder.

Available Update Files

The following files are required to perform a complete Pentaho 7.1 update:

Component File Name
Pentaho Server Upgrade Utility


Pentaho Server Installation


DI Client pdi-ee-client-7.1.x.yy-dist
Pentaho Analyzer paz‐plugin‐ee‐7.1.x.yy-dist
Pentaho Dashboard Designer pdd‐plugin‐ee‐7.1.x.yy-dist
Pentaho Interactive Reporting pir‐plugin‐ee‐7.1.x.yy-dist
Report Designer prd‐ee‐7.1.x.yy-dist
Metadata Editor pme‐ee‐7.1.x.yy-dist
Schema Workbench psw‐ee‐3.14.x.yy-dist
Aggregation Designer pad‐ee‐7.1.x.yy-dist
License Files Pentaho [component] Enterprise Edition.lic

Unzip the Downloaded Files

Perform the following steps to unzip the downloaded files:

  1. If needed, move the downloaded files to a temporary location on your current server.
  2. Unzip each downloaded file.

You are now prepared to begin your 7.0 to 7.1 upgrade.

Upgrade the Pentaho Server

The following steps will guide you through the 7.1 Pentaho Server upgrade process:

  1. Backup Your Pentaho Server Configuration and Solutions Files
  2. Install the 7.1 Pentaho Server and Plugins
  3. Restore Your Server Configuration and Solutions Files
  4. Consider Previous Version Upgrades and Customizations
  5. Start and Test the Pentaho Server

This process assumes you have completed a manual installation of the 7.0 Pentaho Server and are upgrading to version 7.1.

Step 1: Backup Your 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.

Complete the following steps to back up your configuration and solutions files:

  1. Stop the Pentaho Server.
  2. Open a command line terminal and navigate to the unzipped folder of the pentaho-server-ee-upgrade.
  3. At the prompt, run the correct PentahoServerConfigAndSolutionsBackup utility for your operating system as shown in the following examples:


    PentahoServerConfigAndSolutionsBackup.bat "<path to 7.0 pentaho server>"


    ./ <path to 7.0 pentaho server>

    The backup utility has the following optional parameters:
    • pentaho_solutions_folder – use to specify the path to the pentaho-solutions directory if you manually installed it outside of the main pentaho directory structure.
    • pentaho_version – use to specify your Pentaho Server version if a valid version cannot be automatically found during the backup process.

When the backup utility finishes, you can install a new instance of the Pentaho 7.1 software. 

Step 2: Install the 7.1 Pentaho Server and Plugins

After completing Step 1, you are ready to install the 7.1 Pentaho Server and related plugins.

Make sure to install the new instance of Pentaho on the same server yet leave your Pentaho 7.0 "as is" while unpacking Pentaho 7.1 into a new directory.

Pentaho Server Installation

Perform the following steps to install the 7.1 version of the Pentaho Server:

  1. Verify Java 8 is installed on the server machine. If you need to install Java 8, you can download the supported version of JRE or JDK from the Oracle site.
  2. Verify the PENTAHO_JAVA_HOME environment variable is set to the path of your Java installation. If you need to set this variable, use the SET command in Windows or the export command in Linux. If you are using a JRE, verify the JRE_HOME environment variable is also set to the correct location.
  3. Browse to the location where you unzipped the pentaho-server-ee-7.1.x.yy-dist file in the Available Update Files section.
  4. Execute the supplied install.bat or file.
  5. Agree to the end-user license agreement.
  6. Select the pentaho/server/pentaho-server directory as the location to store the extracted files.

Plugin Installation

The following -dist files mentioned in the Available Update Files section pertain to the Analyzer, Interactive Reports, and Dashboard Designer plugins:

  • paz‐plugin‐ee‐8.1.x.yy-dist
  • pdd‐plugin‐ee‐8.1.x.yy-dist
  • pir‐plugin‐ee‐8.1.x.yy-dist

If you use any of these plugins, browse to the location where you unzipped these distributions and perform the following steps for each file:

  1. Execute the supplied install.bat or file.
  2. Agree to the end-user license agreement.
  3. Select the pentaho/server/pentaho-server/pentaho-solutions/system directory as the location to store the extracted files.

Step 3: Restore Your Server Configuration and Solutions Files

After you have unpacked your Pentaho 7.1 bundle, restore your Pentaho files to your 7.1 instance with the restore utility.

Perform the following steps to apply the PentahoServerConfigAndSolutionsRestore utility:

  1. Except as noted below, delete the content in the Pentaho Server 7.1 pentaho-solutions/system/default-content directory. Keep the following files if you intend to reinstall DI Ops Mart:

Once you have finished the upgrade process, see For Customers Using DI Ops Mart

  1. Open a command line terminal and navigate to the unzipped folder of the pentaho-server-ee-upgrade.
  2. In the prompt, run the PentahoServerConfigAndSolutionsRestore utility to restore your data from the .zip files located in your user home directory as shown in the following examples: 


    PentahoServerConfigAndSolutionsRestore.bat "<path to 7.1 pentaho server>"


    ./ "<path to 7.1 pentaho server>"
    If the directory path you specify is not within the main directory structure, use an optional pentaho_solutions_folder parameter to specify its location.

Enable Logging Before Restoring Files

Before starting your 7.1 Pentaho Server, you may want to enable logging.

Perform the following steps to enable logging:

  1. Locate the /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes folder and open the log4j.xml file with any text editor. 
  2. Find the parameter for Threshold and verify its value is set to INFO. If it is not set to INFO, change the value as shown in the example below:
Old param value
<param name="Threshold" value="ERROR"/>
New param value
<param name="Threshold" value="INFO"/>
  1. Verify whether the following category is in the log4j.xml file. If it is not in the file, then add it:
<category name="org.pentaho.platform.engine.core.system.status">
<priority value="INFO"/>
  1. Save and close the log4j.xml file.

The jackrabbit/repository.xml file contains database connection information. Please ensure this database connection information is properly carried over from your 7.0 version of the repository file into the 7.1 version of the file.

Step 4: Consider Previous Version Upgrades and Customizations

This section includes version specific and configuration changes to consider.

Previous Version of a DI Server

If you have manually upgraded to 7.0 from a previous version of Pentaho that used a DI Server, you must also complete the following steps:

  1. Copy the pentaho-solutions/system/jackrabbit/repository.xml file from the 7.0 server (that was upgraded from a DI Server) to the pentaho-solutions/system/jackrabbit folder on the 7.1 Pentaho Server.
  2. Check the file size of the pentaho-solutions/system/pentaho.xml file. If the file size is 0 KB, then the file is corrupted and must be replaced. To resolve this issue, copy the file from your 7.0 DI server and to the 7.1 Pentaho Server and change the theme to sapphire.

Spring Security Update

You must to add the authenticationEventPublisher property to the spring security XML file.

Perform the following steps to add the authenticationEventPublisher property to the applicationContext-spring-security.xml file:

  1. Navigate to the pentaho-solutions/system/applicationContext-spring-security.xml file and open it with any text editor.
  2. Locate the section that contains the following lines:
    <bean id="authenticationManager" ...>
  3. Add the following property within the authenticationManager bean:
    <property name="authenticationEventPublisher">
        <bean class="" />
  4. Save and close the file.

Karaf Customizations

The Pentaho Server installs all the Karaf features upon installation. The system waits for these features to be installed before timing out. The default is to wait two minutes before timing out. If you modified any Karaf feature, you should consider changing the Karaf startup timeout setting.

Previously Customized Files

If you have previously customized any of the following items, verify your customizations have been merged:

  • server.xml
  • Startup and shutdown scripts
  • System listeners
  • Security configuration files

If your previous customizations have not been merged, incorporate them into their 7.1 files. 

Step 5: Start and Test the Pentaho Server

You are now ready to start the Pentaho Server.

Do not pause or stop the initial starting of the server.

After starting the server, check your Catalina and Pentaho logs in the server/pentaho-server/tomcat/logs directory for any errors. See the Installation and Upgrade Issues article to troubleshoot any errors that occur.

Test Your Server

You can use the following actions to ensure your content has been restored to the 7.1 Pentaho Server:

  1. Clear your web browser cache and history.
  2. Navigate to your Pentaho URL (the default URL is http://localhost:8080/pentaho) and ensure the login screen appears.
  3. Log on to PUC and try to run your old BA content.
  4. Verify your schedules exist and are working properly.
  5. Ensure your Pentaho plugins are installed and functional by performing the following tasks:
    • Open a report that requires no user prompts or parameters.
    • Create a test report for Interactive Reporting and a test report for Analyzer.
    • Open a dashboard in Dashboard Designer.
  6. Check your application server log.

If you have upgraded to 7.1 from an earlier DI Server, navigate to your Pentaho DI URL (the default URL is http://localhost:9080/pentaho-di) and verify the following items:

  • Log on and try to access the kettle/status page.
  • Check your Catalina and Pentaho logs in the server/pentaho-server/tomcat/logs directory for any errors.

For troubleshooting issues, refer to the Installation and Upgrade Issues article.

Update Your Design Tools

After completing the server upgrade to 7.1, perform the following steps to upgrade your Pentaho design tools on your workstations:

  1. Exit any of the design tools, if any are currently running.
  2. Backup and rename all the 7.0 existing directories in a separate, temporary diretcory. 
  3. Browse to the location where you downloaded the following -dist files in the Available Update Files section.
  4. If you have not already done so, unzip all the new design tools directories and install them into a pentaho/design-tools directory.
  5. Start your new design tools to verify they were upgraded to 7.1.
  6. Test the functionality of the design tools.

You have now completed your Pentaho upgrade from 7.0 to 7.1.

For Customers Using Analyzer

Analyzer can be upgraded from Visualization API 2.0 to Visualization API 3.0. Before upgrading, please review the following information for more details:

Upgrading from Visualization API 2.0 to Visualization API 3.0 invalidates any visualizations created with 2.0. If you have created any 2.0 visualizations you want to keep, do not upgrade to 3.0.

For Customers Using DI Ops Mart

Now that you have completed the upgrade to 7.1, you can reinstall the DI Ops Mart. Move the following .zip files into the Pentaho Server 7.1 pentaho-solutions/system/default-content folder.


For further instructions, see Install DI Ops Mart