Skip to main content
Pentaho Documentation

Upgrade from 6.1.x to 8.0

Important: This guide describes how to upgrade from Pentaho 6.1.x to Pentaho 8.0. We recommend that you read through this material before starting.

The upgrade process from 6.1.x to 8.0 assumes you manually installed your original BA Server or original DI Server. This process is similar whether you are upgrading the Pentaho Business Analytics (BA) Server or the Data Integration (DI) Server.

Get Started with the 6.1.x to 8.0 Upgrade

Before you begin your Pentaho 8.0 upgrade, you need to know the following items:

  • How to access the Pentaho Server as an Administrator
  • Know where your data is stored
  • Know how to connect to your data 

You will also need to perform the following tasks:

Task Description
Verify your current version of Pentaho Suite and PDI

Start with a working installation of at least Pentaho Suite 6.1.x or PDI 6.1.x.

Verify your system components are current

Make sure that your system components, such as web browsers, Java version, or repository databases, are up-to-date for Pentaho.
Backup your databases Create backups of all Pentaho databases.
BA Databases: DI Databases:
  • hibernate
  • quartz
  • jackrabbit
  • di_hibernate
  • di_quartz
  • di_jackrabbit

 

Download and configure Info-ZIP (Linux only) Download, install, and configure Info-ZIP open source compression utility using the Info-ZIP documentation. Info-ZIP is available at http://www.info‐zip.org/.

The license is a BSD-style license and is provided for most Linux and Unix variants.

A Windows version of Info-ZIP is preconfigured and included in the Pentaho update package.

Verify that no users are logged into the Server Perform this update during off-business hours to minimize impact to your day-to-day operations.
Make sure to get the correct version of Java for your system. Components Reference

It is recommended that you review the 7.0, 7.1 and 8.0 system updates:

Get the Pentaho Upgrade and Utility Files 

Upgrade and utility files are available for 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 8.0 GA Release in the 8.x list. 
  3. On the bottom of the Pentaho 8.0 GA Release page, browse the folders in the Box widget to find the files you need.

Available Update Files

The following BA and DI files are required to perform a complete Pentaho 8.0 update:

Component File Name
BA Server

The following upgrade and installation files are required for the Pentaho Server:

  • biserver-ee-upgrade‐8.0.x.yy-dist
  • pentaho-server-ee-8.0.x.yy-dist 
DI Server

The following upgrade and installation files are required for the Pentaho Server:

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

Unzip the Distribution Files

The -dist.zip files include an End-User License Agreement. Accept the agreement to extract the files.

Perform the following steps to unzip the distribution files:

  1. Unzip the selected dist.zip file.
  2. Execute the supplied install.bat or install.sh files.
  3. When prompted, agree to the end-user license agreement.
  4. Choose the location to store the extracted files.

You are now prepared to begin your Pentaho 8.0 upgrade.

Upgrade the Pentaho Business Analytics Server

If you are not using the BA server, you can skip this section.

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

  1. Backup Your BA Server Configuration and Solutions Files
  2. Install the Pentaho Server 8.0
  3. Restore Your BA Server Configuration and Solutions Files
  4. Update the BA Server Configuration
  5. Test Your BA Server

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 items:

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

Complete the following steps to back up 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. You can also add an optional 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 8.0 software. 

Step 2: Install the Pentaho Server 8.0

Now that you have completed Step 1, you are ready to create a new archive installation of the Pentaho Server 8.0 package. 

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

Next, complete these tasks from the Prepare Your Environment (Windows or Linux) section of the installation guide. Make sure that you leave your Pentaho 6.1.x instance "as is" and unpack Pentaho 8.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, refer to the Change the Port and URLs article for the required settings.

Step 3: Restore Your BA Server Configuration and Solutions Files

After you have unpacked your Pentaho 8.0 bundle, restore your Pentaho files to your 8.0 instance with the restore utility. Use the following steps to apply the BAServerConfigAndSolutionsRestore utility:

  1. Delete all the content in the Pentaho Server 8.0 pentaho-solutions/system/default-content directory.
  2. Open a cmd prompt on the BA Server host machine.
  3. In the prompt, run the BAServerConfigAndSolutionsRestore utility to restore your data from the .zip files located in your user home directory. 

    Windows

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

    Linux

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

