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

    This chapter describes the recommended procedure for upgrading from the latest version of JasperReports Server 6.0 through 6.3.x to JasperReports Server 7.1. If you're upgrading from version 6.4.x to 7.1, we recommend the procedure in Upgrading from 6.4 to 7.1.

    If you are upgrading from an earlier version of JasperReports Server, you need to go through an intermediate version before upgrading to 7.1. See Upgrading JasperReports Server 5.6.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 6.3.

    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 7.1 WAR File Distribution
    Configuring Buildomatic for Your Database and Application Server
    Upgrading to JasperReports Server 7.1
    Starting and Logging into JasperReports Server 7.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.
    2. Back up your current JasperReports Server instance.
    3. Export your existing repository data. For example, export your 6.3 data.
    4. Download and set up the new 7.1 JasperReports Server WAR file distribution zip.
    5. Run the js-upgrade script as described in Upgrading to JasperReports Server 7.1.

    Upgrading with Customizations

    If your current instance of JasperReports Server has modifications or extensions, keep track of these and re-integrate them into your 7.1 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:

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

    cd <path>/JS_BACKUP

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

         MySQL

    cd <path>/JS_BACKUP

    Windows:

    Linux:

    note-icon-ns_28x28.png.caa63112e7340e5844fe9e04933307e8.png

    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. Use the JasperReports Server export utility to export using:

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

    Exporting from the UI

    In JasperReports Server version 5.0, we added import-export functionality to the UI. Administrators who log in with the superuser account can export all repository data to a file on their machine.

    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.

    warning-icon-ns_28x28.png.6165cbe1c1b3a50a9e1ddcd0ae267b73.png

    Warning: Export from the UI in Release 5.1 has a bug. So, it's 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.

    To export your 6.3 repository data from the UI do the following:

    1. Start a web browser on your server (so you can save to the server’s hard disk).
    1. Log into JasperReports Server using the superuser account.
    2. Navigate to the Export tab page: Manage > Server Settings > Export.
    3. Click the Export button to accept the default values
    4. When you're 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'll need to upload it to the server where you're 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 use buildomatic to export your repository data. For example, to export 6.3 repository data, use the following commands:

    1. Navigate to the buildomatic directory:

    cd <js-install-6.3>/buildomatic

    2. Run buildomatic with the export target:

    Windows:

    js-ant.bat export-everything -DexportFile=js-6.3-export.zip[/code]                    

    Linux:

    ./js-ant export-everything -DexportFile=js-6.3-export.zip[/code]                    

    note-icon-ns_28x28.png.90a30ba549cc89a01c97ba4ae3ef7ed2.png

    Note the location of this export file so that you can use it during the 7.1 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‑6.3>/buildomatic. If you're using the PostgreSQL database the js-export script should already be configured to run. If you're using a different database, or you've 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-6.3>/buildomatic

    2. Run the js-export script:

    Windows:

    js-export.bat --everything --output-zip js-6.3-export.zip[/code]                    

    Linux:

    js-export.sh --everything --output-zip js-6.3-export.zip[/code]                    

    note-icon-ns_28x28.png.f6b6c6bf6262fc9b96992a1b6e663e72.png

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

    Preparing the JasperReports Server 7.1 WAR File Distribution

    Use the buildomatic js-upgrade scripts included in the 7.1 WAR file distribution ZIP release package to carry out the upgrade. The WAR file distribution comes in a compressed ZIP file named TIB_js-jrs_7.1.0_bin.zip.

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

    1. Download the WAR file distribution from (http://support.tibco.com) or contact your sales representative.
    2. Extract all files from TIB_js-jrs_7.1.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-7.1>

    Configuring Buildomatic for Your Database and Application Server

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

    note-icon-ns_28x28.png.eb81e05bdb47e16289a82f59efe9518f.png

    For Unix, the bash shell is required for the js-upgrade scripts. If you're 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 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-7.1>/buildomatic/sample_conf/postgresql_master.properties

    2. Copy the file to <js-install-7.1>/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, glassfish, etc.)appServerDir=c:Apache Software FoundationTomcat 8.0.43 (for example)dbUsername=postgresdbPassword=postgresdbHost=localhost[/code]                    

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

    2. Copy the file to <js-install-7.1>/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, glassfish, etc.)appServerDir=c:Apache Software FoundationTomcat 8.0.43 (for example)dbUsername=rootdbPassword=passworddbHost=localhost[/code]                    

    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-7.1>/buildomatic/sample_conf/oracle_master.properties

    2. Copy the file to <js-install-7.1>/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, glassfish, etc.)appServerDir=c:Apache Software FoundationTomcat 8.0.43 (for example)dbUsername=jasperserverdbPassword=passwordsysUsername=systemsysPassword=passworddbHost=localhost[/code]                        

    Using Vendor's Drivers for Commercial Databases

    JasperReports Server versions 5.6.1 and later include 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. See Working With JDBC Drivers for more information.

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

    If your application server is JBoss 7, your database is Oracle, SQL Server, or DB2 — and you're not using the TIBCO JDBC driver — you'll need to make an explicit reference to your JDBC driver so JBoss 7 will know its exact file name.

    1. First update your default_master.properties file to specify the exact name (artifactId and version) of your JDBC driver. To do this:
    a. Edit: <js-install-7.1>/buildomatic/default_master.properties
    b. Look for the section "Setup JDBC Driver", then uncomment and edit these two lines:

    # maven.jdbc.artifactId=ojdbc5

    # maven.jdbc.version=11.2.0

    So they look like this:

    maven.jdbc.artifactId=ojdbc5

    maven.jdbc.version=11.2.0

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

    c. Uncomment the line:

    jdbcDriverMaker=native

    2. Edit your jboss-deployment-structure.xml file so that it specifies the JDBC filename:
    a. Edit: <js-install-7.1>/buildomatic/install_resources/jboss/jboss-deployment-structure.xml
    b. Look for the section "Setup JDBC Driver"
    c. 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 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 7.1

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

    warning-icon-ns_28x28.png.9de0ead82e3be15ebc1bc4792eff6e4e.png

    Make sure you've backed up your jasperserver database before proceeding.

    Make sure you've 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-7.1>/buildomatic

    Change to buildomatic directory

    js-upgrade-newdb.bat <path>js-6.3-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-6.3-export.zip

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

    note-icon-ns_28x28.png.5744c3cfcb37c8180a1673a75802f0be.png

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

    note-icon-ns_28x28.png.b2eae93eab84e9b6fe92f8a341f6e47e.png

    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

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

    cd <js-install-7.1>/buildomatic

    js-upgrade-newdb.bat test <path>/js-6.3-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-7.1>/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 7.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

    System-wide administrator

    Administrator for the default organization

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

    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;

    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're 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

    cd <js-install-7.1>/buildomatic

     

    js-ant drop-js-db

    js-ant create-js-db

    js-ant init-js-db-pro

    Deletes and recreates 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-6.3-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 6.3 instance in a "non-update" mode (so that core resources from 7.1 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 6.3 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

    Deletes the existing older war file, deploys the new war file.

     


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...