1. Home
  2. Tutorials
  3. Upgrade Guide to ReportServer 3.0.1

Upgrade Guide to ReportServer 3.0.1

In this guide we describe how to upgrade ReportServer 2.2.2 (RS2.2.2-5639) installations to ReportServer 3.0.1. This guide assumes that you have installed ReportServer manually and have not setup ReportServer via the Bitnami ReportServer Stack. A separate upgrade guide is available for the Bitnami ReportServer Stack.

Before we continue, make sure that you have a backup of the system including your ReportServer database.

With ReportServer 3.0.1 we have introduced some changes in licensing and now provide two versions of ReportServer: ReportServer Community Edition and ReportServer Enterprise Edition. In the cause of this restructuring we have moved some of the functionality that was previously available in the Open Source version of ReportServer to ReportServer Enterprise (see a detailed comparison between the two versions). In particular, scripting is no longer available in the open source variant of ReportServer. A trial version of ReportServer Enterprise Edition including full scripting capabilities is available on request from mailto:sales@infofabrik.de

If you require any of the following features and do not wish to purchase ReportServer Enterprise Edition, please do not upgrade to Reportserver 3.0.1: Scripting, Dynamic List Templates, Dynamic List Pivot Mode, SAP Crystal, Database Bundles or Conditional Scheduling: click here for a detailed comparison between ReportServer Enterprise and ReportServer Community.

Overview

The following upgrade installation explains how to upgrade to either ReportServer 3.0.1 Community Edition or ReportServer 3.0.1 Enterprise Edition. The upgrade consists of the following steps.

  1. Obtain the ReportServer Program Files
  2. Replace the Tomcat webapp with the new version of ReportServer.
  3. Adapt the external configuration files
  4. Create the Schema Info table
  5. Start ReportServer for an automated upgrade of the database schema

Obtaining the ReportServer Program Files

The binaries for ReportServer Community Edition are available from SourceForge. On SourceForge look for Files and then the bin directory. Beneath the bin directory you should find directories for the various versions of ReportServer. The files are named according to the following schema: RS followed by the version number and the build number, followed by reportserver.zip. For example, RS3.0.1-5834-2016-03-24-23-46-15-reportserver-ce.zip denotes ReportServer version 3.0 minor revision 1 and build number 5834.

Note: You can download a trial version of the latest ReportServer Enterprise Edition here.

Download the new program files to a temporary location. We will refer to the zip archive as REPORTSERVER301.ZIP.

Replace the Program Files

As a first step we need to replace the ReportServer program files. In the following we assume that Tomcat has its webapps directory in TOMCAT_WEBAPPS. In a standard installation, ReportServer is installed in a folder TOMCAT_WEBAPPS/reportserver or in case you decided to install it to be directly accessible it is installed in TOMCAT_WEBAPPS/ROOT. In the following we will refer to the ReportServer installation directory as REPORTSERVER_WEBAPPS_DIR.

To upgrade the program files perform the following steps:

Stop Tomcat

Make sure that the Tomcat server is stopped.

Remove old files

Move everything beneath REPORTSERVER_WEBAPPS_DIR to a temporary directory, such that we can later access old configuration files.

Unzip the new Program Files to REPORTSERVER_WEBAPPS_DIR

Unzip the new program files (REPORTSERVER301.ZIP) to REPORTSERVER_WEBAPPS_DIR. Ensure that the files were extracted to the correct folder. For this check that directly beneath REPORTSERVER_WEBAPPS_DIR there are (amongst others) the folders WEB-INF and ddl.

Adapt External Configuration

In the next step we need to adapt the external configuration. For this we need to configure two configuration files:

  • reportserver.properties — contains ReportServer specific properties
  • persistence.properties — contains the connection properties for ReportServer

Note that the connection properties in previous versions were defined via a file called persistence.xml. Starting with ReportServer 3.0.1 the connection properties are instead defined via the configuration file persistence.properties.

reportserver.properties

