Skip to main content
Pentaho Documentation

Upgrade Pentaho Servers and Design Tools

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

This process assumes you manually installed your original BA Server or original DI Server.

Upgrade the Pentaho Business Analytics Server

After you finish the prerequisite tasks located in Before You Begin, there are a few tasks that you will need to complete in order to upgrade to Pentaho 7.0 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 the Pentaho Server 7.0
  • Restore Your BA Server Configuration and Solutions Files
    • Enable Logging Before Restoring Files
  • Update the BA Server Configuration
  • Test Your BA Server
  • Update Your BA Design 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, system listeners, or security configuration files. 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 7.0 software. 

Step 2: Install the Pentaho Server 7.0

A new archive installation of the Pentaho Server 7.0 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 or 6.x instance "as is" and unpack Pentaho 7.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 7.0 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 7.0.

Step 3: Restore Your BA Server Configuration and Solutions Files

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

  1. Delete all the content in the Pentaho Server 7.0 pentaho-solutions/system/default-content folder.
  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 folder. 

    Windows

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

    Linux

    ./BAServerConfigAndSolutionsRestore.sh /opt/home/pentaho/server/pentaho-server
    
  1. If you are not going to enable logging before restoring files, update the BA Server configuration

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 verify its value is set to INFO. If it is not set to INFO, change the value as shown here:
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"/>
</category>
  1. Save and close the log4j.xml file.

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 folder of your previous installation, these modifications must be      applied to the same Pentaho 7.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.7 state. After the utility scripts run, determine the differences between your 6.1 files and these originals, then apply these changes to the 7.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 version of the repository file into the 7.0 version of the file.

  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

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

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

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

Step 6: Update Your 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 Before You Begin, there are a few tasks that you will need to complete in order to upgrade to Pentaho 7.0 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 the Pentaho Server 7.0 
  • Restore Your DI Server Configuration and Solutions Files
    • Optional Step: Enable Logging Before Restoring Files
  • Update the DI Server Configuration
  • 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, system listeners, or security configuration files. 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 7.0 software.

Step 2: Install the Pentaho Server 7.0 

A new archive installation of the Pentaho Server 7.0 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.x instance "as is" and unpack Pentaho 7.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 7.0 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 7.0.

Step 3:  Restore Your DI Server Configuration and Solutions Files

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

  1. Delete all the content in the Pentaho Server 7.0 pentaho-solutions/system/default-content folder.
  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 folder. 

    Windows

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

    Linux

    ./DIServerConfigAndSolutionsRestore.sh /opt/custom software/pentaho/server/pentaho-server
    
  1. If you are not going to enable logging before restoring files, update the DI Server configuration

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/WEB-INF/classes directory 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 here:
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"/>
</category>
  1. Save and close the log4j.xml file.

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/WEB-INF folder.
  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 folder.
  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 folder of your previous installation, these modifications must be applied to the same Pentaho 7.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.7 state. After the utility scripts run, determine the differences between your 6.1 files and these originals, then apply these changes to the 7.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 version of the repository file into the 7.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: 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 6: 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 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-7.0..x.yy-dist file and use it to replace the corrupted one in the tomcat/webapps/pentaho-di/jsp folder.
  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 folder.
  7. Edit the new index.jsp file to replace “pentaho” with “pentaho-di”.
  8. Save and close the file.