Jump to content
JasperReports Library 7.0 is now available ×
  • This documentation is an older version of JasperReports Server Upgrade Guide - Community Edition. View the latest documentation.

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

    5.6 or 5.6.1

    to JasperReports Server 6.0.

    The examples describe how to use the js-upgrade shell scripts to carry out the upgrade operation.

    This chapter contains the following sections:

    Upgrade Steps Overview
    Back Up Your JasperReports Server Instance
    Preparing the JasperReports Server 6.0 WAR File Distribution
    Configuring Buildomatic for Your Database and Application Server
    Upgrading to JasperReports Server 6.0
    Starting and Logging into JasperReports Server 6.0
    Additional Tasks to Complete the Upgrade
    Old Manual Upgrade Steps: 5.6 to 6.0

    Upgrade Steps Overview

    These are the general steps used in this section:

    1. Back up your current JasperReports Server instance.
    2. Download and set up the new 6.0 JasperReports Server WAR file distribution zip.
    3. Run the js-upgrade script as described in Upgrading to JasperReports Server 6.0.

    If your current instance of JasperReports Server has any custom modifications or extensions, keep track of these and re-integrate them into your 6.0 instance after 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 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 war file. For example, C:JS_55_BACKUP or /opt/JS_55_BACKUP.
    2. Copy <tomcat>/webapps/jasperserver  to  <path>/JS_55_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 you jasperserver database, For example, C:JS_55_BACKUP or /opt/JS_55_BACKUP.
    2. Run the following commands for PostgreSQL or MySQL:
         PostgreSQL

    cd <path>/JS_55_BACKUP

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

         MySQL on Windows

    cd <path>/JS_55_BACKUP

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

         MySQL on Linux
                    cd <path>/JS_55_BACKUP                mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver > js-db-5.5-dump.sql[/code]        

    note-icon-ns_28x28.png.c47db9e5375735d0d9166164c664792e.png

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

    Preparing the JasperReports Server 6.0 WAR File Distribution

    Use the buildomatic js-upgrade scripts included in the 6.0 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-cp-6.0-bin.zip in the compressed ZIP format. Download the WAR file distribution from http://community.jaspersoft.com. .
    2. Extract all files from jasperreports-server-cp-6.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 Zip, the resulting location will be known as:

    <js-install-6.0>

    Configuring Buildomatic for Your Database and Application Server

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

    note-icon-ns_28x28.png.1474810fac5ab0c6050b54018a02f878.png

    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 and MySQL databases.

    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-6.0>/buildomatic/sample_conf/postgresql_master.properties

    2. Copy the file to <js-install-6.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

    PostgreSQL

    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.5>/buildomatic/sample_conf/mysql_master.properties

    2. Copy the file to <js-install-6.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

    MySQL

    Upgrading to JasperReports Server 6.0

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

    warning-icon-ns_28x28.png.3dd94fb01f67795bd4f1c79110e99ca9.png

    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-6.0>/buildomatic

     

    js-upgrade-samedb-ce.bat

    (Windows) Upgrade jasperserver war file, upgrade jasperserver database to 6.0, add 6.0 repository resources into the database

    ./js-upgrade-samedb-ce.sh

    (Linux) Upgrade jasperserver war file, upgrade jasperserver database to 6.0, add 6.0 repository resources into the database

    js-upgrade Test

    You can run the js-upgrade scripts in test mode using the test option. For example, in Windows enter:

    cd <js-install-6.0>/buildomatic

    js-upgrade-samedb-ce.bat test

    In test mode, the js-upgrade scripts check your default_master.properties settings. The application server location is validated and the capability to connect to the specified database is validated. Using test mode can help debug issues, such as an incorrect database password. Your system is not 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-6.0>/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. Additionally, you should refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. The information in this appendix applies to both js-upgrade scripts and the js-install scripts.

    If you need to modify values in your default_master.properties file, you can simply edit the file. When the js-upgrade script is run again, the new values will be used.

    Starting and Logging into JasperReports Server 6.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

    Administrator for the default organization

    Your JasperReports Server instance has now been upgraded to 6.0. 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.

    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, the buildomatic deploy-webapp-ce 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. 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.

    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. In summary, 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: 5.6 to 6.0

    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:

    Commands

    Description

    cd <js-install-6.0>/buildomatic

     

    js-ant upgrade-5.6-6.0-ce

    Execute SQL script to upgrade database to 6.0.

    Executes script buildomatic/install_resources/sql/<dbType>/upgrade-<dbType>-5.6.0-6.0.0-ce.sql

    js-ant import-minimal-for-upgrade-ce

    Loads themes and other core resources for 6.0.

    Note: "import-minimal-for-upgrade" will import core resources in an "update" mode so that the older 5.6 core resources will be overwritten. Additionally, the "skip-user-update" option will be applied so that jasperadmin users will not have their passwords modified.

    js-ant import-sample-data-upgrade-ce

    (Optional) This step is optional. Loads the 6.0 sample data.

    js-ant deploy-webapp-ce

    Delete old 5.6 war file, deploy the 6.0 war file.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...