You can safely reuse your old version of the configuration file reportserver.properties. Simply copy the old file to REPORTSERVER_WEBAPPS_DIR/WEB-INF/classes.

persistence.properties

The configuration persistence.properties defines the connection properties used by ReportServer. An example configuration file called persistence.properties.example is provided in directory REPORTSERVER_WEBAPPS_DIR/WEB-INF/classes. Rename the persistence.properties.example to persistence.properties and set the following properties according to your database settings: 

hibernate.connection.username=
hibernate.connection.password=
hibernate.dialect=
hibernate.connection.driver_class=
hibernate.connection.url=

You can find the correct configuration values from your old configuration file persistence.xml which is located in REPORTSERVER_OLD_TMPDIR/WEB-INF/classes/META-INF.

Please ensure that the hibernate.dialect is one of the supported ReportServer dialects. These differ from the standard hibernate settings. The supported dialects are:

  • net.datenwerke.rs.utils.hibernate.DB2Dialect
  • net.datenwerke.rs.utils.hibernate.MySQL5Dialect
  • net.datenwerke.rs.utils.hibernate.PostgreSQLDialect
  • net.datenwerke.rs.utils.hibernate.Oracle10gDialect
  • net.datenwerke.rs.utils.hibernate.SQLServer2008Dialect

Tip: ReportServer allows to remove the configuration files from Tomcat's web directory and put them into an external configuration directory. This makes future upgrades easier as upgrading the program files then does not overwrite any configuration. For further information on using an external configuration directory see the chapter on the configuration dir in ReportServer's Configuration Guide as well as the best-practice installation guide.

Create Schema Info Table

Next, we need to perform a small schema update to tell ReportServer what version of the schema is currently used. This step will only be necessary for this upgrade. Connect to your database and issue the following create tabel statement.

For MySQL: 

create table RS_SCHEMAINFO (
        ENTITY_ID bigint not null auto_increment,
        KEY_FIELD varchar(128) not null,
        value longtext,
        primary key (ENTITY_ID)
    ) CHARACTER SET utf8 COLLATE utf8_bin;

For PostgreSQL: 

create table RS_SCHEMAINFO (
	ENTITY_ID serial not null,
	KEY_FIELD varchar(128) not null,
	value text,
	primary key (ENTITY_ID)
);

For DB2: 

create table RS_SCHEMAINFO (
	ENTITY_ID bigint generated by default as identity,
	KEY_FIELD varchar(128) not null,
	value clob(1g),
	primary key (ENTITY_ID)
);

For Oracle: 

create table RS_SCHEMAINFO (
	ENTITY_ID number(19,0) not null,
	KEY_FIELD varchar2(128 char) not null,
	value clob,
	primary key (ENTITY_ID)
);

For Microsoft SQL Server: 

create table RS_SCHEMAINFO (
	ENTITY_ID bigint identity not null,
	KEY_FIELD varchar(128) not null,
	value varchar(MAX),
	primary key (ENTITY_ID)
);

We now need to insert a single line identifying the current schema version. If you have the latest version from source forge installed, then this would be RS2.2.2-5639.

For MySQL, PostgreSQL, DB2 and Microsoft SQL Server 

insert into RS_SCHEMAINFO(KEY_FIELD, value) VALUES('version', 'RS2.2.2-5639');

For Oracle 

insert into RS_SCHEMAINFO(ENTITY_ID, KEY_FIELD, value) VALUES(1, 'version', 'RS2.2.2-5639');

Restart Tomcat

All that is left to do is to restart Tomcat. On the first startup ReportServer will detect that the database needs a schema upgrade and perform the necessary steps. Note that this only works in case you use one of the databases that are supported by ReportServer:

  • DB2
  • Microsoft SQL Server
  • MySQL / MariaDB
  • PostgreSQL
  • Oracle

Adapt Internal Configuration

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

This completes the Upgrade to ReportServer 3.0.1.

Happy Reporting