Step 4: Update the BA Server Configuration

After you have restored your BA Server configuration and solution files, make the following .xml file changes before starting the server.

  1. Open the web.xml file located here pentaho-server/tomcat/webapps/pentaho/WEB-INF.
  2. Make the following filter class value and parameter value changes:
Old Text
<filter>
  <filter-name>Spring Security Filter Chain Proxy</filter-name>
  <filter-class>org.springframework.security.util.FilterToBeanProxy</filter-class>
  <init-param>
    <param-name>targetBean</param-name>
    <param-value>filterChainProxy</param-value>
  </init-param>
</filter>
New Text
<filter>
  <filter-name>Spring Security Filter Chain Proxy</filter-name>
  <!--@deprecate FilterToBeanProxy in favour of the simpler and Spring Core provided DelegatingFilterProxy-->
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
  <init-param>
    <param-name>targetBeanName</param-name>
    <param-value>filterChainProxy</param-value>
  </init-param>
</filter>
  1. In the same web.xml file, make the following listener value changes:
Old Text
<listener>
  <listener-class>org.springframework.security.ui.session.HttpSessionEventPublisher</listener-class>
</listener>
New Text
<listener>
  <listener-class>org.springframework.security.web.session.HttpSessionEventPublisher</listener-class>
</listener>
  1. Save and close the web.xml file.
  2. Open the plugin.xml file located here: /pentaho-solutions/system/pentaho-interactive-reporting

  3. Search the plugin.xml file for the <content-generator id=”Iadhoc” type=”iadhoc”>  block.
  4. Below that add the following block:
<content-generator id="iadhocasync" type="iadhocasync">
        <classname>com.pentaho.iadhoc.service.BackgroundJobAdHocGenerator</classname>
        <title>Adhoc Async Report Viewer</title>
</content-generator>
  1. Save and close the plugin.xml file.
  2. Open the settings.xml file located here: server/pentaho-server/pentaho-solutions/system/reporting/settings.xml
  3. Update the query-limit-ui-enabled setting to true and the query-limit setting to 0 as shown in the following example lines of code:
<!-- Enabled or disabled row limit control on UI. No value means disabled.-->
<query-limit-ui-enabled>true</query-limit-ui-enabled>
<!-- The maximum number of rows that will be rendered in a report viewer.-->
<query-limit>0</query-limit>
  1. Save and close the settings.xml file.
  2. If you modified any of the following system configuration files in the pentaho-solutions/system directory of your previous installation, these modifications must be applied to the same Pentaho 8.0 files:
  • jackrabbit/repository.xml
  • applicationContext-logging.xml.original
  • applicationContext-pentaho-security-jackrabbit.xml.original
  • applicationContext-pentaho-security-jdbc.xml.original
  • applicationContext-pentaho-security-ldap.xml.original
  • applicationContext-pentaho-security-memory.xml.original
  • applicationContext-spring-security-cas.xml.original
  • applicationContext-spring-security-jackrabbit.xml.original
  • applicationContext-spring-security-jdbc.xml.original
  • applicationContext-spring-security-ldap.xml.original
  • applicationContext-spring-security-memory.xml.original
  • applicationContext-spring-security-superuser.xml.original
  • applicationContext-spring-security.xml.original
  • pentahoObjects.spring.xml.original
  • pentahoServices.spring.xml.original
  • repository.spring.xml.original
  • log4j.xml – which is located at server/pentaho-server/tomcat/webapps/Pentaho/WEB-INF/classes/log4j.xml

The upgrade utility contains a set of spring configuration files in their original 6.1.0.11-R state. After the utility scripts run, determine the differences between your 6.1.x files and these originals, then apply these changes to the 8.0 configuration files.

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

  1. Remove the following directories and their contents. These plugins are not available in version 8.0.
