Upgrading from 8.0.x - 8.1.x to 9.0.0
This chapter describes the recommended procedure for upgrading from the latest version of JasperReports Server 8.0 through 8.1.x to JasperReports Server 9.0.0. If you are upgrading from version 8.2.x to 9.0.0, we recommend the procedure in Upgrading from 8.2.x to 9.0.0.
If you are upgrading from an earlier version of JasperReports Server, you need to go through an intermediate version before upgrading to 9.0.0. See Upgrading JasperReports Server 6.4.x or Earlier] for more information.
This upgrade procedure uses the JasperReports Server WAR File Distribution ZIP release package and the included buildomatic scripts. Our examples are for upgrading from version 8.0.x.
This chapter contains the following sections:
• | Upgrade Steps Overview |
• | Upgrading with Customizations |
• | Back Up Your JasperReports Server Instance |
• | Exporting Current Repository Data |
• | Preparing the JasperReports Server 9.0.0 WAR File Distribution |
• | Configuring Buildomatic for Your Database and Application Server |
• | Upgrading to JasperReports Server 9.0.0 |
• | Starting and Logging into JasperReports Server 9.0.0 |
• | 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. |
2. | Back up your current JasperReports Server instance. |
3. | Export your existing repository data. For example, export your 8.0.x data. |
4. | Download and set up the new 9.0.0 JasperReports Server WAR file distribution zip. |
5. | Run the js-upgrade script as described in Upgrading to JasperReports Server 9.0.0. |
Upgrading with Customizations
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
- Create a folder where you can save your
jasperserver
war file, for example-pro C:\JS_BACKUP
or/opt/JS_BACKUP
. - Copy
<tomcat>/webapps/jasperserver
to-pro <path>/JS_BACKUP
.
Back up your Jasperserver Database
- Procedure
- Create a folder (if you did not do so in the step above) where you can save your
Jasperserver
database, for exampleC:\JS_BACKUP
or/opt/JS_BACKUP
. - 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.sqlFor MySQL, If you receive an error about packet size, see the Troubleshooting appendix of the JasperReports Server Installation Guide.
- PostgreSQL
Back up your JasperReports Server Keystore
1. | Create a folder (if you did not do so already) where you can save your server's keystore, for example C:\JS_BACKUP or /opt/JS_BACKUP . |
2. | As the user who originally installed the server, copy $HOME/.jrsks and $HOME/.jrsksp to <path>/JS_BACKUP . Remember that these files contain sensitive keys for your data, so they must always be transmitted and stored securely. |
Exporting Current Repository Data
To export using the js-export.bat/.sh
script, navigate to the buildomatic folder, for example, <js‑install‑8.0.x>/buildomatic
. If you are using the PostgreSQL database, 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.
Run the following commands:
1. | Navigate to the buildomatic directory: |
cd <js-install-8.0>/buildomatic
2. | Run the js-export script: |
Operating System | Command |
---|---|
Windows: |
js-export.bat --everything --output-zip js-8.0-export.zip |
Linux: |
./js-export.sh --everything --output-zip js-8.0-export.zip |
|
Note the location of the export file so that you can use it during the 9.0.0 upgrade process. |
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:
1. |
Download the WAR file distribution from |
2. | Extract all files from js-jrs_9.0.0_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, 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-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 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
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
.
PostgreSQL Example
To configure default_master.properties
for PostgreSQL:
1. | Locate the postgresql_master.properties sample configuration file. |
Database |
Master Properties File |
PostgreSQL |
<js-install-9.0.0>/buildomatic/sample_conf/postgresql_master.properties |
2. | Copy the file to <js-install-9.0.0>/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=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=postgres
dbPassword=postgres
dbHost=localhost
|
default_master.properties
file as described in Additional Buildomatic Configuration for Split Installation Upgrade.
MySQL Example
To configure default_master.properties
for MySQL:
1. | Locate the mysql_master.properties sample configuration file: |
Database |
Master Properties File |
MySQL |
<js-install-9.0.0>/buildomatic/sample_conf/mysql_master.properties |
2. | Copy the file to <js-install-9.0.0>/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=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=root
dbPassword=password
dbHost=localhost
|
default_master.properties
file as described in Additional Buildomatic Configuration for Split Installation Upgrade.
Oracle Example
To configure default_master.properties
for Oracle:
1. | Locate the oracle_master.properties sample configuration file: |
Database |
Master Properties File |
Oracle |
<js-install-9.0.0>/buildomatic/sample_conf/oracle_master.properties |
2. | Copy the file to <js-install-9.0.0>/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=tomcat (or wildfly, etc.)
appServerDir=c:\\Apache Software Foundation\\Tomcat 9.0 (for example)
dbUsername=jasperserver
dbPassword=password
sysUsername=system
sysPassword=password
dbHost=localhost
|
default_master.properties
file as described in Additional Buildomatic Configuration for Split Installation Upgrade.
Using Vendor's Drivers for Commercial Databases
JasperReports Server doesn't include JDBC drivers for the following commercial databases: Oracle, SQL Server, or DB2. If you want to use one of those databases, you need to obtain one of the available JDBC drivers and copy it into the correct location, and then edit default_master.properties before running the upgrade steps. See Working With JDBC Drivers for more information.
Upgrading to JasperReports Server 9.0.0
Now that your buildomatic scripts are configured, you can complete the upgrade.
|
Make sure you have taken backup of your Make sure you have taken backup of your old JasperReports Server WAR file before proceeding. |
1. | Stop your application server. |
2. | Start your database server. |
3. | Make sure that the user running the upgrade commands is the same user that installed the server. |
4. | Run the following commands: |
Commands |
Description |
|
Change to buildomatic directory |
|
(Windows) Upgrade jasperserver |
|
(Linux) Upgrade jasperserver |
|
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. |
|
If the upgrade is Split, the Access, Audit, and Monitoring events are imported to the |
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:
• | In general, it is recommended to exit the upgrade procedure and make sure that the keystore is in the proper location, then rerun the upgrade. |
• | If you continue and create a keystore, then the upgrade proceeds but your repository is corrupted and users are unable to log in. In this case, you need to export manually the server's repository with a custom key, then import the key before importing the repository, as described in Encryption Keys. |
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-newdb.bat test <path>/js-8.0.x-export.zip
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
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 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
|
Installing JasperReports Server automatically generates encryption keys that reside on the file system. These keys are stored in a dedicated Jaspersoft keystore. Make sure that this keystore is properly secured and backed up, as described in the JasperReports Server Security Guide. |
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 filedeploy-webapp-
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
1. | Change the 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, usually in a temp
folder. Clear this temp
folder to avoid any post-upgrade conflicts. 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
1. | Change the 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. 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;
Old Manual Upgrade Steps
This section describes the older, manual upgrade steps used before we implemented the js-upgrade
shell scripts in release 4.0. They are provided here mainly as a reference for internal use.
We recommend using the js-upgrade shell scripts described in the beginning of this chapter instead of these manual commands.
Commands |
Description |
|
|
|
Deletes and recreates your |
|
|
Windows:
Linux and Mac OSX:
|
The
On Windows, you must use double quotation marks ( Note: "import-upgrade" imports the resources from the 8.0.x instance in a "non-update" mode (so that core resources from 9.0.0 stay unchanged). Additionally, the "update-core-users" option is applied so that the superuser and jasperadmin users have the same password as set in the 8.0.x instance. |
|
(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. |
|
Deletes the existing older war file, deploys the new war file. |
Recommended Comments
There are no comments to display.