Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Upgrade from 7.x or 8.x DI Server to 8.2

The upgrade process from a  7.x or 8.x Data Integration (DI) Server to an 8.2 Pentaho Server assumes that you installed your original DI Server using an archive installation. This process is similar whether you are upgrading the Pentaho Business Analytics (BA) Server or the Data Integration (DI) Server.

If you are currently using Pentaho 7.x or 8.x, and are upgrading to 8.2 on the same server as your current archive installation, use the Upgrade instructions.

Important: This upgrade documentation describes how to upgrade from Pentaho 7.x or 8.x DI Server to Pentaho 8.2. It assumes that you are upgrading to 8.2 on the same server as your current archive installation. We recommend that you read through this material completely before starting.

Get Started with the 7.x or 8.x DI Server to 8.2 Upgrade

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

  1. Verify your current version of the DI Server and PDI. Start with a working installation of at least DI Server 7.x or PDI 7.x.
  2. Verify your system components are current. Ensure that your system components, such as web browsers, Java version, or repository databases, are up-to-date for Pentaho.
  3. Create backups for all the following Pentaho DI databases: 
  • di_hibernate
  • di_quartz
  • di_jackrabbit
  1. 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 and used for most Linux and Unix variants. A Windows version of Info-ZIP is preconfigured and included in the Pentaho update package.
  2. Verify that no users are logged on to the Server. The upgrade process should be performed during off-business hours to minimize impact to your day-to-day operations.
  3. Make sure to obtain the correct version of Java for your system. See Components Reference for more details.

We recommend you review all the following system updates to understand how our products have changed since Pentaho 7.x:

Get the Pentaho Upgrade and Utility Files

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

Perform the following steps to download these files:

  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.2 GA Release in the 8.x list.
  3. On the bottom of the Pentaho 8.2 GA Release page, browse the folders in the Box widget to find the files you need.

Available Update Files

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

Component File Name
DI Server Upgrade Utility pentaho-upgrade-utility-8.2.x.yy-pdi 
Pentaho Server Installation


PDI Client pdi-ee-client-8.2.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 Pentaho 8.2 upgrade.

Upgrade the Pentaho Data Integration Server

After you finish the prerequisite tasks located in Get Started with the Upgrade, then you are ready to upgrade to Pentaho 8.2.

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

  1. Back up Your DI Server Configuration and Solutions Files
  2. Install the 8.2 Pentaho Server
  3. Restore Your DI Server Configuration and Solutions Files
  4. Start and Test the DI Server

Step 1: Back up 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.

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

  1. Stop your DI Server.
  2. Navigate to the directory that the upgrade utility (pentaho-upgrade-utility-8.2.x.yy-pdi) was unpacked to and open a command line prompt. 
  3. At the prompt, run the DIServerConfigAndSolutionsBackup utility for your operating system as shown in the following examples:
    DIServerConfigAndSolutionsBackup.bat <path to your 7.x or 8.x DI server>

    If you are using Windows and the directory path you specified contains white spaces, then be sure to wrap it in double quotation marks (“). 

    ./ <path to your 7.x or 8.x DI 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 DI version if a valid version cannot be automatically found during the backup process.

After the backup utility finishes, you can install a new instance of the Pentaho 8.2 software.

Step 2: Install the 8.2 Pentaho Server

After completing Step 1, you are ready to install the 8.2 Pentaho Server.

Make sure to install the new instance of Pentaho on the same server, yet leave your Pentaho 7.x or 8.x instance "as is" and unpack Pentaho 8.2 into a new directory.

Perform the following steps to install the 8.2 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 a supported version of JRE or JDK. 
  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.
  1. Browse to the location where you unzipped the pentaho-server-ee-8.2.x.yy-dist file in the Available Update Files section.
  2. Execute the supplied install.bat or file.
  3. Agree to the end-user license agreement.
  4. Select the pentaho/server/pentaho-server directory as the location to store the extracted files.

Step 3: Restore Your DI Server Configuration and Solutions Files

