Upgrade from 6.1.x to 8.1

Available Update Files

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

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.1 upgrade.

• Upgrade the Pentaho Business Analytics (BA) Server
• Upgrade the Pentaho Data Integration (DI) Server
• Upgrade Your Design Tools

Pentaho Server Installation

Perform the following steps to install the 8.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-8.1.x.yy-dist file in the Available Update Files section.
4. Execute the supplied install.bat or install.sh 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 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.

Web XML File

Perform the following steps to modify the web.xml file:

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>

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

4. Save and close the web.xml file.

Plugin XML File

Perform the following steps to modify the plugin.xml file:

1. Open the plugin.xml file located here: /pentaho-solutions/system/pentaho-interactive-reporting.
2. Search the plugin.xml file for the <content-generator id="Iadhoc" type="iadhoc"> block.
3. 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>

4. Save and close the plugin.xml file.

Settings XML and Security Setup Files

Perform the following steps to modify the settings.xml and security setup files:

1. Open the settings.xml file located here: server/pentaho-server/pentaho-solutions/system/reporting/settings.xml
2. Add query-limit-ui-enabled and set it to true as shown in the following example:

   <!-- Enabled or disabled row limit control on UI. No value means disabled.-->
   <query-limit-ui-enabled>true</query-limit-ui-enabled>
   

3. Also, add query-limit and set it to 0 as shown in the following example:

   <!-- The maximum number of rows that will be rendered in a report viewer.-->
   <query-limit>0</query-limit>

4. Save and close the settings.xml file.
5. 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.1 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.1 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.1 version of the file.

5. Remove the following directories and their contents. These plugins are not available in version 8.1.

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

Previous Versions of a BA Server

If you are upgrading from a previous version of a BA server, you must update the connection pool parameter.

Perform the following step to update the connection pool parameter:

1. Navigate to the pentaho-server/tomcat/webapps/pentaho/META-INF directory and open the context.xml file with any file editor.
2. Locate the section that contains the following line:

   factory="org.apache.commons.dbcp.BasicDataSourceFactory"

3. Replace it with this line:

   factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
   

4. Save and close the context.xml 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.

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"/>

4. Save and close the file.
5. 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 defaultUser.spring.properties.xml file with any text editor.
6. Locate the following lines:

   defaultAdminUserPassword=cGFzc3dvcmQ=
   defaultNonAdminUserPassword=cGFzc3dvcmQ=

7. Replace the values in these lines with the following values:

   defaultAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
   defaultNonAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde

8. 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:

   <documentation-url>https://help.pentaho.com/Documentation/8.1</documentation-url>

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:

   <!--
   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>

3. If you are embedding CTools, add the following line (as shown above) and set the value to: true

   <cors-requests-allowed>true</cors-requests-allowed>

4. Save and close the file.

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 8.1 files.

Test Your BA Server

You can use the following actions to verify the upgrade was successful:

1. Clear your web browser cache and history.
2. Navigate to your Pentaho URL and make sure the login screen appears.
3. Log on to PUC and verify that you can run your old BA content.
4. Verify that your schedules exist and are working properly.
5. Make sure that 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 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.

Web XML File

Perform the following steps to modify the web.xml file:

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>

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

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

5. Save and close the web.xml file.

License Manager and Security Setup Files

Perform the following steps to modify the licenseManagerAdmin.js and security setup files:

1. Open the licenseManagerAdmin.js file located in the pentaho-server/pentaho-solution/system/admin-plugin/resources/licenseManagerModule directory.
2. Make the following changes to the context path:

   Old Text	window.location = CONTEXT_PATH + "Home"
   New Text	window.location = CONTEXT_PATH + "kettle/status"

3. Save and close the licenseManagerAdmin.js file.
4. 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.1 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.1 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.1 version of the file.

Previous Versions of a DI Server

If you are upgrading from a previous version of a DI server, you must update the connection pool parameter.

Perform the following step to update the connection pool parameter:

1. Navigate to the pentaho-server/tomcat/webapps/pentaho/META-INF directory and open the context.xml file with any file editor.
2. Locate the section that contains the following line:

   factory="org.apache.commons.dbcp.BasicDataSourceFactory"

3. Replace it with this line:

   factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
   

4. Save and close the context.xml 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.

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"/>

4. Save and close the file.
5. 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 defaultUser.spring.properties.xml file with any text editor.
6. Locate the following lines:

   defaultAdminUserPassword=cGFzc3dvcmQ=
   defaultNonAdminUserPassword=cGFzc3dvcmQ=

7. Replace the values in these lines with the following values:

   defaultAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
   defaultNonAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde

8. 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:

   <documentation-url>https://help.pentaho.com/Documentation/8.1/Products/User_Console</documentation-url>

3. Save and close the file.

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 8.1 files.

Test Your DI Server

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

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