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 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:Jaspersoftjasperreports-server-4.0buildomaticdefault_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 |
| System-wide administrator | ||
| 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.
Recommended Comments
There are no comments to display.