Upgrading from 3.7 - 5.2 to 5.6.1

This chapter describes the recommended procedure for upgrading from JasperReports Server:

3.7, 3.7.1, 4.0, 4.0.1, 4.1, 4.2, 4.2.1, 4.5, 4.5.1, 4.7, 4.7.1, 5.0, 5.1, or 5.2

to JasperReports Server 5.6.1.

The upgrade procedures described in this chapter use the JasperReports Server WAR File Distribution ZIP release package and the included buildomatic scripts.

The procedure in this chapter can also be used to upgrade JasperReports Server 5.5 or 5.6 to 5.6.1. However, we recommend you use the procedure in Upgrading from 5.5 or 5.6 to 5.6.1.

In this chapter the examples shown will use JasperReports Server 5.2 as the version being upgraded from.

This chapter contains the following sections:

Upgrade Steps Overview
Planning Your Upgrade
Back Up Your JasperReports Server Instance
Exporting Current Repository Data
Preparing the JasperReports Server 5.6.1 WAR File Distribution
Configuring Buildomatic for Your Database and Application Server
Upgrading to JasperReports Server 5.6.1
Starting and Logging into JasperReports Server 5.6.1
Additional Tasks to Complete the Upgrade
Old Manual Upgrade Steps

Upgrade Steps Overview

These are the general steps used in this section:

1. Plan your upgrade (specifically if upgrading from 4.7 or earlier).
2. Back up your current JasperReports Server instance.
3. Export your existing repository data. For example, export your 5.2 data.
4. Download and set up the new 5.6.1 JasperReports Server WAR file distribution zip.
5. Run the js-upgrade script as described in Upgrading to JasperReports Server 5.6.1.

If your current instance of JasperReports Server has any custom modifications or extensions, keep track of these and re-integrate them into your 5.6.1 instance after upgrading.

Planning Your Upgrade

If you are upgrading from JasperReports Server version 4.7 (or earlier), there is a planning chapter you should review in order to see if there are changes which will affect your deployment. This chapter can be found here: Planning Your Upgrade .

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 or MySQL database. For other databases, 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_52_BACKUP or /opt/JS_52_BACKUP.
2. Copy <tomcat>/webapps/jasperserver-pro  to  <path>/JS_52_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_52_BACKUP or /opt/JS_52_BACKUP.
2. Run the following commands for PostgreSQL or MySQL:
     PostgreSQL

cd <path>/JS_52_BACKUP

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

     MySQL

cd <path>/JS_52_BACKUP

Windows:

mysqldump --user=root --password=<password> jasperserver > js-db-5.2-dump.sql

Linux:

mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver ><br />js-db-5.2-dump.sql

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

Exporting Current Repository Data

You need to export your old repository data, for example your 5.2 repository data, using the JasperReports Server export utility. You can export in the following ways:

Use the JasperReports Server UI (since 5.0 release)
Use the buildomatic scripts (if you originally installed using buildomatic).
Use the js-export.bat/.sh script found in the <js-install>/buildomatic folder.

Exporting from the UI

As of JasperReports Server version 5.0, import-export functionality has been added to the User Interface. Administrators who login under the superuser account can export all repository data to a file on their machine. To export your 5.2 repository data from the UI do the following:

Warning: Export from the UI in Release 5.1 has a bug. So, it is best to export from the command line if upgrading from 5.1. If you do export from the UI with 5.1, you can unpack the resulting export.zip file, edit the index.xml file and change the string “5.0.0 CE” to 5.1.0 PRO”. See the JasperReports Server Administrator Guide for details.

1. Start a web browser on your server system (so that you can save to the server’s hard disk)
1. Login to JasperReports Server using the superuser account
2. Navigate to the Export tab page: Manage > Server Settings > Export tab
3. Click the Export button to accept the default values

Important: If you have a very large amount of repository data, it might be better to run export from the command line instead of from the UI.

4. When you are prompted to save the file, save to a location on the hard disk.

Remember that the export.zip file will need to be accessible from the command line where you run the upgrade commands. So, if you save the zip locally you will need to upload it to the server where you are running the upgrade commands.

Using Buildomatic Scripts to Export Data

If you configured buildomatic and your default_master.properties file for export as described in the JasperReports Server Administrator Guide, you can export your repository data. For example, to export 5.2 repository data, use the following commands:

1. Navigate to the buildomatic directory:

cd <js-install-5.2>/buildomatic

2. Run buildomatic with the export target:

Windows:

js-ant.bat export-everything -DexportFile=js-5.2-export.zip

Linux:

./js-ant export-everything -DexportFile=js-5.2-export.zip

Note the location of this export file so that you can use it during the 5.6 upgrade process.

Using the js-export Script to Export Data

To use the js-export.bat/.sh script, navigate to the buildomatic folder, for example, <js‑install‑5.2>/buildomatic. If you are using the PostgreSQL database then the js-export script should already be configured to run. If you are using a different database, or you have changed database passwords, you may need to update the js‑export configuration.

The import-export utility for JasperServer 3.7 needs additional configuration. For complete information on the standard import-export options refer to the JasperReports Server Administrator Guide.