Plugin Path
Mobile /Pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-mobile-plugin
Sparkl /Pentaho/server/pentaho-server/pentaho-solutions/system/sparkl
  1. Start the BA Server.

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

Step 5: Test Your BA Server

Before testing, 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 two minutes. If you modify any Karaf feature, you should consider changing the Karaf startup timeout setting

Verify that the upgrade was successful:

  • Navigate to your Pentaho URL and make sure the login screen appears.
  • Log on to 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 by performing the following tasks:
    • 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 the PDI Client (Spoon), if you have installed the Agile BI plugin available in the marketplace. (If not, you can publish an analysis schema using the Publish Model job entry.)
  • Check your application server log. 

For Customers Using BA Ops Mart

Now that you have completed the upgrade to 8.0, you can reinstall the BA Ops Mart. For further instructions, see Monitor System Performance Using Pentaho Operations Mart

Upgrade the Pentaho Data Integration Server

After you finish the prerequisite tasks located in Prepare for Your Upgrade, you are ready to upgrade to Pentaho 8.0.

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

  1. Backup Your DI Server Configuration and Solutions Files
  2. Install the Pentaho Server 8.0 
  3. Restore Your DI Server Configuration and Solutions Files
  4. Update the DI Server Configuration
  5. 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 items:

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

Complete the following steps to back up 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. You can also add an optional 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 8.0 software.

Step 2: Install the Pentaho Server 8.0 

Now that you have completed Step 1, you are ready to create a new archive installation of the Pentaho Server 8.0 package. 

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

Next, complete these tasks from the Prepare Your Environment (Windows or Linux) section of the installation guide. Make sure that you leave your Pentaho 6.1.x instance "as is" and unpack Pentaho 8.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, refer to the Change the Port and URLs article for the required settings.

Step 3:  Restore Your DI Server Configuration and Solutions Files

After you have unpacked your Pentaho 8.0 bundle, restore your custom data to your 8.0 instance with the restore utility. Use the following steps to apply the DIServerConfigAndSolutionsRestore utility:

  1. Delete all the content in the Pentaho Server 8.0 pentaho-solutions/system/default-content directory.
  2. Open a cmd prompt on the DI Server host machine.
  3. In the prompt, run the DIServerConfigAndSolutionsRestore utility to restore your data from the .zip files in your user home directory. 

    Windows

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

    Linux

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

Step 4: Update the DI Server Configuration

After restoring your DI Server configuration and solution files and enabling the DI Server, update your configuration by making changes to the web.xml file, the licenseManagerAdmin.js file, and any configuration files you modified in your previous installation.

  1. Open the web.xml file located in the pentaho-server/tomcat/webapps/pentaho-di/WEB-INF directory.
  2. Make the following filter value changes:
Old Text
<filter>
        <filter-name>Pentaho Web Context Filter</filter-name>
        <filter-class>org.pentaho.platform.web.http.filters.PentahoWebContextFilter</filter-class>
    </filter>
New Text
<filter>
       <filter-name>Pentaho Web Context Filter</filter-name>
       <filter-class>com.pentaho.platform.web.http.filters.PentahoEnterpriseWebContextFilter</filter-class>
   </filter>    
  1. In the same web.xml file, make the following filter class value and parameter value changes:
Old Text
<filter>
  <filter-name>Spring Security Filter Chain Proxy</filter-name>
  <filter-class>org.springframework.security.util.FilterToBeanProxy</filter-class>
  <init-param>
    <param-name>targetBean</param-name>
    <param-value>filterChainProxy</param-value>
  </init-param>
</filter>
New Text
<filter>
  <filter-name>Spring Security Filter Chain Proxy</filter-name>
  <!--@deprecate FilterToBeanProxy in favour of the simpler and Spring Core provided DelegatingFilterProxy-->
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
  <init-param>
    <param-name>targetBeanName</param-name>
    <param-value>filterChainProxy</param-value>
  </init-param>
</filter>
  1. And then, make the following listener value changes:
Old Text
<listener>
  <listener-class>org.springframework.security.ui.session.HttpSessionEventPublisher</listener-class>
