Upgrade Guide to ReportServer 4.6.1

In this guide we describe how to upgrade ReportServer installations to the latest ReportServer 4.6.1 version. This upgrade guide is valid for ReportServer installations 3.0.1 and higher. This tutorial is valid both for Enterprise and Community versions, as well as for manual installations and Bitnami installer installations.

If you want to perform a new installation check here: Linux or Windows.

Backup all your data before upgrading.

IMPORTANT: In ReportServer 4.4.0, the Saiku and Mondrian libraries were upgraded to 3.16.1 and 9.4, respectively. These are in most of the cases not backward compatible. This means the following:

Pivot table variants: you have to run this script once in order to upgrade your variants using the "-c" (commit) flag: "exec -c pivotUpdate.groovy"
Mondrian datasources: if your Mondrian XML schema is defined in reportserver, you can choose:
- Mondrian 4 users: You can upgrade the schema to version 9, which is compatible with Mondrian 3's syntax, i.e. your schema should not contain after the upgrade: "<Schema name="YourSchema" metamodelVersion="4.0">". More information here. You have to create new variants, configure them, and save them again.
- Mondrian 3 users: Since Mondrian 9's syntax is compatible to Mondrian 3, you only have to create new variants, configure them, and save them again.

In order to use ReportServer 4.6.1 with Oracle, the following jars (or newer versions) are needed: ojdbc6.jar, orai18n.jar, xdb6.jar and xmlparserv2.jar. These are needed because of the new XML/JSON support. Please download and copy them to the WEB-INF/lib directory. Note: we recommend to use ojdbc7.jar or newer because of this jdbc driver incompatibility with null parameters in BIRT reports.

Default configuration files are created on first run of ReportServer. Later, when upgrading ReportServer to a newer version, it is probable that newly added configuration files will be missing (i.e. all configuration files added between the version originally installed and the version upgraded to). You can use the "diffconfigfiles" command for finding out these configuration files, check the Administration Guide for details. Note that default values are used for configuration files that are not found.

The Upgrade in a Nutshell

The upgrade basically consists of replacing the webapp files of ReportServer, that is, the files under TOMCAT/webapps/reportserver (or TOMCAT/webapps/ROOT, depending on your installation) are removed and the freshly downloaded files are copied there instead. In the following we explain the upgrade in detail

Preconditions

In this upgrade guide we assume that you are working with an externalized configuration directory as described in Chapter 5 of the configuration guide. We are also assuming that you use Tomcat as application server. If you are not yet using an external configuration directory, this is a good point to change your setup. As for this upgrade, the main difference is that you do not need to worry about your configuration changes, but can simply do a one-step copy and paste upgrade.

For Bitnami users: We here describe how to upgrade ReportServer without upgrading the entire Bitnami stack.

The Upgrade

To upgrade ReportServer, follow these steps.

Download ReportServer 4.6.1.
Stop your ReportServer instance.
Go to the webapps directory of Tomcat and there to the directory in which ReportServer is installed. If you used the Bitnami installer this is
```
INSTALLATION DIRECTORY/apache-tomcat/webapps/reportserver
```
If you followed the installation tutorial this would be
```
TOMCAT DIRECTORY/webapps/ROOT
```
To check that you have the right folder confirm that this folder contains amongst others a file called ReportServer.html and a folder called ddl.
Clear out the above folder, that is, remove the entire contents. If you do not use external configuration, all your drivers will be deleted, since the whole directory is being replaced by the downloaded one. Backup them to easily add them later. These are found on the WEB-INF/lib directory of your reportserver installation.
Unzip ReportServer 4.6.1 and copy everything to the now empty folder. The structure should be identical to before, that is, you should once more find a file called ReportServer.html and a folder called ddl.
Completely delete your browser's cache (including all temporary internet files!!!) to ensure you will get the newest files. If you get any error of this type: "Type 'net.datenwerke.rs.base.client.dbhelper.dto.DatabaseHelperDto' was not assignable to 'com.google.gwt.user.client.rpc.IsSerializable' and did not have a custom field serializer.For security purposes, this type will not be serialized.: instance = net.datenwerke.rs.base.client.dbhelper.dto.DatabaseHelperDto@62cbf40f at com.google.gwt.user.server.rpc.impl.ServerSerializationStreamWriter.serialize(ServerSerializationStreamWriter.java:667)" you have to delete all browser's cache including all temporary internet files.
Start up Tomcat