Run the following commands:

1. Navigate to the buildomatic directory:

cd <js-install-5.2>/buildomatic

2. Run the js-export script:

Windows:

js-export.bat --everything --output-zip js-5.2-export.zip

Linux:

js-export.sh --everything --output-zip js-5.2-export.zip

Note the location of this export file so that you can use it during the 5.6.1 upgrade process.

Preparing the JasperReports Server 5.6.1 WAR File Distribution

Use the buildomatic js-upgrade scripts included in the 5.6 WAR file distribution ZIP release package to carry out the upgrade. Follow these steps to obtain and unpack the WAR file distribution ZIP file:

1. The WAR file distribution comes in a file named jasperreports-server-5.6-bin.zip in the compressed ZIP format. Download the WAR file distribution from Jaspersoft technical support (http://support.jaspersoft.com) or contact your sales representative.
2. Extract all files from jasperreports-server-5.6-bin.zip. Choose a destination, such as a C:\Jaspersoft folder on Windows, /home/<user> on Linux, or /Users/<user> on Mac.

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

<js-install-5.6>

Configuring Buildomatic for Your Database and Application Server

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

For Unix, the bash shell is required for the js-upgrade scripts. If you are installing to a non-Linux Unix platform such as HP-UX, IBM AIX, FreeBSD or Solaris, you need to download and install the bash shell. See the Troubleshooting appendix of the JasperReports Server Installation Guide for more information.

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

Example Buildomatic Configuration

The upgrade configuration is handled by the default_master.properties file. Jaspersoft provides a sample configuration file for each database. You must specify your database credentials and your application server location, and rename the file to default_master.properties.

PostgreSQL Example

This example shows how to configure default_master.properties for PostgreSQL.

1. Locate the postgresql_master.properties sample configuration file:

Database

Master Properties File

PostgreSQL

<js-install-5.6>/buildomatic/sample_conf/postgresql_master.properties

2. Copy the file to <js-install-5.6>/buildomatic
3. Rename the file default_master.properties
4. Edit default_master.properties for your database and application server:

Database

Sample Property Values

PostgreSQL

appServerType=tomcat6 [tomcat7, tomcat5, jboss, glassfish2, glassfish3]
appServerDir=c:\\Apache Software Foundation\\Tomcat 6
dbUsername=postgres
dbPassword=postgres
dbHost=localhost

MySQL Example

This example shows how to configure default_master.properties for MySQL.

1. Locate the mysql_master.properties sample configuration file:

Database

Master Properties File

MySQL

<js-install-5.6>/buildomatic/sample_conf/mysql_master.properties

2. Copy the file to <js-install-5.6>/buildomatic
3. Rename the file default_master.properties
4. Edit default_master.properties for your database and application server:

Database

Sample Property Values

MySQL

appServerType=tomcat6 [tomcat7, tomcat5, jboss, glassfish2, glassfish3]
appServerDir=C:\\Apache Software Foundation\\Tomcat 6
dbUsername=root
dbPassword=password
dbHost=localhost

Oracle Example

This example shows how to configure default_master.properties for Oracle.

1. Locate the oracle_master.properties sample configuration file:

Database

Master Properties File

Oracle

<js-install-5.6>/buildomatic/sample_conf/oracle_master.properties

2. Copy the file to <js-install-5.6>/buildomatic
3. Rename the file to default_master.properties
4. Edit default_master.properties for your database and application server:

Database

Sample Property Values

Oracle

appServerType=tomcat6 [tomcat7, tomcat6, jboss, glassfish2, glassfish3]
appServerDir=c:\\Apache Software Foundation\\Tomcat-6 (for example)
dbUsername=jasperserver
dbPassword=password
sysUsername=system
sysPassword=password
dbHost=localhost
5. As of 5.6.1, JasperReports Server includes 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 and edit default_master.properties before running the upgrade steps.

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

<js-install-5.6>/buildomatic/conf_source/db/oracle/jdbc

For SQL Server or DB2, the driver would get copied to the following locations respectively:

<js-install-5.6>/buildomatic/conf_source/db/sqlserver/jdbc

<js-install-5.6>/buildomatic/conf_source/db/db2/jdbc

Once you have copied the driver, in your default_master.properties file, go to the Setup Standard JDBC Driver section and edit it according to the instructions in that section.

Additional Step when Using JBoss 7 (and Oracle, SQL Server, or DB2)

If you are using JBoss 7 as your application server and Oracle, SQL Server, or DB2 as your database, and you are using a driver other than the TIBCO JDBC driver, there is an additional set of required steps to handle the JDBC driver.

You will need to make an explicit reference to your JDBC driver file name so that JBoss 7 will know the exact file name.

1. First update your default_master.properties file to specify the exact name (artifactId and version) of your JDBC driver:

Edit: <js-install-5.6>/buildomatic/default_master.properties

Look for the section "Setup JDBC Driver"

Uncomment and edit the two lines shown below:

# maven.jdbc.artifactId=ojdbc5

# maven.jdbc.version=11.2.0

So that they look like this:

maven.jdbc.artifactId=ojdbc5

maven.jdbc.version=11.2.0

(This will work for a driver with the filename: ojdbc5-11.2.0.jar)

2. Edit your jboss-deployment-structure.xml file so that the JDBC filename is specified:

Edit: <js-install-5.6>/buildomatic/install_resources/jboss/jboss-deployment-structure.xml

Look for the section "Setup JDBC Driver"

Uncomment and edit the line for your database type (for instance):

<!-- <resource-root path="WEB-INF/lib/ojdbc5-11.2.0.jar" use-physical-code-source="true"/> -->

So that it looks like this:

<resource-root path="WEB-INF/lib/ojdbc5-11.2.0.jar" use-physical-code-source="true"/>

(This will work for a driver with the filename: ojdbc5-11.2.0.jar)

Upgrading to JasperReports Server 5.6.1

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

Make sure you have backed up your jasperserver database before proceeding.

Make sure you have backed up your old JasperReports Server WAR file before proceeding.

1. Stop your application server
2. Start your database server
3. Run the following commands:

Commands

Description

cd <js-install-5.6>/buildomatic

Change to buildomatic directory

js-upgrade-newdb.bat <path>\js-5.2-export.zip

(Windows) Upgrade jasperserver-pro war file, drop and recreate the database, import data file from previous version.

./js-upgrade-newdb.sh <path>/js-5.2-export.zip

(Linux) Upgrade jasperserver-pro war file, drop and recreate the database, import data file from previous version.

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

If you have auditing enabled, see the section about including audit events in the Troubleshooting appendix of the JasperReports Server Installation Guide.

js-upgrade Test Mode

You can run the js-upgrade script in test mode using the test option. For example, on Window, enter:

cd <js-install-5.6>/buildomatic

js-upgrade-newdb.bat test <path>/js-5.2-export.zip

In test mode, the js-upgrade scripts check your default_master.properties settings. The application server location and the capability to connect to the specified database are validated. Using test mode can help debug issues such as an incorrect database password. Your system will not be altered when executing the script in test mode.

Output Log Location

The js-upgrade script creates an output log that captures standard output and error output. If there are any problems during the execution of the script, or if you want to remember which options you chose, you can open the output log file.

The output log file is located here:

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

Errors

If you encounter errors during the js-upgrade script execution, first look at the output log to see if you can spot any errors. Also, refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. The information in this appendix applies to js-upgrade scripts as well as 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, the new values are used.

Starting and Logging into JasperReports Server 5.6.1

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

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

The tasks described below should be done when the application server is shutdown.

Handling JasperReports Server Customizations

If you made modifications or customizations to the original JasperReports Server application, JasperReports Server 5.2 for example, these configurations are typically found in the WEB-INF/applicationContext-*.xml set of files.

Configuration modifications, such as client-specific security classes or LDAP server configurations, need to be hand-copied from your previous environment and re-integrated into the upgraded environment.

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’s 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:

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

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 to support this functionality. Typically, these cached files are stored in a temp folder. Clear this temp folder to avoid any conflicts after the upgrade is complete. Typically, the temp folder used by an application server corresponds to the path pointed at 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:

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

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. In some cases, you may encounter errors running reports after an upgrade. Because the JasperReports Library JAR is typically updated with each new JasperReports Server release, old cached items can get out of date and thus cause errors at runtime. If you encounter errors that mention a JasperReports Library “local class incompatible,” check your repository cache table. You can clear your jasperserver database cache table whether there are errors or not as part of this upgrade process.

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

update JIRepositoryCache set item_reference = null;

delete from JIRepositoryCache;

Old Manual Upgrade Steps

This section has the older, manual upgrade steps that were in place before the js-upgrade shell scripts were implemented in the 4.0 release. These are provided in the following table as a reference, mainly for internal use. The js‑upgrade shell scripts execute these buildomatic targets “behind the scenes.” Jaspersoft recommends using the js-upgrade scripts described in the beginning of this upgrade chapter instead of these manual steps.

Older buildomatic upgrade steps for this chapter are the following (using a 5.2 upgrade as an example):

Commands

Description

cd <js-install-5.6>/buildomatic

js-ant drop-js-db

js-ant create-js-db

js-ant init-js-db-pro

This will delete and recreate your jasperserver db. Make sure your original database is backed up.

js-ant import-minimal-pro

js-ant import-upgrade

-DimportFile="<path-and-filename>"

The -DimportFile should point to the <path> and <filename> of the js-5.2-export.zip file you created earlier.

On Windows, you must use double quotation marks (“) if your path or filename contains spaces. On Linux, you must use double quotation marks, escaped with a backslash (\”) in this case.

Note: "import-upgrade" will import resources from the 5.2 instance in a "non-update" mode (so that core resources from 5.6 will stay unchanged). Additionally, the "update-core-users" option will be applied so that the superuser and jasperadmin users will have the same password as set in the 5.2 instance.

js-ant import-sample-data-upgrade-pro

(Optional) This step is optional; it loads the new sample data. The old sample data is overwritten, so you may need to redo certain changes such as configuring the sample data sources for your database.

js-ant deploy-webapp-pro

Delete the existing older war file, deploy the new war file.

Version: 
Feedback