After you have unpacked your Pentaho 8.2 bundle, restore your custom data to your 8.2 instance with the restore utility.

Perform the following steps to apply the DIServerConfigAndSolutionsRestore utility:

  1. Delete all the content in the Pentaho Server 8.2 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 as shown in the following examples.


    DIServerConfigAndSolutionsRestore.bat <path to your 8.2 pentaho server>

    If you are using Windows and the directory path you specified contains white spaces, then be sure to wrap it in double quotation marks (“).  


    ./ <path to your 8.2 pentaho server>

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.

Password Encoding

Pentaho version 8.0 changed the password encoding from previous versions.

If you are using your own password encoding, this update is not necessary.

If you wish to use this version of password encoding, perform the following steps:

  1. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentahoObjects.spring.xml file with any text editor.
  2. Locate the line that contains: bean id="IPasswordService"
  3. Verify or modify the class= value with the following value:
    bean id="IPasswordService" class="org.pentaho.platform.util.KettlePasswordService" scope="singleton"/>
  1. Save and close the file.
  2. If you modified the class= value in Step 3, you must make the following modification to encrypt the Pentaho Admin password. In the same pentaho/server/pentaho-server/pentaho-solutions/system directory, open the file with any text editor.
  3. Locate the following lines:
  4. Replace the values in these lines with the following values:
    defaultAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
    defaultNonAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
  5. Save and close the file.

Documentation Version Link

The default URL of the online Pentaho documentation changes with each release. When upgrading, this URL parameter may need to be updated in the pentaho.xml file.

  1. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentaho.xml file with any text editor.
  2. Modify the following <documentation-url> line and replace the previous documentation value with the current documentation value:
  3. Save and close the file.

CORS - Embedding CTools

If your Pentaho deployment requires the ability to embed CTools, you can modify the following settings.

  1. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentaho.xml file with any text editor.
  2. Modify or add the following CORS lines:
    Flag indicating if cross-origin requests are allowed or not.
    accepted values are: true | false
    Comma separated list of domains allowed to do cross-origin requests to the server.
    Example:, http://localhost:1337
    <cors-requests-allowed-domains><!-- allowed domains here --></cors-requests-allowed-domains>
  3. If you are embedding CTools, add the following line (as shown above) and set the value to 'true'.
  4. Save and close the file.

Previously Customized Files

Important: If upgrading from version 7.0, follow these additional steps.

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

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

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

Step 4: Start and Test the DI Server

You are now ready to Start the DI Server.

Do not pause or stop the initial starting of the DI Server.

Test Your Server

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

  1. Clear your web browser cache and history. 
  2. Navigate to your Pentaho URL (the default URL is http://localhost:9080/pentaho-di) and ensure the login screen appears.
  3. Navigate to the kettle/status page.
  4. Log on to Spoon (PDI client) and try to run your existing content.
  5. Ensure that a repository connection can be made using Spoon (PDI client).
  6. Verify any scheduled items exist and are working properly.
  7. Check your application server logs for any errors:
  • The Catalina and Pentaho logs are located at server/pentaho-server/tomcat/logs

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

For Customers Using DI Ops Mart

If you are interested in installing and using DI Ops Mart, see Install DI Operations Mart.

Update Your Design Tool

After completing the upgrade to 8.2, perform the following steps to upgrade the PDI client design tool on your workstations.

  1. Exit the PDI client, if it is currently running.
  2. Back up and rename the 7.x or 8.x existing data-integration directory in the pentaho/design-tools directory to a separate, temporary directory.
  3. Browse to the location where you downloaded the pdi-ee-client-8.2.x.yy-dist file in the Available Update Files section.
  4. If you have not already done so, unzip the new data-integration directory and install it into your existing pentaho/design-tools directory.
  5. Start your new PDI client design tool to verify it has been upgraded to 8.2.
  6. Test the functionality of the new PDI client design tool.

You have now completed your Pentaho upgrade from 7.x or 8.x DI Server to 8.2.