This completes the Upgrade to ReportServer 4.6.1. To ensure that installation was successful have a look at your Tomcat log files. Startup should look similar to the following

  _____                       _    _____                            ______       _                       _          
 |  __ \                     | |  / ____|                          |  ____|     | |                     (_)         
 | |__) |___ _ __   ___  _ __| |_| (___   ___ _ ____   _____ _ __  | |__   _ __ | |_ ___ _ __ _ __  _ __ _ ___  ___ 
 |  _  // _ \ '_ \ / _ \| '__| __|\___ \ / _ \ '__\ \ / / _ \ '__| |  __| | '_ \| __/ _ \ '__| '_ \| '__| / __|/ _ \
 | | \ \  __/ |_) | (_) | |  | |_ ____) |  __/ |   \ V /  __/ |    | |____| | | | ||  __/ |  | |_) | |  | \__ \  __/
 |_|  \_\___| .__/ \___/|_|   \__|_____/ \___|_|    \_/ \___|_|    |______|_| |_|\__\___|_|  | .__/|_|  |_|___/\___|
            | |                                                                              | |                    
            |_|                                                                              |_|                    

Version: RS4.6.1-6098-2023-09-21-00-57-26
Code Version: 2023-09-21-00-57-26
Java Version: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.91-b14 (1.8)
VM Args: -agentlib:jdwp=transport=dt_socket,suspend=y,address=localhost:55866 -Xmx2g -Drs.configdir=/opt/reportserver -Dfile.encoding=UTF-8
rs.configdir: /opt/reportserver (OK)

### DB Config ###
hibernate.dialect: net.datenwerke.rs.utils.hibernate.MySQL5Dialect (OK)
hibernate.connection.driver_class: com.mysql.jdbc.Driver (OK)
hibernate.connection.url: jdbc:mysql://127.0.0.1:3309/bitnami_reportserver (OK)
hibernate.connection.username: bn_reportserver
hibernate.connection.password: **********
hibernate.default_schema: 

Connection Test: OK
Schema Version: RS3.0-11

16:27:30.458 INFO  n.datenwerke.rs.EnvironmentValidator - Performing database update RS3.0-11 -> RS3.0-26
16:27:34.220 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-12-MySQL5_UPDATE.sql
16:27:34.230 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-13-MySQL5_UPDATE.sql
16:27:34.240 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-14-MySQL5_UPDATE.sql
16:27:34.250 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-15-MySQL5_UPDATE.sql
16:27:34.260 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-16-MySQL5_UPDATE.sql
16:27:34.270 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-17-MySQL5_UPDATE.sql
16:27:34.280 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-18-MySQL5_UPDATE.sql
16:27:34.290 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-19-MySQL5_UPDATE.sql
16:27:34.300 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-20-MySQL5_UPDATE.sql
16:27:34.310 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-21-MySQL5_UPDATE.sql
16:27:34.320 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-22-MySQL5_UPDATE.sql
16:27:34.330 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-23-MySQL5_UPDATE.sql
16:27:34.340 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-24-MySQL5_UPDATE.sql
16:27:34.350 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-25-MySQL5_UPDATE.sql
16:27:34.360 INFO  n.datenwerke.rs.EnvironmentValidator - Running script RS3.0-26-MySQL5_UPDATE.sql
16:29:35.175 INFO  n.datenwerke.rs.EnvironmentValidator - Validating database schema...

The important parts are the last rows which indicate that the database upgrade script was successfully executed. Note that this only happens once after the upgrade and that from then on any startup would show an updated schema version, that is:

Schema Version: RS3.0-26

Adapt Internal Configuration

An optional step is to adapt the internal configuration files located in ReportSever's file server (folder etc). For an overview of the changes see here.

Upgrade/Install Demo Data

A final optional step is to install or upgrade your existing demo data. For this, check this link. This step will delete all your existing data in the system.

Happy Reporting