Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server Upgrade Guide. View the latest documentation.

    This chapter describes the overlay process for upgrading to JasperReports Server 7.9.0 and contains the following sections:

    Introduction to the Overlay Upgrade
    Upgrade Steps Overview
    Plan Your Upgrade
    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 7.9
    Additional Tasks to Complete the Upgrade
    Running Overlay Upgrade a Second Time

    Introduction to the Overlay Upgrade

    The overlay upgrade procedure is currently available only for the JasperReports Server Commercial edition installed with the WAR file and only with the Apache Tomcat application server.

    warning-icon-ns.png.e81dd39f4b178904145bb4366a52917c.png

    The overlay upgrade supports only the Apache Tomcat application server.
    The overlay upgrade supports only JasperReports Server installations using the WAR file. The binary installer is not supported.
    The overlay upgrade is not possible if you configured custom encryption keys in your previous server.
    Only the certified repository databases are supported.

    The overlay upgrade supports upgrading from JasperReports Server versions 7.1 and later to JasperReports Server 7.9.

    Although the overlay upgrade does offer a rollback feature, you should always back up your database and application before upgrading.

    note-icon-ns_28x28.png.313bd7189934d9869dde35c2c2f389a7.png

    This section uses a 7.1 to 7.9 upgrade as an example.

    Upgrade Steps Overview

    These are the general steps used in this section:

    1. Plan your upgrade.
    2. Back up your current JasperReports Server instance.

    (The overlay tool will automatically back up your war file and ask if you've backed up your database.)

    3. Download and unpack the new JasperReports Server overlay upgrade 7.9 package zip file.
    4. Run the upgrade steps.

    The overlay upgrade procedure will help you to identify any modifications or extensions you've made to your JasperReports Server instance.

    note-icon-ns_28x28.png.747658486560cf3411ca50a78ba8eedc.png

    It's always best practice to back up your application and database before upgrading.

    Plan Your Upgrade

    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.

    Back up your JasperReports Server War File:

    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:

    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:
         PostgreSQL

    cd <path>/JS_BACKUP

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

    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.

    Unpack the Overlay Upgrade Package

    The overlay upgrade package comes in a file named: TIB_js-jrs_7.9.0_overlay.zip.

    1. Download the overlay upgrade package from TIBCO Jaspersoft Technical Support (http://support.tibco.com) or contact your sales representative.
    2. Extract all files from TIB_js-jrs_7.9.0_overlay.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.

    note-icon-ns.png.b07bc68e80233e31de26c37f022f6d18.png

    The overlay upgrade uses paths which exceed the 260-character limit on Windows. To extract the package, Enable NTFS long paths (Windows 10 only) or use a third-party file archiver such as 7-Zip.

    3. The overlay upgrade package unpacks into a folder named:

    overlay

    This document refers to this folder location as:

    <overlay-folder>

    Check for JDBC Driver (Oracle, SQL Server, DB2)

    JasperReports Server uses the TIBCO JDBC drivers for the Oracle, SQL Server, and DB2 commercial databases. If you want to use a different JDBC driver, you need to copy it to the correct location. If you use Oracle or DB2, you must also use your existing version of the db.template.properties file. See Working With JDBC Drivers for more information.

    Run the Overlay Upgrade

    The overlay upgrade works only with the Tomcat application server. It supports only the certified repository databases. You can perform the overlay upgrade whether or not you have local customizations.

    1. Stop the Tomcat application server.
    2. Make sure your database is running.
    3. Make sure that the user running the overlay commands is the same user that installed the server.
    4. Run the following commands:

    cd <overlay-folder>

    Windows: overlay install

    Linux: ./overlay install

         You're prompted to specify a path to a working folder:

    You can accept the default or specify an alternate folder

    Press enter to accept the default “../overlayWorkspace

         You are prompted to back up your jasperserver database. If you have already backed up your database, choose "y" to continue. If you have not yet backed up your database, choose "n" to exit the overlay and create a backup.
         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

         If you are prompted to create a new 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 overlay procedure and make sure the keystore is in the proper location, then rerun the overlay as described below.

    Alternatively, update the current location of the keystore in the keystore.init.properties file at the following locations:

    .../WEB-INF/classes/keystore.init.properties
    .../buildomatic/keystore.init.properties
    .../buildomatic/conf_source/iePro/keystore.init.properties

    If you continue and create a new keystore, then the overlay will proceed but your repository will be corrupted and users unable to login. In this case, you will need to manually export the server's repository with a custom key, then import the key before importing the repository, as described in Encryption Keys.

         You're prompted to specify a path to your master.properties file:

    For a 7.1 instance it might be similar to:

    C:Jaspersoftjasperreports-server-7.1buildomaticdefault_master.properties

    /opt/jasperreports-server-7.1/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's located in the path to: <tomcat>

    Press enter to accept the default if it's correct

         The overlay will begin updating your system:

    Your jasperserver-pro war file will be automatically backed up

    Potential customizations in your environment will be analyzed

    You're 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 upgrade has finished, start Tomcat, and log in to test the upgraded JasperReports Server.

    If upgrade was successful, you'll see BUILD SUCCESSFUL on the command line.

    Rerun the Overlay Upgrade

    If you exit the overlay install for any reason, you can re-run the overlay by simply running the same command:

    overlay install

    By default, the overlay runs in resume mode (resumeMode=true) This means your answers to previous prompts will be remembered.

    If you want to re-run the overlay “from scratch”, run the following command:

    overlay install -DresumeMode=false

    For more information on the overlay options run:

    overlay help

    Rollback Procedure

    If you encounter 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've rolled back your JasperReports Server database:

    The default is no

    note-icon-ns_28x28.png.247a6d056655293eeee223eb0f00576a.png

    You're required to manually restore your database .

    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_BACKUP or /opt/JS_BACKUP.

    2. Run the following commands for PostgreSQL:

    cd /opt/JS_BACKUP

    pg_restore --username=postgres  jasperserver  <  js-db-dump.sql

    To restore your JasperReports Server Keystore:

    1. Go to the directory location where you saved the backup of your JasperReports Server keystore.

    For example, C:JS_BACKUP or /opt/JS_BACKUP.

    2. Copy the .jrsks and .jrsksp files from the C:JS_BACKUP folder back to the $HOME folder, where they were originally backed up from.

    note-icon-ns.png.29c68ea8189bc00ba50d32edd28b0fe6.png

    If the backed up .jrsks and .jrsksp files are not copied from the C:JS_BACKUP folder back to the $HOME folder, JasperReports Server login page does not open and gives an error.

     

    Starting and Logging into JasperReports Server 7.9

    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

    System-wide administrator

    Administrator for the default organization

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

    Additional Tasks to Complete the Upgrade

    note-icon-ns_28x28.png.bb796136d893879db7bc64bd1b4aa086.png

    Installing JasperReports Server automatically generates encryption keys that reside on the file system. These keys are stored in a dedicated TIBCO TIBCO keystore. Make sure this keystore is properly secured and backed up, as described in the TIBCO JasperReports Server Security Guide.

    Perform these tasks with the application server shut down.

    Handling JasperReports Server Customizations

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

    You'll need to manually copy configuration changes, like client-specific security classes or LDAP server configurations, from your previous environment and integrate them with your 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, usually in a temp folder. Clear this temp folder to avoid any post-upgrade conflicts.

    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. 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 or not there are errors.

    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;

    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 file the first time you executed the overlay.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...