Steps to upgrade Pentaho from lower version to higher version

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

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, including the pentaho-server-ee-upgrade-8.2.x.yy file in the Utilities and Tools folder.

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.

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

1. Back up Your Pentaho Server Configuration and Solutions Files
2. Install the 8.2 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

Step 1: Back up Your Pentaho 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 directory of the pentaho-upgrade-utility-8.2.x.yy-pentaho.
3. At the prompt, run the correct PentahoServerConfigAndSolutionsBackup utility for your operating system as shown in the following examples:

./PentahoServerConfigAndSolutionsBackup.sh <path to your 8.x pentaho server>

Step 2: Install the 8.2 Pentaho Server and Plugins

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

1. Perform the following steps to install the 8.2 version of the Pentaho Server:
2. 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.
3. Verify the PENTAHO_JAVA_HOME environment variable is set to the path of your Java installation.
4. If you need to set this variable, use the SET command in Windows or the export command in Linux.
5. If you are using a JRE, verify the JRE_HOME environment variable is also set to the correct location.
6. Browse to the location where you unzipped the pentaho-server-ee-8.2.x.yy-dist file in the Available Update Files section.
7. Execute the supplied install.bat or install.sh file.
8. Agree to the end-user license agreement.
9. 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.2.x.yy-dist
pir‐plugin‐ee‐8.2.x.yy-dist
pdd‐plugin‐ee‐8.2.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 install.sh 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 8.2 bundle, restore your Pentaho files to your 8.2 instance with the restore utility.

Perform the following steps to apply the PentahoServerConfigAndSolutionsRestore utility:

1. Delete the content in the Pentaho Server 8.2 pentaho-solutions/system/default-content directory.
2. Open a command line terminal and navigate to the unzipped directory of the pentaho-upgrade-utility-8.2.x.yy-pentaho.
3. 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.sh <path to 8.2 pentaho server>

Step 4: Consider Previous Version Upgrades and Customizations

This section includes version specific and configuration changes to consider.

If you are upgrading from Pentaho version 7.x, perform the following steps:

1. Ensure the database connection information in the jackrabbit/repository.xml file is properly carried over from the 7.x version of this file to the 8.2 version. If the 8.2 version differs from 7.x, you must match these files manually.
2. Update the path to the pentaho.log file in the tomcat/webapps/pentaho/WEB-INF/classes/log4j.xml file.
3. Remove the following directories and their contents. These plugins are not available in version 8.2.
   Plugin Path

Mobile pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-mobile-plugin
Sparkl pentaho/server/pentaho-server/pentaho-solutions/system/sparkl

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. <documentation-url>https://help.pentaho.com/Documentation/8.2/Products/User_Console&lt;/documentation-url>

4. Save and close the file.

CORS – Embedding CTools

1. If your Pentaho deployment requires the ability to embed CTools, you can modify the following settings.
2. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentaho.xml file with any text editor.
3. Modify or add the following CORS lines:

4. <!--
   cors-requests-allowed:
   Flag indicating if cross-origin requests are allowed or not.
   accepted values are: true | false
   -->
   <cors-requests-allowed>false</cors-requests-allowed>
   <!--
   cors-requests-allowed-domains:
   Comma separated list of domains allowed to do cross-origin requests to the server.
   Example:
   http://domainA.com, http://localhost:1337
   -->
   <cors-requests-allowed-domains><!-- allowed domains here --></cors-requests-allowed-domains>

5. Save and close the file.

Previously Customized Files

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

1. server.xml
2. startup and shutdown scripts
3. system listeners
4. security configuration files
5. If your previous customizations have not been merged, incorporate them into their 8.2 files.

Step 5: Start and Test the Pentaho Server

You are now ready to Start your 8.2 Pentaho 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:8080/pentaho) and ensure the login screen appears.
3. Log on to PUC and try to run your existing content.
4. Verify your schedules exist and are working properly.
5. Ensure your Pentaho plugins are installed and functional by performing the following tasks:
6. Open a report that requires no user prompts or parameters.
7. Create a test report for Interactive Reporting and a test report for Analyzer.
8. Open a dashboard in Dashboard Designer.
9. Examine the application server logs for any errors:
10. Check your Catalina and Pentaho logs in the server/pentaho-server/tomcat/logs directory.
11. Log on and try to access the kettle/status page.

Update Your Design Tools

After completing the server upgrade to 8.2, perform the following steps to upgrade your Pentaho design tools on your workstations. Exit any of the design tools, if any are currently running.

1. Back up and rename all the 7.x or 8.x existing directories in a separate, temporary directory.
2. Browse to the location where you downloaded the following -dist files in the Available Update Files section:

3. pdi-ee-client-8.2.x.yy-dist
   prd-ee-8.2.x.yy-dist
   pme-ee-8.2.x.yy-dist
   psw-ee-8.2.x.yy-dist
   pad-ee-8.2.x.yy-dist

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 8.2.
6. Test the functionality of the design tools.

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