Overlay Upgrade

This chapter describes how to upgrade to JasperReports Server 5.6.1 using the overlay upgrade package. This chapter contains the following sections:

Introduction to the Overlay Upgrade
Upgrade Steps Overview
Back Up Your JasperReports Server Instance
Unpack the Overlay Upgrade Package
Check for JDBC Driver (Oracle, SQL Server, DB2)
Run the Overlay Upgrade
Rerun the Overlay Upgrade
Rollback Procedure
Starting and Logging into JasperReports Server 5.6
Additional Tasks to Complete the Upgrade
Running Overlay Upgrade a Second Time

Introduction to the Overlay Upgrade

JasperReports server now has an overlay upgrade procedure. For now, this is only available with JasperReports Server Commercial edition installed with the WAR file and only with the Apache Tomcat application server.

The overlay upgrade only supports Apache Tomcat as the application server.
The overlay upgrade only supports JasperReports Server version installed using the WAR file. The binary installer is not supported.
All certified databases are supported.

The overlay upgrade supports upgrading from the following JasperReports Server versions:

4.0, 4.0.1, 4.1, 4.2.1, 4.5.1, 4.5.2, 4.7, 4.7.1, 5.0, 5.0.1, 5.1, 5.2, 5.5, 5.6

to JasperReports Server 5.6.1.

Although the overlay upgrade does offer a rollback feature, you should always back up your database and application before upgrading.

This section will use a 4.0 to 5.6 upgrade as an example.

Upgrade Steps Overview

These are the general steps used in this section:

1. Back up your current JasperReports Server instance.

(The overlay tool will additionally back up your war file automatically and ask you if you have backed up your database.)

2. Download and unpack the new JasperReports Server overlay upgrade 5.6.1 package zip file.
3. Run the upgrade steps.

The overlay upgrade procedure will assist you in handling any custom modifications or extensions that you have made to your JasperReports Server instance.

Best practice is to always back up your application and database before upgrading.

Back Up Your JasperReports Server Instance

First you must backup your JasperReports Server WAR file and jasperserver database so that they can be restored in case there is a problem with the upgrade. These steps are performed from the command line in a Windows or Linux shell.

The following backup example is for Tomcat with the PostgreSQL database. For other databases please consult your DB administration documentation for back up information.

Back up your JasperReports Server War File :

1. Create a folder location where you can save your jasperserver-pro war file. For example, C:\JS_40_BACKUP or /opt/JS_40_BACKUP.
2. Copy <tomcat>/webapps/jasperserver-pro  to  <path>/JS_40_BACKUP

Back up your jasperserver Database:

1. Create a folder location (if you did not do so in the step above) where you can save your jasperserver database, For example, C:\JS_40_BACKUP or /opt/JS_40_BACKUP.
2. Run the following commands for PostgreSQL:

cd <path>/JS_40_BACKUP

pg_dump --username=postgres  jasperserver  >  js-db-40-dump.sql

Unpack the Overlay Upgrade Package

The overlay upgrade package comes in a file named: jasperreports-server-overlay-5.6.zip.