</listener>
New Text
<listener>
  <listener-class>org.springframework.security.web.session.HttpSessionEventPublisher</listener-class>
</listener>
  1. Save and close the web.xml file.
  2. Open the licenseManagerAdmin.js file located in the pentaho-server/pentaho-solution/system/admin-plugin/resources/licenseManagerModule directory.
  3. Make the following changes to the context path:
Old Text
window.location = CONTEXT_PATH + "Home"
New Text
window.location = CONTEXT_PATH + "kettle/status"
  1. Save and close the licenseManagerAdmin.js file.
  2. If you modified any of the following system configuration files in the pentaho-solutions/system directory of your previous installation, these modifications must be applied to the same Pentaho 8.0 files:
  • jackrabbit/repository.xml
  • applicationContext-logging.xml.original
  • applicationContext-pentaho-security-jackrabbit.xml.original
  • applicationContext-pentaho-security-jdbc.xml.original
  • applicationContext-pentaho-security-ldap.xml.original
  • applicationContext-pentaho-security-memory.xml.original
  • applicationContext-spring-security-cas.xml.original
  • applicationContext-spring-security-jackrabbit.xml.original
  • applicationContext-spring-security-jdbc.xml.original
  • applicationContext-spring-security-ldap.xml.original
  • applicationContext-spring-security-memory.xml.original
  • applicationContext-spring-security-superuser.xml.original
  • applicationContext-spring-security.xml.original
  • pentahoObjects.spring.xml.original
  • pentahoServices.spring.xml.original
  • repository.spring.xml.original
  • log4j.xml – which is located at server/pentaho-server/tomcat/webapps/pentaho-di/WEB-INF/classes/log4j.xml

The upgrade utility contains a set of spring configuration files in their original 6.1.0.11-R state. After the utility scripts run, determine the differences between your 6.1.x files and these originals, then apply these changes to the 8.0 configuration files.

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

  1. Start the DI Server.

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

Step 5: Test Your DI Server

Before testing, clear the cache from your web browser. 

As the DI Server starts, 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 the PDI Client (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 or transformation 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.

If the test fails, the PUCLogin.jsp and index.jsp files may have been corrupted during the upgrade process. If they are corrupted, these files must be replaced to resolve this issue, as shown in the following steps:

  1. To verify corruption has occurred, open the tomcat/webapps/pentaho-di/jsp/PUCLogin.jsp file to see if it is empty or has corrupted information.
  2. Retrieve the original PUCLogin.jsp from the pentaho-server-ee-8.0.x.yy-dist file and use it to replace the corrupted one in the tomcat/webapps/pentaho-di/jsp directory.
  3. Edit the new PUCLogin.jsp file to replace “Home” with “kettle/status”.
  4. Save and close the file.
  5. Open the tomcat/webapps/ROOT/index.jsp file to verify corruption has occurred.
  6. Retrieve the original index.jsp file and use it to replace the corrupted one in the tomcat/webapps/ROOT directory.
  7. Edit the new index.jsp file to replace “pentaho” with “pentaho-di”.
  8. Save and close the file.

For Customers Using DI Ops Mart

Now that you have completed the upgrade to 8.0, you can reinstall the DI Ops Mart. For further instructions, see Install DI Operations Mart

Update Your Design Tools

Now that you have completed the upgrade to 8.0, 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 all the 6.1.x existing directories in the Pentaho/design-tools directory to a temporary directory. 
  3. Browse to the location where you downloaded the following -dist files in the Available Update Files section:
  • pdi-ee-client-8.0.x.yy-dist
  • prd-ee-8.0.x.yy-dist
  • pme-ee-8.0.x.yy-dist
  • psw-ee-8.0.x.yy-dist
  • pad-ee-8.0.x.yy-dist
  1.  Unzip and copy all the new design tools directories into your existing Pentaho/design-tools directory.
  2. Restart to verify that your design tools were upgraded.

You have now completed your Pentaho upgrade from 6.1.x to 8.0.

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: http://pentaho.github.io/pentaho-platform-plugin-common-ui/platform/visual/analyzer-viz-api.