Upgrading from 8.2.x to 9.0.0

This chapter describes the recommended procedure for upgrading to JasperReports Server 9.0.0 from version 8.2.x. The examples show you how to upgrade using the js-upgrade shell script.

This chapter contains the following sections:

Upgrade Steps Overview

These are the general steps used in this section:

If your current instance of JasperReports Server has modifications or extensions, monitor these and reintegrate them into your 9.0.0 instance after upgrading.

Upgrading with Customizations

If your current instance of JasperReports Server has modifications or extensions, keep track of these and re-integrate them into your 9.0.0 instance after upgrading. See Planning Your Upgrade to determine if any customizations you've made to your existing version of JasperReports Server are affected by changes to the updated version.

Back Up Your JasperReports Server Instance

First back up your JasperReports Server WAR file and Jasperserver database so you can restore them if necessary. Perform these steps from the command line in a Windows or Linux shell.

This backup example is for Tomcat with the PostgreSQL or MySQL database. For other databases, consult your DB administration documentation for backup information.

Back up your JasperReports Server War File

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

Back up your Jasperserver Database

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

     cd <path>/JS_BACKUP
     pg_dump --username=postgres  jasperserver  >  js-db-dump.sql

   • MySQL

     cd <path>/JS_BACKUP

     Operating System	Command
     Windows:	mysqldump --user=root --password=<password> jasperserver > js-db-dump.sql
     Linux:	mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver > js-db-dump.sql

     For MySQL, If you receive an error about packet size, see the Troubleshooting appendix of the JasperReports Server Installation Guide.

Back up your JasperReports Server Keystore

Preparing the JasperReports Server 9.0.0 WAR File Distribution

Use the buildomatic js-upgrade scripts included in the 9.0.0 WAR file distribution ZIP release package to carry out the upgrade. The WAR file distribution comes in a compressed ZIP file named js-jrs_9.0.0_bin.zip.

Follow these steps to obtain and unpack the WAR file distribution ZIP file:

After you unpack the WAR File Distribution, the resulting location will be known as:

<js-install-9.0.0>

Configuring Buildomatic for Your Database and Application Server

This upgrade procedure uses the js-upgrade-samedb shell script.

This section shows example configurations for the PostgreSQL, MySQL, and Oracle databases. Other databases are similar.

Example Buildomatic Configuration

The default_master.properties file handles the upgrade configuration. We provide a sample configuration file for each database. You must specify your database credentials and application server location, and rename the file to default_master.properties.

appServerType=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=postgres
dbPassword=postgres
dbHost=localhost

For the Split upgrade, configure the settings in the default_master.properties file as described in Additional Buildomatic Configuration for Split Installation Upgrade.

MySQL Example

To configure default_master.properties for MySQL:

appServerType=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=root
dbPassword=password
dbHost=localhost									

For the Split upgrade, configure the settings in the default_master.properties file as described in Additional Buildomatic Configuration for Split Installation Upgrade.

appServerType=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=jasperserver
dbPassword=password
sysUsername=system
sysPassword=password
dbHost=localhost

Upgrading to JasperReports Server 9.0.0

Now that your buildomatic scripts are configured, you can complete the upgrade.

If you are prompted to create a keystore, this means that the server's original keystore was not found in the user's home directory. Proceed with caution:

For the Split upgrade, after the upgrade is done, to transfer the data (Audit, Access, and Log monitoring data) to the audit database from the Jasperserver database, run the following command:

The data is transferred to the audit database and the tables are deleted from the Jasperserver database. Rerun the command if there is any interruption in the data transfer process, it resumes the transfer process from where it was interrupted in the previous run.

js-upgrade Test Mode

Use the test option to run the js-upgrade script in test mode. For example, on Windows, enter:

cd <js-install-9.0.0>/buildomatic

js-upgrade-samedb.bat test

In test mode, the js-upgrade scripts check your default_master.properties settings and validate your application server location and its ability to connect to your database. Test mode can help you debug issues like an incorrect database password without altering your system.

Output Log Location

The js-upgrade script creates an output log that captures both standard and error output. If problems occur during script execution, or you just want to remember which options you chose, open the output log file located here:

<js-install-9.0.0>/buildomatic/logs/js-upgrade-<date>-<number>.log

Errors

If you encounter errors running the js-upgrade script, first look at the output log to see if you can spot the errors. For help, refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. The information in this appendix applies to both js-upgrade scripts and js-install scripts.

If you need to modify values in your default_master.properties file, you can simply edit the file. When you run the js‑upgrade script again, it uses the new values.

Starting and Logging into JasperReports Server 9.0.0

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 the UI elements of JasperReports Server, are typically cached by the browser. Clear the cache to ensure that the newer files are used.

Logging into JasperReports Server

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

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

superuser

<your-password>

jasperadmin

<your-password>

Your JasperReports Server instance has now been upgraded to 9.0.0. If you have startup or login problems, refer to the Troubleshooting appendix of the JasperReports Server Installation Guide.

Additional Tasks to Complete the Upgrade

Perform these tasks with the application server shutdown.

Handling JasperReports Server Customizations

If you made modifications to the original JasperReports Server application, you need to copy manually configuration changes, like client-specific security classes or LDAP server configurations, from your previous environment and integrate them with your upgraded environment. These configurations are typically found in the files at the WEB-INF/ location, for example, applicationContext-*.xml, *.properties, *.js, *.jar, and so on.

Clearing the Application Server Work Folder

Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored. When you update the WAR file or license, the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory, but it is a good practice to double-check. A permission problem, or some other problem, could prevent the clearing of the work folder.

To clear the work folder in Tomcat

Clearing the Application Server Temp Folder

JasperReports Server uses caching to speed operations within the application. Caching files are created and stored in the application server, usually in a temp folder. Clear this temp folder to avoid any post-upgrade conflicts. Typically, the temp folder used by an application server corresponds to the path referenced by the java.io.tmpdir Java system property. For Apache Tomcat the temp folder is <tomcat>/temp.

To clear the temp folder in Apache Tomcat

Clearing the Repository Cache Database Table

In the Jasperserver database, compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime. Because the JasperReports Library JAR is typically updated with each new release, old cached items can get out of date and cause errors at runtime. If you encounter errors that mention a JasperReports Library "local class incompatible", check your repository cache table. In summary, you can clear your Jasperserver database cache table as part of this upgrade process whether there are errors or not.

To clear the repository cache database table manually, run a SQL command similar to the one shown below:

update JIRepositoryCache set item_reference = null;
delete from JIRepositoryCache;