1. Download the overlay upgrade package from Jaspersoft technical support (http://support.jaspersoft.com) or contact your sales representative.
2. Extract all files from jasperreports-server-overlay-5.6.1.zip. Create or choose a destination folder, such as C:\JS_OVERLAY on Windows, /home/<user>/JS_OVERLAY on Linux, or /Users/<user>/JS_OVERLAY on Mac.
3. The overlay upgrade package will unpack into a folder named:

overlay

This folder location will be known as:

<overlay-folder>

Check for JDBC Driver (Oracle, SQL Server, DB2)

As of version 5.6.1, JasperReports Server uses the TIBCO JDBC drivers for the following commercial databases: Oracle, SQL Server, or DB2. If you want to use a different JDBC driver, you need to copy it to the correct location.

With Oracle, for example, the alternate JDBC jar should be copied into the following location:

<overlay-folder>/buildomatic/conf_source/db/oracle/jdbc

For DB2, the alternate JDBC jar should be copied into the following location:

<overlay-folder>/buildomatic/conf_source/db/db2/jdbc

For SQL Server, the alternate JDBC jar should be copied into the following location:

<overlay-folder>/buildomatic/conf_source/db/sqlserver/jdbc

In addition, for SQL Server, modify the default_master.properties file in your existing installation to comment out the maven version:

1. Open the default_master.properties in your existing installation in a text editor.
2. Locate the line:

maven.jdbc.version=1.6

and change it to:

# maven.jdbc.version=1.6

For MS SQL Server, comment out the maven version information in your existing copy of default_master.properties.

Run the Overlay Upgrade

The overlay upgrade only works with the Tomcat application server. All certified JasperReports Server databases are supported. You can perform the overlay upgrade whether or not you have local customizations.

1. Stop the Tomcat application server
2. Your database should be running
3. Run the following commands:

cd <overlay-folder>

overlay install

 

     You are prompted to specify a path to a working folder:

You can accept the default value or specify an alternate location

Press enter to accept the default “../overlayWorkspace

     You are prompted to back up your jasperserver database:

You can back up your database now if you have not already done so

Choose “y” for yes to continue

     You are prompted to shutdown your Tomcat instance:

You can stop Tomcat now if you have not already done so

Choose “y” for yes to continue

     You are prompted to specify a path to your master.properties file:

For a 4.0 instance it might be similar to:

C:\Jaspersoft\jasperreports-server-4.0\buildomatic\default_master.properties

/opt/jasperreports-server-4.0/buildomatic/default_master.properties

Enter the full path and file name for your default_master.properties file

     For final verification, the overlay prompts you for the path to your application server:

If you haven’t moved it, it will be located at path to: <tomcat>

Press enter to accept the default if it is correct

     The overlay will now begin making updates to your system:

Your jasperserver-pro war file will be automatically backed up

Potential customizations in your environment will be analyzed

You are prompted to review the report on customizations if you choose to:

Choose “y” for yes to continue with the upgrade

The jasperserver database will be upgraded

The jasperserver-pro war file will be upgraded

The core data resources will be upgraded in the jasperserver repository database

     When the overlay execution has completed, start Tomcat, and Login to test the upgraded JasperReports Server

If execution was successful, you will see BUILD SUCCESSFUL on the command line

Rerun the Overlay Upgrade

If you exited out of the overlay install for any reason, you can resume execution without re-answering the prompted questions that you already answered. This execution behavior is the default when re-running the overlay.

You can re-run the overlay by simply running the same command:

overlay install

By default, under the covers, the overlay will run in a mode of: resumeMode=true

This means that any previous prompts you answered will be remembered.

If you would like to re-run the overlay “from scratch”, you can run the following command:

overlay install -DresumeMode=false

To see more information on the overlay options you can run:

overlay help

Rollback Procedure

In the case of an error with the overlay upgrade, use the following rollback procedure:

1. Stop Tomcat.
2. Run the following command:

overlay rollback

3. Specify the path to the working folder:

The default is “../overlayWorkspace

4. The tool will ask if you have rolled back your JasperReports Server database:

The default is no

It is required that you restore your database manually.

5. When the tool has finished, restore your database (see below), start Tomcat, and test JasperReports Server.

To restore your JasperReports Server Database:

1. Go to the directory location where you saved the backup of your jasperserver database

For example, C:\JS_40_BACKUP or /opt/JS_40_BACKUP.

2. Run the following commands for PostgreSQL:

cd /opt/JS_40_BACKUP

pg_restore --username=postgres  jasperserver  <  js-db-40-dump.sql

Starting and Logging into JasperReports Server 5.6

Start your application server. Your database should already be running.

Clearing Your Browser Cache

Before you log in, make sure you and your end-users clear the browser cache. JavaScript files, which enable UI elements of JasperReports Server, are typically cached by the browser. Clear the cache to ensure that the newer files are used.

If the UI for JasperReports Server looks broken or incorrect, it is often because of needing to clear the browser cache.

Logging into JasperReports Server

Log in using the following URL, user IDs, and passwords:

URL: http://localhost:8080/jasperserver-pro

User ID

Password

Description

superuser <your-password>

System-wide administrator

jasperadmin <your-password>

Administrator for the default organization

Your JasperReports Server instance has now been upgraded to 5.6.1. In the event of startup or login problems, refer to the Troubleshooting appendix of the JasperReports Server Installation Guide.

Additional Tasks to Complete the Upgrade

For additional information about optional steps after the main upgrade steps are complete, see Additional Tasks to Complete the Upgrade.

Clearing the Application Server Temp Folder

JasperReports Server uses caching to speed operations within the application. In the application server, caching files are created and stored for this caching functionality. Typically, these cached files are stored in a temp folder. Clear this temp folder to avoid any conflicts after the upgrade is complete. For Apache Tomcat the temp folder is <tomcat>/temp. (In general, the temp folder used by an Application Server corresponds to the path pointed at by the java.io.tmpdir Java system property.)

To clear the temp folder in Apache Tomcat:

1. Change directory to <tomcat>/temp
2. Delete all the files and folders in this directory.

Running Overlay Upgrade a Second Time

If you run the overlay upgrade a second time, the overlay logic will ask if you want to resume the last run of the overlay, so that your previous answers to questions are remembered and reused.

The overlay procedure will ask:

“We have detected that overlay install was already run. Do you want to resume last run? Default is 'y' ([y], n):”

Choose “y” for yes if you do not want to change any information previously given to the overlay

Choose “n” for no if you would like to enter new or different information

One reason for entering “n” for no would be if you did not give a valid path to your default_master.properties the first time you executed the overlay.

Version: 
Feedback
randomness