JasperReports Server Upgrade Guide

TIBCO JASPERREPORTS® SERVERUPGRADE GUIDE RELEASE 6.1 http://www.jaspersoft.com Copyright ©2005-2015, TIBCO Software Inc. All rights reserved. Printed in the U.S.A. TIBCO, the TIBCO logo, TIBCO Jaspersoft, the TIBCO Jaspersoft logo, TIBCO Jaspersoft iReport Designer, TIBCO JasperReports Library, TIBCO JasperReports Server, TIBCO Jaspersoft OLAP, TIBCO Jaspersoft Studio, and TIBCO Jaspersoft ETL are trademarks and/or registered trademarks of TIBCO Software Inc. in the United States and in jurisdictions throughout the world. All other company and product names are or may be trade names or trademarks of their respective owners. This is version 0515-JSP61-04 of the JasperReports Server Upgrade Guide. TABLE OF CONTENTS Chapter 1 Introduction 1.1 JasperReports Server Upgrade Distributions 1.1.1 About Bundled Apache Ant Chapter 2 Overlay Upgrade 2.1 Introduction to the Overlay Upgrade 2.2 Upgrade Steps Overview 2.3 Plan Your Upgrade 2.4 Back Up Your JasperReports Server Instance 2.5 Unpack the Overlay Upgrade Package 2.6 Check for JDBC Driver (Oracle, SQL Server, DB2) 2.7 Run the Overlay Upgrade 2.8 Rerun the Overlay Upgrade 2.9 Rollback Procedure 2.10 Starting and Logging into JasperReports Server 6.1 2.10.1 Clearing Your Browser Cache 2.10.2 Logging into JasperReports Server 2.11 Additional Tasks to Complete the Upgrade 2.11.1 Handling JasperReports Server Customizations 2.11.2 Clearing the Application Server Work Folder 2.11.3 Clearing the Application Server Temp Folder 2.11.4 Clearing the Repository Cache Database Table 2.12 Running Overlay Upgrade a Second Time Chapter 3 Upgrading from 6.0 to 6.1 3.1 Upgrade Steps Overview 3.2 Upgrading with Customizations 3.3 Back Up Your JasperReports Server Instance 3.4 Preparing the JasperReports Server 6.1 WAR File Distribution 3.5 Configuring Buildomatic for Your Database and Application Server 3.5.1 Example Buildomatic Configuration 3.5.2 Additional Step when Using JBoss 7 (and Oracle, SQL Server, or DB2) 3.6 Upgrading to JasperReports Server 6.1 3.6.1 js-upgrade Test Mode TIBCO Software Inc. 7 8 8 11 11 12 12 12 12 13 14 14 15 15 15 15 16 16 16 16 16 17 19 19 19 20 20 20 21 22 23 24 3 1 Upgrade Steps Overview 4.2 Output Log Location 3.1 General Procedure 6.6. SQL Server.7.0 to 6.2 Upgrading with Customizations 4.6 Configuring Buildomatic for Your Database and Application Server 4. .5 or Earlier 5.7 Starting and Logging into JasperReports Server 6.9.6.9.6.4 Clearing the Repository Cache Database Table 4.3 Clearing the Application Server Temp Folder 3.1 Handling JasperReports Server Customizations 4.4.8.8.1 Chapter 4 Upgrading from 3.7.3 Clearing the Application Server Temp Folder 4.2 Using Buildomatic Scripts to Export Data 4. or DB2) 4.8.9.8.1 Example Buildomatic Configuration 4.8 Starting and Logging into JasperReports Server 6.10 Old Manual Upgrade Steps Chapter 5 Upgrading JasperServer 3.9.2.7.2 Backing Up Your JasperReports Server CP Instance 6.6.1 Upgrading from 3.8.3 Errors 4.2.1 Backing Up Your JasperReports Server CP WAR File 6.1 Clearing Your Browser Cache 3.1 Handling JasperReports Server Customizations 3.1 WAR File Distribution 4.2 Logging into JasperReports Server 3.4 Clearing the Repository Cache Database Table 3.JasperReports Server Upgrade Guide 3.9 Old Manual Upgrade Steps: 6.3 Using the js-export Script to Export Data 4.7 Upgrading to JasperReports Server 6.3 Errors 3.1 4.2 Logging into JasperReports Server 4.2 Clearing the Application Server Work Folder 4.5 or Earlier 5.2 Clearing the Application Server Work Folder 3.8 Additional Tasks to Complete the Upgrade 3.7.1 3.1 4.2 Backing Up Your JasperReports Server Database 4 24 24 24 24 24 25 25 25 25 26 26 27 27 27 28 28 28 29 29 30 30 30 32 33 33 34 34 34 34 34 34 35 35 35 35 36 37 37 37 39 39 40 40 40 TIBCO Software Inc.5.8.5 Preparing the JasperReports Server 6.1 js-upgrade Test Mode 4.1 4.3 Back Up Your JasperReports Server Instance 4.7.9 Additional Tasks to Complete the Upgrade 4.1 Clearing Your Browser Cache 4.4 Exporting Current Repository Data 4.2 Output Log Location 4.4.7 .6 to 6.2 Additional Step when Using JBoss 7 (and Oracle.1 Exporting from the UI 4.4.2 Best Practices for Upgrading on Windows Chapter 6 Upgrading from the Community Project 6. 6 That May Affect Your Upgrade A.5 Changes in 5.9 Additional Tasks to Complete the Upgrade 6.2.6.9.2 Logging into the Commercial Version of JasperReports Server 6.1 6.3 Clearing the Application Server Temp Folder 6.1 6.2 Migrating Customizations A.4 Preparing the JasperReports Server 6.1.0 That May Affect Your Upgrade A.2 Changes to OLAP Engine TIBCO Software Inc.1 Changes in 6.4 Changes in 5.1 That May Affect Your Upgrade A.6 Upgrading to the Commercial Version of JasperReports Server 6.3 Changes in 6.0. 40 41 41 41 42 43 43 44 44 44 45 45 45 45 47 48 48 51 51 52 53 60 60 60 60 61 61 61 5 .3 Changes to Security Classes in JasperReports Server 6.5.3 Exporting Your CP Repository Data 6.2 Changes to Domain Security Files A.1 Changes to Custom Data Sources A.2.1 Example Buildomatic Configuration 6.7.2 Clearing the Application Server Work Folder 6.5.1 That May Affect Your Upgrade A.5 Configuring Buildomatic for Your Database and Application Server 6.9.6.2.5.4 Clearing the Repository Cache Database Table Appendix A Planning Your Upgrade A.8 Re-Configuring XML/A Connections (Optional) 6.1 WAR File Distribution 6.7 Starting and Logging into JasperReports Server 6.1 Clearing Your Browser Cache 6.2 Changes in 6.9.7.1 Migrating External Authentication Sample Files A.1 That May Affect Your Upgrade A.1 A.3.1 6.1 Handling JasperReports Server Customizations 6.0.9.1 Removal of Commercial JDBC Drivers A.1 Changes to Themes A.3. JasperReports Server Upgrade Guide 6 TIBCO Software Inc. . providing robust static and interactive reporting. a repository. more complex reports can be created outside of the server. To find out what you're licensed to use. If you don’t see some of the options described in this section. web-based. You can access PDF and HTML versions of these guides online from the Documentation section of the Jaspersoft Community website. your license may prohibit you from using them. The heart of the TIBCO™ Jaspersoft® BI Suite is the server. You can either use TIBCO™ Jaspersoft® Studio or manually write JRXML code to create a report that can be run in the server. Interact with reports. Our Ultimate Guides document advanced features and configuration. data-rich Jaspersoft Dashboards that quickly convey business trends. They also include best practice recommendations and numerous examples. contact Jaspersoft. which provides the ability to: • • • • • Easily create new reports based on views designed in an intuitive.CHAPTER 1 INTRODUCTION TIBCO™ JasperReports® Server builds on TIBCO™ JasperReports® Library as a comprehensive family of Business Intelligence (BI) products. such as security. report server. administer. changing formatting. and drilling on data. Efficiently and securely manage many reports. or as part of an integrated end-to-end BI suite utilizing common metadata and provide shared services. and data analysis capabilities. or to upgrade your license. and use JasperReports Server. While the Ad Hoc Editor lets users create simple reports. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the JasperReports file structure. The server exposes comprehensive public interfaces enabling seamless integration with other applications and the capability to easily add custom functionality. Arrange reports and web content to create appealing. You can use the following sources of information to extend your knowledge of JasperReports Server: • • Our core documentation describes how to install. which runs on the server. including sorting. Jaspersoft offers TIBCO™ Jaspersoft® OLAP. 7 . TIBCO Software Inc. drag and drop Ad Hoc Editor. and scheduling. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server installation. For business intelligence users. You can also access PDF and HTML versions of these guides online from the Documentation section of the Jaspersoft Community website. These capabilities are available as either stand-alone products. entering parameters. Schedule reports for distribution through email and storage in the repository. This section describes functionality that can be restricted by the software license for JasperReports Server. JasperReports Server Upgrade Distributions 1. are documented online.4. Distribution Package Description Overlay Upgrade zip Available only with the Commercial version of JasperReports Server. auditing.1.1-bin. scheduling. and data integration users. Supports all certified application servers. The bundled Apache Ant includes an additional jar This jar (ant-contrib.1 or later is required. which is bundled with the Overlay Upgrade ZIP and the War File Distribution ZIP. Supports all certified repository databases.7 or later. flash charts. and a multi-organization architecture for hosting large BI deployments. Linux.0 or later. Supports Windows. and other platforms. and other platforms.jar) enables conditional logic in Ant. and JasperReports Server. business users.9. Supports upgrade and rollback of upgrade changes.1 JasperReports Server Upgrade Distributions The following distribution packages are available for JasperReports Server.jar to your <Ant_HOME>/lib folder. The Portal is available online from Professional Services section of our website. and covers topics for developers. File name is: jasperreports-server-overlay-6. system administrators. Mac. dashboards. Commercial editions provide additional features. Supports Windows. Mac. Each integrates the standard features such as security. JasperReports Server is a component of both a community project and commercial offerings. a web services interface. Linux. 8 TIBCO Software Inc. If you want to run your own version of Apache Ant. which are installed with JasperReports. including Ad Hoc charts. The Ant scripts used for upgrade come with Windows and Linux batch scripts pre-configured to use the bundled version of Apache Ant.8.JasperReports Server Upgrade Guide • • Our Online Learning Portal lets you learn at your own pace. Supports upgrade from version 4. Our free samples. Provides assistance with identifying customized files in your environment. Jaspersoft Studio.zip WAR File Distribution Zip Supports upgrade from version 3. Supports only the Apache Tomcat application server. and much more for running and sharing reports.zip 1. If you're running your own Ant you should copy the ant-contrib. . Supports all certified repository databases. File name is: jasperreports-server-6.1. version 1.1 About Bundled Apache Ant We recommend Apache Ant version 1. Domains. the Ant commands may not be compatible with all shells.Chapter 1  Introduction On Linux and Solaris. use the bash shell explicitly. If you get errors. TIBCO Software Inc. 9 . see the information on the bash shell in the Troubleshooting appendix of the JasperReports Server Installation Guide. For more information. JasperReports Server Upgrade Guide 10 TIBCO Software Inc. . 1 and contains the following sections: • • • • • • • • • • • • 2. TIBCO Software Inc. This section uses a 5. SQL Server. DB2) Run the Overlay Upgrade Rerun the Overlay Upgrade Rollback Procedure Starting and Logging into JasperReports Server 6. The overlay upgrade supports only JasperReports Server installations using the WAR file.1 upgrade as an example. All certified databases are supported. Although the overlay upgrade does offer a rollback feature. The binary installer is not supported.0 to 6. • • • The overlay upgrade supports only the Apache Tomcat application server.CHAPTER 2 OVERLAY UPGRADE This chapter describes the overlay process for upgrading to JasperReports Server 6. 11 .0 and later to JasperReports Server 6. you should always back up your database and application before upgrading.1 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.1. The overlay upgrade supports upgrading from JasperReports Server versions 4.1 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. 5 jasperserver > js-db-5. 4. (The overlay tool will automatically back up your war file and ask if you've backed up your database.jaspersoft. For example. Create a folder where you can save your jasperserver-pro war file. Back up your current JasperReports Server instance. Create a folder (if you did not do so in the step above) where you can save your jasperserver database. C:\JS_50_BACKUP or /opt/JS_50_BACKUP.sql Unpack the Overlay Upgrade Package The overlay upgrade package comes in a file named: jasperreports-server-overlay-6. Run the following commands for PostgreSQL: • PostgreSQL cd <path>/JS_50_BACKUP pg_dump --username=postgres 2. TIBCO Software Inc. 2.zip.1 package zip file.1-dump.) 3. 12 Download the overlay upgrade package from Jaspersoft technical support (http://support.” on page 47 to determine if any customizations you've made to your existing version of JasperReports Server are affected by changes to the updated version. 1. Copy <tomcat>/webapps/jasperserver-pro  to   <path>/JS_50_BACKUP Back up your jasperserver Database: 1. It's always best practice to back up your application and database before upgrading.2 Upgrade Steps Overview These are the general steps used in this section: 1.JasperReports Server Upgrade Guide 2. 2.06. 2. Download and unpack the new JasperReports Server overlay upgrade 6. . “Planning Your Upgrade .com) or contact your sales representative. For example. 2. Plan your upgrade.4 Back Up Your JasperReports Server Instance First back up your JasperReports Server WAR file and jasperserver database so you can restore them if necessary.3 Plan Your Upgrade See Appendix A. 2. C:\JS_50_BACKUP or /opt/JS_50_BACKUP. Back up your JasperReports Server War File: 1.1. The overlay upgrade procedure will help you to identify any modifications or extensions you've made to your JasperReports Server instance. Perform these steps from the command line in a Windows or Linux shell. Run the upgrade steps. TIBCO Software Inc. Make sure you back up the modified file. DB2) As of version 5.template. or /Users/<user>/JS_ OVERLAY on Mac. Open the default_master.6 3. Locate the line: maven.properties DB2 example: Copy the alternate JDBC jar to this location: <overlay-folder>/buildomatic/conf_source/db/db2/jdbc Copy your existing version of the db.1.jdbc.properties file of your existing installation to comment out the maven version: 1.template. you need to copy it to the correct location. 2. Extract all files from jasperreports-server-overlay-6.zip.version=1.6 and change it to: # maven.6 Check for JDBC Driver (Oracle. Oracle example: Copy the alternate JDBC jar to this location: <overlay-folder>/buildomatic/conf_source/db/oracle/jdbc Copy your existing version of the db.template.template. If you use Oracle or DB2.template.6.properties file to this location: <overlay-folder>/buildomatic/conf_source/db/db2/db.1.jdbc. 13 .properties. For MS SQL Server. 3. The overlay upgrade package unpacks into a folder named: overlay This document refers to this folder location as: <overlay-folder> 2. /home/<user>/JS_OVERLAY on Linux.properties file to this location: <overlay-folder>/buildomatic/conf_source/db/oracle/db. JasperReports Server uses the TIBCO JDBC drivers for the Oracle.properties of your existing installation in a text editor. comment out the maven version information in your existing copy of default_ master. SQL Server.Chapter 2  Overlay Upgrade 2. SQL Server.properties SQL Server example: Copy the alternate JDBC jar to this location: <overlay-folder>/buildomatic/conf_source/db/sqlserver/jdbc Modify the default_master. you must also use your existing version of the db. and DB2 commercial databases. Create or choose a destination folder. such as C:\JS_OVERLAY on Windows.version=1.properties file. If you want to use a different JDBC driver. 0/buildomatic/default_master.0 instance it might be similar to: C:\Jaspersoft\jasperreports-server-5. It supports all certified JasperReports Server databases.properties file • For final verification.JasperReports Server Upgrade Guide 2. You can perform the overlay upgrade whether or not you have local customizations. If you haven't yet: Choose “y” for yes to continue • 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 • You're prompted to specify a path to your master./overlayWorkspace” • You're are prompted to back up your jasperserver database.properties /opt/jasperreports-server-5. you can re-run the overlay by simply running the same command: overlay install By default. 14 TIBCO Software Inc.properties file: For a 5. 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. the overlay prompts you for the path to your application server: If you haven’t moved it. 1.8 Rerun the Overlay Upgrade If you exit the overlay install for any reason. If upgrade was successful. and log in to test the upgraded JasperReports Server. Make sure your database is running 3. Stop the Tomcat application server 2. Run the following commands: cd <overlay-folder> 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 “. the overlay runs in resume mode (resumeMode=true) This means your answers to previous prompts will be remembered.properties Enter the full path and file name for your default_master. you'll see BUILD SUCCESSFUL on the command line 2.. start Tomcat.0\buildomatic\default_master. .7 Run the Overlay Upgrade The overlay upgrade works only with the Tomcat application server. 10 Starting and Logging into JasperReports Server 6.9 Rollback Procedure If you encounter an error with the overlay upgrade. 15 .1 Clearing Your Browser Cache Before you log in.sql 2./overlayWorkspace 4.. Go to the directory location where you saved the backup of your jasperserver database For example.Chapter 2  Overlay Upgrade If you want to re-run the overlay “from scratch”. 2.2 Logging into JasperReports Server Log in using the following URL. 2. Clear the cache to ensure that the newer files are used. which enable the UI elements of JasperReports Server. 2. make sure you and your end users clear the browser cache. and test JasperReports Server. When the tool has finished. user IDs. Specify the path to the working folder: The default is . Run the following command: overlay rollback 3. 5. JavaScript files.10. The tool will ask if you've rolled back your JasperReports Server database: The default is no You're required to manually restore your database . C:\JS_50_BACKUP or /opt/JS_50_BACKUP. To restore your JasperReports Server Database: 1. restore your database (see below). run the following command: overlay install -DresumeMode=false For more information on the overlay options run: overlay help 2. start Tomcat. and passwords: URL: http://localhost:8080/jasperserver-pro TIBCO Software Inc. 2. are typically cached by the browser. Your database should already be running. Stop Tomcat. Run the following commands for PostgreSQL: cd /opt/JS_50_BACKUP pg_restore --username=postgres jasperserver < js-db-50-dump.1 Start your application server.10. use the following rollback procedure: 1. Because the JasperReports Library JAR is 16 TIBCO Software Inc. could prevent the clearing of the work folder. 2. To clear the work folder in Tomcat: 1. 2. but it’s a good practice to double-check.1. Change directory to <tomcat>/work. If you have startup or login problems.11 Additional Tasks to Complete the Upgrade Perform these tasks with the application server shutdown. like client-specific security classes or LDAP server configurations.1 Handling JasperReports Server Customizations If you made modifications to the original JasperReports Server application.11.3 Delete all the files and folders in this directory. JasperReports Server 5. usually in a temp folder. from your previous environment and integrate them with your upgraded environment. . 2. You'll need to manually copy configuration changes.xml set of files. 2.4 Delete all the files and folders in this directory Clearing the Repository Cache Database Table In the jasperserver database.11. A permission problem.1 for example.JasperReports Server Upgrade Guide 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 6. When you update the WAR file or license. Clearing the Application Server Temp Folder JasperReports Server uses caching to speed operations within the application.2 Clearing the Application Server Work Folder Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored. To clear the temp folder in Apache Tomcat: 1. Caching files are created and stored in the application server. 2.11. 2. the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory.06. Clear this temp folder to avoid any post-upgrade conflicts. compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime. or some other problem.11. these configurations are typically found in the WEB-INF/applicationContext-*. refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. Change directory to <tomcat>/temp 2. so that your previous answers to questions are remembered and reused. 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. delete from JIRepositoryCache. TIBCO Software Inc. Do you want to resume last run? Default is 'y' ([y]. old cached items can get out of date and cause errors at runtime.12 Running Overlay Upgrade a Second Time If you run the overlay upgrade a second time. run a SQL command similar to one shown below: update JIRepositoryCache set item_reference = null. 17 . 2. If you encounter errors that mention a JasperReports Library “local class incompatible. The overlay procedure will ask: “We have detected that overlay install was already run.Chapter 2  Overlay Upgrade typically updated with each new release. To manually clear the repository cache database table.properties file the first time you executed the overlay. you can clear your jasperserver database cache table as part of this upgrade process whether or not there are errors.” check your repository cache table. In summary. the overlay logic will ask if you want to resume the last run of the overlay. JasperReports Server Upgrade Guide 18 TIBCO Software Inc. . keep track of these and reintegrate them into your 6.1.1 Upgrade Steps Overview Upgrading with Customizations Back Up Your JasperReports Server Instance Preparing the JasperReports Server 6. 3. Run the js-upgrade script as described in 3. TIBCO Software Inc.CHAPTER 3 UPGRADING FROM 6. Download and set up the new 6. 4.2 Upgrading with Customizations If your current instance of JasperReports Server has modifications or extensions. Back up your current JasperReports Server instance.” on page 47 to determine if any customizations you've made to your existing version of JasperReports Server are affected by changes to the updated version. keep track of these and reintegrate them into your 6.6.1 instance after upgrading. 19 .0 TO 6.1 Upgrade Steps Overview These are the general steps used in this section: 1.0. If your current instance of JasperReports Server has modifications or extensions.1. This chapter contains the following sections: • • • • • • • • • 3.1 WAR File Distribution Configuring Buildomatic for Your Database and Application Server Upgrading to JasperReports Server 6.1 This chapter describes the recommended procedure for upgrading to JasperReports Server 6.1 Additional Tasks to Complete the Upgrade Old Manual Upgrade Steps: 6.1 from versions 6. “Planning Your Upgrade .1 instance after upgrading.” on page 23.1 Starting and Logging into JasperReports Server 6. The examples show you how to upgrade using the js-upgrade shell scripts. Identify your customizations.0 or 6. See Appendix A. 3.0 to 6. “Upgrading to JasperReports Server 6. 2.1 JasperReports Server WAR file distribution zip. JasperReports Server Upgrade Guide 3.0. C:\JS_60_BACKUP or /opt/JS_60_BACKUP.1 WAR File Distribution Use the buildomatic js-upgrade scripts included in the 6. consult your DB administration documentation for backup information.1-dump.06.sql MySQL cd <path>/JS_60_BACKUP Windows: mysqldump --user=root --password=<password> jasperserver > js-db-6.4 Preparing the JasperReports Server 6. 2.sql For MySQL. 20 TIBCO Software Inc. Create a folder where you can save your jasperserver-pro war file.3 Back Up Your JasperReports Server Instance First back up your JasperReports Server WAR file and jasperserver database so you can restore them if necessary. Follow these steps to obtain and unpack the WAR file distribution ZIP file: 1.zip. Create a folder (if you did not do so in the step above) where you can save your jasperserver database.1> 3. For example. Extract all files from jasperreports-server-6.06. Run the following commands for PostgreSQL or MySQL: • PostgreSQL cd <path>/JS_60_BACKUP pg_dump --username=postgres • jasperserver > js-db-6. If you receive an error about packet size. Choose a destination. 2. The WAR file distribution comes in a compressed ZIP file named jasperreports-server6.1-dump. Copy <tomcat>/webapps/jasperserver-pro  to   <path>/JS_60_BACKUP Back up your jasperserver Database: 1. For other databases. Perform these steps from the command line in a Windows or Linux shell. see the Troubleshooting appendix of the JasperReports Server Installation Guide.1 jasperserver > js-db-6.0.1-bin.jaspersoft. such as a C:\Jaspersoft folder on Windows.zip. For example. or /Users/<user> on Mac.5 Configuring Buildomatic for Your Database and Application Server This upgrade procedure uses the js-upgrade-samedb shell script. 2.1-bin. Back up your JasperReports Server War File: 1. After you unpack the WAR File Distribution. . Download the WAR file distribution from Jaspersoft technical support (http://support. 3. C:\JS_60_BACKUP or /opt/JS_60_BACKUP.06.1-dump. the resulting location will be known as: <js-install-6. This backup example is for Tomcat with the PostgreSQL or MySQL database.com) or contact your sales representative.sql Linux: mysqldump --user=root --password=<password> --host=127. /home/<user> on Linux.1 WAR file distribution ZIP release package to carry out the upgrade. properties for MySQL: 1. you need to download and install the bash shell.properties for your database and application server: TIBCO Software Inc. jboss. If you're installing to a non-Linux Unix platform such as HP-UX. glassfish2. FreeBSD or Solaris. and rename the file to default_master.Chapter 3  Upgrading from 6. Locate the postgresql_master.0 to 6.5. Locate the mysql_master.1>/buildomatic 3.1 Example Buildomatic Configuration The default_master. and Oracle databases. 21 .properties for your database and application server: Database Sample Property Values PostgreSQL appServerType=tomcat6 [tomcat7. Copy the file to <js-install-6. You must specify your database credentials and application server location. MySQL. Rename the file default_master. See the Troubleshooting appendix of the JasperReports Server Installation Guide for more information.1>/buildomatic 3.properties file handles the upgrade configuration. 3.properties 4. 3.properties sample configuration file: Database Master Properties File MySQL <js-install-6.5.1>/buildomatic/sample_conf/postgresql_master.1.properties for PostgreSQL: 1. Other databases are similar. the bash shell is required for the js-upgrade scripts.1. IBM AIX. Edit default_master.properties.properties 2. Copy the file to <js-install-6. We provide a sample configuration file for each database.properties sample configuration file: Database Master Properties File PostgreSQL <js-install-6.1 PostgreSQL Example To configure default_master.2 MySQL Example To configure default_master. Rename the file default_master.5.1>/buildomatic/sample_conf/mysql_master.1 For Unix.properties 4. Edit default_master.properties 2. This section shows example configurations for the PostgreSQL. glassfish3] appServerDir=c:\\Apache Software Foundation\\Tomcat 6 dbUsername=postgres dbPassword=postgres dbHost=localhost 3. open your default_master.1>/buildomatic/conf_source/db/sqlserver/jdbc <js-install-6.1>/buildomatic/conf_source/db/oracle/jdbc For SQL Server or DB2. glassfish3] appServerDir=c:\\Apache Software Foundation\\Tomcat-6 (for example) dbUsername=jasperserver dbPassword=password sysUsername=system sysPassword=password dbHost=localhost 5. you should copy the driver to one of these locations respectively: <js-install-6.properties 2.6. for example. If you want to use a different JDBC driver. glassfish2.properties before running the upgrade steps.properties for your database and application server: Database Sample Property Values Oracle appServerType=tomcat6 [tomcat7. SQL Server.1>/buildomatic/conf_source/db/db2/jdbc Once you've copied the driver. you should copy the alternate JDBC jar to this location: <js-install-6. 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. SQL Server.properties 4. . jboss. JasperReports Server versions 5. or DB2.1. Locate the oracle_master. go to the Setup Standard JDBC Driver section and update it according to the instructions in that section.1 and later include the TIBCO JDBC drivers for the following commercial databases: Oracle. 22 TIBCO Software Inc. Rename the file to default_master. or DB2) If your application server is JBoss 7.properties sample configuration file: Database Master Properties File Oracle <js-install-6. you need to copy it to the correct location and edit default_master. your database is Oracle.5. tomcat6. glassfish2.2 Additional Step when Using JBoss 7 (and Oracle.1>/buildomatic/sample_conf/oracle_master.JasperReports Server Upgrade Guide Database Sample Property Values MySQL appServerType=tomcat6 [tomcat7. With Oracle.3 Oracle Example To configure default_master. jboss. 3.properties for Oracle: 1. Copy the file to <js-install-6. glassfish3] appServerDir=C:\\Apache Software Foundation\\Tomcat 6 dbUsername=root dbPassword=password dbHost=localhost 3. Edit default_master.5.1>/buildomatic 3.properties file in a text editor. SQL Server. jdbc.properties file to specify the exact name (artifactId and version) of your JDBC driver: Edit:  <js-install-6.2. Run the following commands: Commands Description cd <js-install-6.version=11.0 to 6.artifactId=ojdbc5 maven.bat TIBCO Software Inc.1>/buildomatic js-upgrade-samedb.2.1>/buildomatic/default_master.xml file so that it specifies the JDBC filename: Edit:  <js-install-6.1 Now that your buildomatic scripts are configured. Stop your application server 2.0 (This will work for a driver with the file name:  ojdbc5-11.0.jdbc.0 So they look like this: maven.version=11. Make sure you've backed up your jasperserver database before proceeding.jar" use-physical-codesource="true"/> --> So it looks like this: <resource-root path="WEB-INF/lib/ojdbc5-11. Start your database server 3. Edit your jboss-deployment-structure.Chapter 3  Upgrading from 6.<resource-root path="WEB-INF/lib/ojdbc5-11.1.2. add 6.0.1>/buildomatic/install_resources/jboss/jboss-deploymentstructure. First update your default_master.jar) 3.jar) 2.2.jdbc.0. you can complete the upgrade.2.properties Look for the section "Setup JDBC Driver" Uncomment and edit these two lines: # maven.6 Upgrading to JasperReports Server 6.jar" use-physical-codesource="true"/> (This will work for a driver with the filename:  ojdbc5-11.1 1. (Windows) Upgrade jasperserver-pro war file. 1.2.artifactId=ojdbc5 # maven.xml Look for the section "Setup JDBC Driver" Uncomment and edit the line for your database type (for instance): <!-.1 repository resources into the database 23 . upgrade jasperserver database to 6.jdbc.0. Make sure you've backed up your old JasperReports Server WAR file before proceeding. When you run the js-upgrade script again. . enter: cd <js-install-6.1 Clearing Your Browser Cache Before you log in.6. the js-upgrade scripts check your default_master.3 Errors If you encounter errors running the js-upgrade script.1.properties file. user IDs. refer to the Troubleshooting appendix of the JasperReports Server Installation Guide.log 3. For help.7. 3. If problems occur during script execution.1>/buildomatic/logs/js-upgrade-<date>-<number>. which enable the UI elements of JasperReports Server.JasperReports Server Upgrade Guide 3. upgrade jasperserver database to 6. 3. open the output log file located here: <js-install-6.1 Commands Description .1 repository resources into the database js-upgrade Test Mode Use the test option to run the js-upgrade script in test mode. and passwords: URL: http://localhost:8080/jasperserver-pro 24 TIBCO Software Inc. 3.7 Starting and Logging into JasperReports Server 6. first look at the output log to see if you can spot the errors. If you need to modify values in your default_master.2 Output Log Location The js-upgrade script creates an output log that captures both standard and error output.7. JavaScript files. Clear the cache to ensure that the newer files are used./js-upgrade-samedb. Test mode can help you debug issues like an incorrect database password without altering your system. are typically cached by the browser. add 6. Your database should already be running. you can simply edit the file.1>/buildomatic js-upgrade-samedb.sh (Linux) Upgrade jasperserver-pro war file.2 Logging into JasperReports Server Log in using the following URL. on Windows. make sure you and your end users clear the browser cache. For example.1 Start your application server. The information in this appendix applies to both js-upgrade scripts and js-install scripts.bat test In test mode.6. or you just want to remember which options you chose.6.properties settings and validate your application server location and its ability to connect to your database. it uses the new values. 3. xml set of files.Chapter 3  Upgrading from 6. the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory.1 for example. like client-specific security classes or LDAP server configurations. or some other problem. 3. You'll need to manually copy configuration changes. 2.1. If you have startup or login problems. Delete all the files and folders in this directory TIBCO Software Inc. but it’s a good practice to double-check. For Apache Tomcat the temp folder is <tomcat>/temp.tmpdir Java system property.io. could prevent the clearing of the work folder. 25 . these configurations are typically found in the WEB-INF/applicationContext-*.8 Additional Tasks to Complete the Upgrade Perform these tasks with the application server shutdown.8. JasperReports Server 6. Typically. usually in a temp folder.1 Handling JasperReports Server Customizations If you made modifications to the original JasperReports Server application. To clear the temp folder in Apache Tomcat: 1. 3. refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. To clear the work folder in Tomcat: 1.2 Clearing the Application Server Work Folder Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored.8. Clearing the Application Server Temp Folder JasperReports Server uses caching to speed operations within the application.8. Caching files are created and stored in the application server. Clear this temp folder to avoid any post-upgrade conflicts. from your previous environment and integrate them with your upgraded environment. Change directory to <tomcat>/work. Change directory to <tomcat>/temp 2. the temp folder used by an application server corresponds to the path referenced by the java.06. 3. A permission problem. When you update the WAR file or license.1 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 6. 3.0 to 6.3 Delete all the files and folders in this directory. 8.0pro.1. delete from JIRepositoryCache. old cached items can get out of date and cause errors at runtime.0-6. To manually clear the repository cache database table. compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime.1>/buildomatic js-ant upgrade-6. manual upgrade steps used before we implemented the js-upgrade shell scripts in release 4. In summary. TIBCO Software Inc. They're provided here mainly as a reference for internal use.1 sample data.0 to 6.4 Clearing the Repository Cache Database Table In the jasperserver database.0.sql js-ant import-minimal-for-upgrade-pro Load themes and other core resources for 6. .0 war file. 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-6. js-ant deploy-webapp-pro Delete old 6. Execute script buildomatic/install_ resources/sql/<dbType>/upgrade-<dbType>-6.” check your repository cache table.1.0-6.1. Note: "import-minimal-for-upgrade" will import core resources in an "update" mode so that the older 6.1 This section describes the older. deploy the 6.0 core resources will be overwritten.9 Old Manual Upgrade Steps: 6.1-pro Execute SQL script to upgrade database to 6. Additionally. If you encounter errors that mention a JasperReports Library “local class incompatible. you can clear your jasperserver database cache table as part of this upgrade process whether or not there are errors.JasperReports Server Upgrade Guide 3. 26 js-ant import-sample-data-upgrade-pro (Optional) Load the 6.1 war file.0. Because the JasperReports Library JAR is typically updated with each new release. the "skip-userupdate" option will be applied so that the superuser and jasperadmin users will not have their passwords modified. 3. run a SQL command similar to one shown below: update JIRepositoryCache set item_reference = null. 4. “Upgrading to JasperReports Server 6.1 instance after upgrading. For example.1 Starting and Logging into JasperReports Server 6. Run the js-upgrade script as described in 4. Our examples are for upgrading from version 5. Upgrading with Customizations If your current instance of JasperReports Server has modifications or extensions. Back up your current JasperReports Server instance.1 Upgrade Steps Overview Upgrading with Customizations Back Up Your JasperReports Server Instance Exporting Current Repository Data Preparing the JasperReports Server 6. Plan your upgrade. See Appendix A.1 WAR File Distribution Configuring Buildomatic for Your Database and Application Server Upgrading to JasperReports Server 6.2 1.6 data. keep track of these and reintegrate them into your 6. Download and set up the new 6. “Upgrading from 6.0 or 6.0 to 6.1. Export your existing repository data.CHAPTER 4 UPGRADING FROM 3.5.1 This chapter describes the recommended procedure for upgrading from JasperReports Server 3.6.” on page 19.1 JasperReports Server WAR file distribution zip.7 .6 TO 6. export your 5.0. 27 . This upgrade procedure uses the JasperReports Server WAR File Distribution ZIP release package and the included buildomatic scripts.1.1. we recommend the procedure in Chapter 3.1 Additional Tasks to Complete the Upgrade Old Manual Upgrade Steps Upgrade Steps Overview These are the general steps used in this section: 4.5 to JasperReports Server 6.7 through 5.” on page 33. If you're upgrading from version 6. “Planning Your Upgrade .7.” on TIBCO Software Inc. This chapter contains the following sections: • • • • • • • • • • 4. 3. 5.1.1 to 6. 2. bat/. consult your DB administration documentation for backup information. Create a folder where you can save your jasperserver-pro war file. 28 TIBCO Software Inc. This backup example is for Tomcat with the PostgreSQL or MySQL database.sql Linux: mysqldump --user=root --password=<password> --host=127.4 Exporting Current Repository Data You need to export your old repository data.1-dump. Copy <tomcat>/webapps/jasperserver-pro  to   <path>/JS_56_BACKUP Back up your jasperserver Database: 1.0. C:\JS_56_BACKUP or /opt/JS_56_BACKUP. .JasperReports Server Upgrade Guide page 47 to determine if any customizations you've made to your existing version of JasperReports Server are affected by changes to the updated version. For example.1 jasperserver > js-db-5.66.sql MySQL cd <path>/JS_56_BACKUP Windows: mysqldump --user=root --password=<password> jasperserver > js-db-5. Use the JasperReports Server export utility to export using: • • • 4.0 or later) the buildomatic scripts (if you originally installed using buildomatic).1 the JasperReports Server UI (version 5.66. see the Troubleshooting appendix of the JasperReports Server Installation Guide. If you receive an error about packet size. the js-export. For other databases. 2.1-dump. Exporting from the UI In JasperReports Server version 5. Create a folder (if you did not do so in the step above) where you can save your jasperserver database. Run the following commands for PostgreSQL or MySQL: • PostgreSQL cd <path>/JS_56_BACKUP pg_dump --username=postgres • jasperserver > js-db-5.sql For MySQL.3 Back Up Your JasperReports Server Instance First back up your JasperReports Server WAR file and jasperserver database so you can restore them if necessary. we added import-export functionality to the UI. 4. Back up your JasperReports Server War File: 1. C:\JS_56_BACKUP or /opt/JS_56_BACKUP. For example. 2. Administrators who log in with the superuser account can export all repository data to a file on their machine.sh script found in the <js-install>/buildomatic folder.1-dump.4. 4.66. Perform these steps from the command line in a Windows or Linux shell.0.0. 3 Using the js-export Script to Export Data To use the js-export.4.1 Important: If you have a very large amount of repository data. to export 5.0. use the following commands: 1. save to a location on the hard disk./js-ant export-everything -DexportFile=js-5. you can use buildomatic to export your repository data.7 .6 to 6.6-export. When you're prompted to save the file. 2.6 repository data from the UI do the following: 1. So.6-export. Warning: Export from the UI in Release 5. 29 .4. For complete information on the standard import-export options refer to the JasperReports Server Administrator Guide. 1.7 needs additional configuration. 4.6>/buildomatic.zip file will need to be accessible from the command line where you run the upgrade commands. To export your 5.5.zip Note the location of this export file so that you can use it during the 6.1. If you're using a different database. Navigate to the Export tab page: Manage > Server Settings > Export.zip file.1.xml file and change the string “5. <js-install-5. Navigate to the buildomatic directory: cd <js-install-5. if you save the zip locally you'll need to upload it to the server where you're running the upgrade commands.6 repository data.properties file for export as described in the JasperReports Server Administrator Guide. for example.bat/. If you're using the PostgreSQL database the js-export script should already be configured to run. Run the js-export script: TIBCO Software Inc. 3. Navigate to the buildomatic directory: cd <js-install-5. Start a web browser on your server (so you can save to the server’s hard disk). or you've changed database passwords.1 has a bug.6>/buildomatic 2. Run buildomatic with the export target: Windows: js-ant. Remember that the export. it might be better to run export from the command line instead of from the UI. So.2 Using Buildomatic Scripts to Export Data If you configured buildomatic and your default_master. See the JasperReports Server Administrator Guide for details. edit the index.0 PRO”.1. 4. Run the following commands: 1. The import-export utility for JasperServer 3. you can unpack the resulting export. navigate to the buildomatic folder.sh script.zip Linux: .6>/buildomatic 2. you may need to update the js-export configuration. If you do export from the UI with 5.bat export-everything -DexportFile=js-5.1 upgrade process.0 CE” to 5. For example. Click the Export button to accept the default values 4. Log into JasperReports Server using the superuser account.Chapter 4  Upgrading from 3. it's best to export from the command line if upgrading from 5. 30 Locate the postgresql_master.6-export.1 upgrade process.zip. After you unpack the WAR File Distribution. Extract all files from jasperreports-server-6.properties sample configuration file: Database Master Properties File PostgreSQL <js-install-6.properties for PostgreSQL: 1.1-bin.JasperReports Server Upgrade Guide Windows: js-export.com) or contact your sales representative.6. The WAR file distribution comes in a compressed ZIP file named jasperreports-server6.1>/buildomatic/sample_conf/postgresql_master.6. . This section shows example configurations for the PostgreSQL. 2.properties.1 WAR file distribution ZIP release package to carry out the upgrade. or /Users/<user> on Mac. 4.zip Linux: js-export. you need to download and install the bash shell.1 PostgreSQL Example To configure default_master.1 Example Buildomatic Configuration The default_master.sh --everything --output-zip js-5.1> 4. Download the WAR file distribution from Jaspersoft technical support (http://support.6 Configuring Buildomatic for Your Database and Application Server This upgrade procedure uses the js-upgrade-newdb shell script. IBM AIX. /home/<user> on Linux. 4. and Oracle databases. Other databases are similar. If you're installing to a non-Linux Unix platform such as HP-UX. MySQL. See the Troubleshooting appendix of the JasperReports Server Installation Guide for more information.1-bin.6-export. We provide a sample configuration file for each database.properties file handles the upgrade configuration.5 Preparing the JasperReports Server 6.zip. the bash shell is required for the js-upgrade scripts. such as a C:\Jaspersoft folder on Windows.bat --everything --output-zip js-5. You must specify your database credentials and application server location. the resulting location will be known as: <js-install-6. For Unix.1. Follow these steps to obtain and unpack the WAR file distribution ZIP file: 1.jaspersoft.properties TIBCO Software Inc.zip Note the location of this export file so that you can use it during the 6. 4.1 WAR File Distribution Use the buildomatic js-upgrade scripts included in the 6. Choose a destination. FreeBSD or Solaris. and rename the file to default_master. jboss. 31 . Locate the oracle_master.3 Oracle Example To configure default_master. Rename the file default_master.properties sample configuration file: Database Master Properties File Oracle <js-install-6.6 to 6.Chapter 4  Upgrading from 3. Copy the file to <js-install-6.properties for MySQL: 1.1>/buildomatic 3. glassfish2.properties sample configuration file: Database Master Properties File MySQL <js-install-6. glassfish3] appServerDir=C:\\Apache Software Foundation\\Tomcat 6 dbUsername=root dbPassword=password dbHost=localhost 4. Edit default_master. glassfish2.6.properties for Oracle: 1. Edit default_master.1. Copy the file to <js-install-6.properties for your database and application server: Database Sample Property Values MySQL appServerType=tomcat6 [tomcat7.7 .properties for your database and application server: Database Sample Property Values PostgreSQL appServerType=tomcat6 [tomcat7. Rename the file to default_master.5.2 MySQL Example To configure default_master.properties 4.1>/buildomatic 3.1 2. glassfish3] appServerDir=c:\\Apache Software Foundation\\Tomcat 6 dbUsername=postgres dbPassword=postgres dbHost=localhost 4.properties 4.properties 2. jboss.1>/buildomatic/sample_conf/oracle_master.1>/buildomatic 3.properties 4. Locate the mysql_master.1.properties for your database and application server: TIBCO Software Inc. Rename the file default_master.6.properties 2.1>/buildomatic/sample_conf/mysql_master. Copy the file to <js-install-6. Edit default_master. tomcat6.jar" use-physical-codesource="true"/> --> So it looks like this: 32 TIBCO Software Inc. you should copy the driver to one of these locations respectively: <js-install-6.0. or DB2) If your application server is JBoss 7.properties file in a text editor.xml Look for the section "Setup JDBC Driver" Uncomment and edit the line for your database type (for instance): <!-.xml file so that it specifies the JDBC filename: Edit:  <js-install-6.2.jar) 2. open your default_master.artifactId=ojdbc5 # maven. SQL Server. JasperReports Server versions 5.1>/buildomatic/default_master.artifactId=ojdbc5 maven.version=11.1>/buildomatic/conf_source/db/sqlserver/jdbc <js-install-6. or DB2. With Oracle. you should copy the alternate JDBC jar to this location: <js-install-6. 4.2. First update your default_master.6. 1.properties file to specify the exact name (artifactId and version) of your JDBC driver: Edit:  <js-install-6. jboss. Edit your jboss-deployment-structure.properties before running the upgrade steps.0 So they look like this: maven. you need to copy it to the correct location and edit default_master. .2.properties Look for the section "Setup JDBC Driver" Uncomment and edit these two lines: # maven. 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.2.2 Additional Step when Using JBoss 7 (and Oracle.6.1 and later include the TIBCO JDBC drivers for the following commercial databases: Oracle.version=11.jdbc.JasperReports Server Upgrade Guide Database Sample Property Values Oracle appServerType=tomcat6 [tomcat7. If you want to use a different JDBC driver.jdbc. glassfish3] appServerDir=c:\\Apache Software Foundation\\Tomcat-6 (for example) dbUsername=jasperserver dbPassword=password sysUsername=system sysPassword=password dbHost=localhost 5.1>/buildomatic/install_resources/jboss/jboss-deploymentstructure.0 (This will work for a driver with the file name:  ojdbc5-11.0.jdbc. your database is Oracle. SQL Server. go to the Setup Standard JDBC Driver section and update it according to the instructions in that section. SQL Server.1>/buildomatic/conf_source/db/db2/jdbc Once you've copied the driver. glassfish2. for example.1>/buildomatic/conf_source/db/oracle/jdbc For SQL Server or DB2.<resource-root path="WEB-INF/lib/ojdbc5-11.jdbc. 1. import data file from previous version. On MySQL.zip In test mode. Make sure you've backed up your jasperserver database before proceeding.5.6-export.1 <resource-root path="WEB-INF/lib/ojdbc5-11. Make sure you've backed up your old JasperReports Server WAR file before proceeding.properties settings and validate your application server location and its ability to connect to your database. Run the following commands: Commands Description cd <js-install-6. you can complete the upgrade.jar" use-physical-codesource="true"/> (This will work for a driver with the filename:  ojdbc5-11.6-export.bat <path>\js-5.Chapter 4  Upgrading from 3. 4.zip (Linux) Upgrade jasperserver-pro war file.1>/buildomatic js-upgrade-newdb.2. Stop your application server 2.7 Upgrading to JasperReports Server 6. Start your database server 3. see the Troubleshooting appendix of the JasperReports Server Installation Guide.6-export. the js-upgrade scripts check your default_master. drop and recreate the database.1>/buildomatic Change to buildomatic directory js-upgrade-newdb.0.bat test <path>/js-5. For example./js-upgrade-newdb.1 Now that your buildomatic scripts are configured. .6 to 6. If you have auditing enabled. see the section about including audit events in the Troubleshooting appendix of the JasperReports Server Installation Guide. TIBCO Software Inc.zip (Windows) Upgrade jasperserver-pro war file.2. import data file from previous version.7 . Test mode can help you debug issues like an incorrect database password without altering your system.0. enter: cd <js-install-6. drop and recreate the database. 33 . if you receive an error about packet size.jar) 4.7.sh <path>/js-5. on Windows.1 js-upgrade Test Mode Use the test option to run the js-upgrade script in test mode. 8. it uses the new values.1 Clearing Your Browser Cache Before you log in.1>/buildomatic/logs/js-upgrade-<date>-<number>. 4.1. make sure you and your end users clear the browser cache. you can simply edit the file.9 Additional Tasks to Complete the Upgrade Perform these tasks with the application server shutdown.8 Starting and Logging into JasperReports Server 6.7. Clear the cache to ensure that the newer files are used. are typically cached by the browser. refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. which enable the UI elements of JasperReports Server. For help. Your database should already be running.2 Logging into JasperReports Server Log in using the following URL. or you just want to remember which options you chose.8.JasperReports Server Upgrade Guide 4.1 Start your application server. 4. If you have startup or login problems.3 Errors If you encounter errors running the js-upgrade script. 4. If problems occur during script execution.log 4. JavaScript files.properties file.2 Output Log Location The js-upgrade script creates an output log that captures both standard and error output. 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. open the output log file located here: <js-install-6. 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 6. If you need to modify values in your default_master. 4. . 34 TIBCO Software Inc. first look at the output log to see if you can spot the errors.7. user IDs. When you run the js-upgrade script again. To clear the temp folder in Apache Tomcat: 1. TIBCO Software Inc. these configurations are typically found in the WEB-INF/applicationContext-*.9.tmpdir Java system property.3 Delete all the files and folders in this directory.” check your repository cache table.66. When you update the WAR file or license. 4. A permission problem. like client-specific security classes or LDAP server configurations.9. Change directory to <tomcat>/temp 2. If you encounter errors that mention a JasperReports Library “local class incompatible. 4.2 Clearing the Application Server Work Folder Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored. you can clear your jasperserver database cache table as part of this upgrade process whether or not there are errors. could prevent the clearing of the work folder. You'll need to manually copy configuration changes. Because the JasperReports Library JAR is typically updated with each new release. Clearing the Application Server Temp Folder JasperReports Server uses caching to speed operations within the application. delete from JIRepositoryCache.4 Delete all the files and folders in this directory Clearing the Repository Cache Database Table In the jasperserver database.9.1 for example.Chapter 4  Upgrading from 3. usually in a temp folder.7 .9. To clear the work folder in Tomcat: 1. JasperReports Server 5. compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime. For Apache Tomcat the temp folder is <tomcat>/temp.io. or some other problem. but it’s a good practice to double-check. run a SQL command similar to one shown below: update JIRepositoryCache set item_reference = null.xml set of files. the temp folder used by an application server corresponds to the path referenced by the java. Caching files are created and stored in the application server. 4. 2. the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory.1 4.5. from your previous environment and integrate them with your upgraded environment. In summary.1 Handling JasperReports Server Customizations If you made modifications to the original JasperReports Server application. Change directory to <tomcat>/work. Clear this temp folder to avoid any post-upgrade conflicts. 35 . To manually clear the repository cache database table. old cached items can get out of date and cause errors at runtime. Typically.6 to 6. you must use double quotation marks.6 instance. 36 js-ant import-sample-data-upgrade-pro (Optional) This step is optional.JasperReports Server Upgrade Guide 4. deploys the new war file. Make sure your original database is backed up. TIBCO Software Inc.zip file you created earlier. They're provided here mainly as a reference for internal use.6 instance in a "non-update" mode (so that core resources from 6. it loads the new sample data. .1 will stay unchanged). On Linux. Note: "import-upgrade" will import resources from the 5. 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-6. manual upgrade steps used before we implemented the js-upgrade shell scripts in release 4. the "updatecore-users" option will be applied so that the superuser and jasperadmin users will have the same password as set in the 5.10 Old Manual Upgrade Steps This section describes the older. so you may need to redo certain changes such as configuring the sample data sources for your database. js-ant init-js-db-pro 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. escaped with a backslash (\”) in this case. js-ant deploy-webapp-pro Deletes the existing older war file.6-export. The old sample data is overwritten. Additionally. you must use double quotation marks (“) if your path or filename contains spaces. On Windows.1>/buildomatic js-ant drop-js-db js-ant create-js-db Deletes and recreates your jasperserver db.0. Upgrade from version 3. if you take the default installation choices.7. This way you have more control over updating and upgrading components like the application server.7.1 UPGRADING JASPERSERVER 3. you have two options for installing jasperreports-serverJasperReports Server: a.5. Installing with the Binary Installer and Bundled Components The binary installer is an executable that puts all the components in place to run JasperReports Server.2 Best Practices for Upgrading on Windows The two methods for installing JasperReports Server are: 1. Use the War File ZIP distribution (file name: bin-<ver>. Upgrade from version 3.CHAPTER 5 5.5 to version 3.7 release.7 to version 6.5. But keep in mind that these components are specially configured to run a specific version of JasperReports Server.1. Once you put these components in place.1. Download the JasperServer 3. The Installation Guide is in the docs folder. If you're running a JasperServer version earlier than 3. 5.5 OR EARLIER Upgrading from 3. 2.7 WAR file distribution zip package to get the relevant files and documentation. Download the JasperServer 3. 37 . 2.5 or Earlier If you're running JasperServer version 3. you may want to install the main components before you install JasperReports Server. The steps for this upgrade are documented in the JasperServer Installation Guide for the 3. first upgrade to 3. your upgrade requires two steps: 1. you'll get the Apache Tomcat application server.zip) TIBCO Software Inc. then to 6.7 WAR file distribution zip package from Jaspersoft technical support or contact your sales representative. This applies to the Windows Start Menu items created to start and stop JasperReports Server. the PostgreSQL database and Java execution environment. database. and Java. For example. Installing to Pre-existing Components When installing a “Production” instance of JasperReports Server. b.JasperReports Server Upgrade Guide You'll install JasperReports Server to the existing components using the js-install. You'll create a default_master. .properties file that specifies the location of the application server and database components.bat scripts. If you intend to upgrade your Windows installation with future releases of JasperReports Server. 38 TIBCO Software Inc. we recommend installing to pre-existing components. This will reduce any post-upgrade confusion caused by the Windows Start Menu showing the older version of JasperReports Server.exe) The installer will prompt you for the location of the application server and database components. Use the Binary Installer (file name: jasperreports-server-<ver>-windows-<x86/64>-installer. CHAPTER 6 UPGRADING FROM THE COMMUNITY PROJECT If you're running a Community Project (CP) instance of JasperReports Server and want to upgrade to a commercial version of JasperReports Server, follow the instructions in this chapter. This upgrade process uses the JasperReports Server commercial WAR File Distribution release package and the included buildomatic scripts. This CP to commercial upgrade procedure is valid only for upgrade within a major JasperReports Server release, for example 6.0 CP to 6.0 commercial. This chapter contains the following sections: • • • • • • • • 6.1 General Procedure Backing Up Your JasperReports Server CP Instance Exporting Your CP Repository Data Preparing the JasperReports Server 6.1 WAR File Distribution Configuring Buildomatic for Your Database and Application Server Upgrading to the Commercial Version of JasperReports Server 6.1 Starting and Logging into JasperReports Server 6.1 Re-Configuring XML/A Connections (Optional) General Procedure The upgrade procedure consists of the following main steps: 1. Back up your JasperReports Server CP instance. 2. Export your CP repository data. 3. Upgrade your instance to JasperReports Server Commercial. 4. Import your CP repository data. If you customized or extended JasperReports Server CP, you need to keep track of these modifications and integrate them with your JasperReports Server commercial instance after completing the upgrade. TIBCO Software Inc. 39 JasperReports Server Upgrade Guide 6.2 Backing Up Your JasperReports Server CP Instance Backup the old JasperReports Server CP WAR file and jasperserver database in case a problem occurs with the upgrade. Perform these steps from the command line in a Windows or Linux shell. These instructions assume you have Tomcat application server and the PostgreSQL or MySQL database. Other application servers require a similar procedure. If you have another database, consult your DB administration documentation for back up information. 6.2.1 Backing Up Your JasperReports Server CP WAR File For example, for Apache Tomcat, back up the jasperserver directory from the <tomcat>/webapps folder: 1. Go to the <tomcat> directory. 2. Make a new directory named js-cp-war-backup. 3. Copy <tomcat>/webapps/ jasperserver to <tomcat>/js-cp-war-backup. 4. Delete the <tomcat>/webapps/jasperserver directory. 6.2.2 Backing Up Your JasperReports Server Database Go to the location where you originally unpacked your CP WAR file distribution zip. (Or create a new local folder to hold your backup file.) 1. Go to the <js-install-cp> directory. 2. Run one of the following commands: • For PostgreSQL on Windows or Linux: cd <js-install-cp> pg_dump --username=postgres • jasperserver > js-db-cp-dump.sql For MySQL on Windows: mysqldump --user=root --password=<password> jasperserver > js-db-cp-dump.sql For MySQL on Linux: mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver >jsdb-cp-dump.sql For MySQL, if you receive an error about packet size, see the Troubleshooting appendix of the JasperReports Server Installation Guide. 6.3 Exporting Your CP Repository Data Before exporting your CP repository data, check to see if you have the default_master.properties file in this directory. <js-install-cp>/buildomatic/default_master.properties This file holds settings specific to your JasperReports Server instance, such as your application server location and your database type and location. If you don't have this file, see 6.5.1, “Example Buildomatic Configuration ,” on page 41. 40 TIBCO Software Inc. Chapter 6  Upgrading from the Community Project To export your CP repository data: 1. Navigate to the buildomatic directory: cd <js-install-cp>/buildomatic 2. Run buildomatic with the export target: Windows: js-ant.bat export-everything-ce -DexportFile=js-cp-export.zip Linux: ./js-ant export-everything-ce -DexportFile=js-cp-export.zip This operation uses the export option --everything, which collects all your repository data. Remember the path to your exported file. You need to specify it when you import to your commercial JasperReports Server repository. 6.4 Preparing the JasperReports Server 6.1 WAR File Distribution Use the buildomatic scripts included in the commercial 6.1 WAR file distribution release package for the upgrade. Follow these steps to obtain and unpack the commercial 6.1 WAR file distribution ZIP file: 1. The WAR file distribution comes in a compressed ZIP file named jasperreports-server-6.1-bin.zip. Download the WAR file distribution from Jaspersoft technical support or contact your sales representative. 2. Extract all files from jasperreports-server-6.1-bin.zip. Choose a destination, such as C:\Jaspersoft on Windows, /home/<user> on Linux, or /Applications on Mac OSX. After you unpack the WAR File Distribution Zip, the resulting location is known as: <js-install-pro> 6.5 Configuring Buildomatic for Your Database and Application Server This upgrade procedure uses the buildomatic scripts included with the WAR File Distribution ZIP release package. 6.5.1 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 your application server location, and rename the file to default_master.properties. 6.5.1.1 PostgreSQL Example This example uses PostgreSQL (the same general logic applies to other databases). 1. Copy postgresql_master.properties from: 2. Paste the file to: 3. Rename the file to: default_master.properties 4. Edit default_master.properties for your database and application server. Sample property values are: <js-install-pro>/buildomatic/sample_conf <js-install-pro>/buildomatic appServerType=tomcat6 (or tomcat7, tomcat5, jboss, glassfish) appServerDir=c:\\Apache Software Foundation\\tomcat-6.0.26 (for example) TIBCO Software Inc. 41 2. tomcat5.26 (for example) dbUsername=root dbPassword=password dbHost=localhost 6. Make sure it's backed up. Start your database server. Adds superuser. jboss. Run the following commands: Commands Description cd <js-install-pro>/buildomatic js-ant drop-js-db js-ant create-js-db js-ant init-js-db-pro js-ant import-minimal-pro 42 The first command deletes your jasperserver db. Rename the file to: default_master.5. 1.properties 4.0. TIBCO Software Inc. and default tenant structure. Make sure you've backed up your old JasperReports Server WAR file before proceeding. Paste the file to: 3.properties from: 2.6 Upgrading to the Commercial Version of JasperReports Server 6.properties file. Stop your application server.properties for your database and application server. Themes. 3. glassfish) appServerDir=c:\\Apache Software Foundation\\tomcat-6.JasperReports Server Upgrade Guide dbUsername=postgres dbPassword=postgres dbHost=localhost 6. 1.1. . you can complete the upgrade. Make sure you've backed up your jasperserver database before proceeding. Sample property values are: <js-install-pro>/buildomatic/sample_conf <js-install-pro>/buildomatic appServerType=tomcat6 (or tomcat7. Copy mysql_master. The other commands recreate and initialize the database.2 MySQL Example This example uses MySQL (the same general logic applies to other databases). Edit default_master.1 After configuring the default_master. directories.zip file you created earlier. js-ant deploy-webapp-cp-to-pro Delete the CP war file.xml files that might exist in <tomcat>\conf\Catalina\localhost. you must use double quotation marks escaped with a backslash (\”) in this case. and deploy the commercial (pro) war file. 6. “Additional Tasks to Complete the Upgrade.7. (Optional) Move any existing <tomcat-install>\logs files into a backup directory to clean up old CP log data. see the Troubleshooting appendix of the JasperReports Server Installation Guide. 4.license file to the C:\Users\<user> directory (Windows 7 example) For information about how to set up the license. 2. 43 .1 Clearing Your Browser Cache Before you log in. JavaScript files. if you receive an error about packet size. see the JasperReports Server Installation Guide. are typically cached by the browser..7 Starting and Logging into JasperReports Server 6. Your database should already be running. Copy the <js-install-pro>/jasperserver. Now start your Tomcat. Set up the JasperReports Server License. On Linux.Chapter 6  Upgrading from the Community Project Commands Description js-ant import-upgrade -DimportFile=<path>/js-cpexport. JBoss.” on page 44. see 6. Delete any files in the <tomcat>\temp folder.9. or GlassFish application server. 6. make sure you and your end-users clear the Browser cache. Clear the cache to ensure that the newer files are used. On MySQL. TIBCO Software Inc. 3. On Windows.1 commercial sample data.zip -DimportArgs="--include-server-settings" The -DimportFile argument should point to the js-cp-export. 5. js-ant import-sample-data-upgrade-pro (Optional) Loads the 6. you must use double quotation marks (“) if your path or filename contains spaces. Delete any files. For instructions on clearing directories.1 Before starting the server: 1. or sub-directories in <tomcat>\work\Catalina\localhost. which enable UI elements of JasperReports Server. Delete any jasperserver*. 1 Log in using the following URL.2 Logging into the Commercial Version of JasperReports Server 6. refer to the Troubleshooting appendix of the JasperReports Server Installation Guide. . You need to update XML/A connection definitions to include the organization the user belongs to. Your JasperReports Server instance has now been upgraded from Community Project (CP) to commercial. Edit your XML/A connections as shown in the following examples: • User IDs Change “jasperadmin” to “jasperadmin|organization_1” Change “joeuser” to “joeuser|organization_1” • URI values Change: http://localhost:8080/jasperserver/xmla to http://localhost:8080/jasperserver-pro/xmla 6. You'll need to update this URI to the commercial instance. users belong to the default organization. 44 TIBCO Software Inc. Each user (except superuser) must belong to a specific organization. The XML/A connection also specifies an instance URI. For example.7. user IDs. 6. The default organization is organization_1. A commercial edition of JasperReports Server supports multi-tenancy. If startup or login problems occur.8 Re-Configuring XML/A Connections (Optional) XML/A connection definitions contain a username and password for connecting the Web Services to the server. which allows multiple organizations on a single instance.JasperReports Server Upgrade Guide 6. the jasperadmin password might be reset to jasperadmin. and passwords: URL: http://localhost:8080/jasperserver-pro User ID Password Description superuser superuser System-wide administrator jasperadmin jasperadmin Administrator for the default organization Your jasperadmin password might be reset to the default setting by the upgrade operation. After upgrading to the commercial JasperReports Server. you should change your jasperadmin and superuser passwords to non-default values.9 Additional Tasks to Complete the Upgrade Perform these tasks with the application server shutdown. For security reasons. 2. you can clear your jasperserver database cache table as part of this upgrade process whether or not there are errors.9.” check your repository cache table.3 Delete all the files and folders in this directory.io. Caching files are created and stored in the application server.1 Handling JasperReports Server Customizations If you made modifications to the original JasperReports Server application. To clear the work folder in Tomcat: 1. 45 . delete from JIRepositoryCache.9. When you update the WAR file or license. Change directory to <tomcat>/temp 2. could prevent the clearing of the work folder. You'll need to manually copy configuration changes. or some other problem.9. usually in a temp folder. like client-specific security classes or LDAP server configurations. old cached items can get out of date and cause errors at runtime.1 for example. Typically. Clearing the Application Server Temp Folder JasperReports Server uses caching to speed operations within the application. 6. Because the JasperReports Library JAR is typically updated with each new release. run a SQL command similar to one shown below: update JIRepositoryCache set item_reference = null. To manually clear the repository cache database table.Chapter 6  Upgrading from the Community Project 6. 6.05. the temp folder used by an application server corresponds to the path referenced by the java.4 Delete all the files and folders in this directory Clearing the Repository Cache Database Table In the jasperserver database. If you encounter errors that mention a JasperReports Library “local class incompatible. Change directory to <tomcat>/work. TIBCO Software Inc. but it’s a good practice to double-check.xml set of files. JasperReports Server 5. For Apache Tomcat the temp folder is <tomcat>/temp. compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime. In summary. 6. A permission problem. To clear the temp folder in Apache Tomcat: 1.66. Clear this temp folder to avoid any post-upgrade conflicts.9. the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory.2 Clearing the Application Server Work Folder Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored.06.tmpdir Java system property. from your previous environment and integrate them with your upgraded environment. these configurations are typically found in the WEB-INF/applicationContext-*. JasperReports Server Upgrade Guide 46 TIBCO Software Inc. . 6. including external authentication and customizations involving Spring Security. and 6.6.1.6. and 6.1 That May Affect Your Upgrade Changes in 6. so review all topics that affect you.0.1 affect commercial JDBC drivers.1 That May Affect Your Upgrade Changes in 6. you may be affected by changes in 5. For an overview of new features.0.6 affect commercial JDBC drivers as well as XML/A connections.1 can affect your deployment. Changes in 6. Changes are cumulative. The versions and their affected functionality are: • • • • • Changes in 6. and you should plan your upgrade accordingly. if you're upgrading from 5. 6. 6. see the JasperReports Server User Guide or the JasperReports Server Administrator Guide.0 affect custom data sources and security files for Domains.6 That May Affect Your Upgrade TIBCO Software Inc.1.0.6. 47 . Before upgrading make sure to: • • Review this information carefully and determine how the changes described affect your deployment. This section describes only those changes that can significantly impact your existing deployment. Back up your current JasperReports Server installation and repository.0.APPENDIX A PLANNING YOUR UPGRADE Some of the new and enhanced features in JasperReports Server 5. Changes in 5. Changes in 6.6 to 6. For information on how to use the new features.1 affect themes.0.0.6. This chapter contains the following sections: • • • • • Changes in 6.1 affect Spring Security. Changes in 5.0 That May Affect Your Upgrade Changes in 5. For example.1. improvements. and bug fixes see the release notes in the root directory of the distribution.1 That May Affect Your Upgrade Changes in 5. 1 Changes in 6. As a result of these modifications.1 Changes to Themes The look and feel of the JasperReports Server web interface has been redesigned to modernize the application's appearance.1 That May Affect Your Upgrade A. . footer.banner The bottom position needs to be adjusted only if the height of the footer is changed 48 TIBCO Software Inc. Instead of attempting to update an existing login page. For information on developing new themes. you should re-implement the login page in the new default theme.JasperReports Server Upgrade Guide A.css. body.css Default value: height: 32px containers.banner containers. see the JasperReports Server Administrator Guide and the JasperReports Server Ultimate Guide. The main changes are in the banner. To accomplish this.1 Element Classname and Modfications File Notes Banner .css Default value: top: 32px bottom: 17px Give custom value to height Body #frame Set custom top and bottom values that position the body of the application between the banner and footer without overlap This value needs to be equal to or greater than the height of . The following table lists the changes made to the user interface and describes some of the steps necessary to update custom themes in overrides_custom. The changes to the login page are extensive.1. custom themes developed for the previous interface will need to be updated for the new interface. Table A-1 Updating Themes in JasperReports Server 6. markup and styles have been modified. and login page. containers.primaryNav .over .menu.wrap > .banner element.banner Banner Main Navigation Home icon .pressed Set background-position to a value that properly displays the default or your custom image.node > .icon Set height to be the same as .icon This only needs to be adjusted if you want a different color disclosure indicator for the pressed and over states of the main menu links 49 .menu. height: 32px background-position: left -79px width: 11px Set background-position and width to a value that properly displays the default or your custom image.css height: 31px line-height: 31px containers.css height: 32px Set height and line-height to 1px shorter than .css Set height to your desired value.menu.Appendix A  Planning Your Upgrade Element Classname and Modfications File Notes Banner Logo #logo theme.banner width: 14px background-position: 0 -164px background-position: 0 -163px (IE8-9) Set values for width and background-position to fit your image.menu.wrap > .menu. the value is cascaded from . with the maximum value being the same height measurement as the .primaryNav .wrap.primaryNav .wrap. Banner Main Navigation Item arrow icon TIBCO Software Inc.css Default values: height: 22px width: 176px Give custom values to height and width that match the dimensions of your logo margin-top: 6px margin-right: 4px margin-bottom: 0 margin-left: 8px Adjust margins around the logo if needed Banner Main Navigation .primaryNav .primaryNav #main_home .node > .wrap > .icon Banner Main Navigation Item arrow icon . .css background-position is not explicitly defined.wrap containers. containers.primaryNav .menu. TIBCO Software Inc. Login page 50 Re-implement in new theme.css height: 17px Set margin-top to desired value that will vertically center it within the banner. .JasperReports Server Upgrade Guide Element Classname and Modfications File Notes Banner Search container #globalSearch. Set line-height to the desired value that will vertically center it within the banner.css margin-top: 5px Banner Metadata #metalinks li themes. Set height if you want it to be anything other than the default value.searchLockup controls.css line-height: 20px Footer #frameFooter containers. 0.Appendix A  Planning Your Upgrade A. Copy or re-enter the properties you need for your server.1. Before upgrading. c. Customizations – If you have customized the server using Spring Security classes. Rename the JasperReports Server 6. taking care not to copy over class names or class packages.xml.2 Changes in 6. locate <js-install6.xml files in the <js-install>/samples/externalAuth-sample-config directory. Update your server installation to JasperReports Server 6. If you want to encrypt the default password.0.xml.1 sample file to remove the sample.0.xml to applicationContext-externalAuth-LDAP. As of JasperReports Server 6. as described in the JasperReports Server Upgrade Guide. you need to reimplement your changes in the updated sample files in JasperReports Server 6. See the JasperReports Server External Authentication Cookbook and the JasperReports Server Security Guide for more information.1: 1. you need to migrate your solution to the new framework. TIBCO Software Inc. locate the sample file that corresponds to the file you implemented previously. you can customize the default admin users created when external authentication creates a new organization. For many users. Optionally you can also encrypt the admin's password in the configuration files.1. 4. if you implemented applicationContext-externalAuth-LDAP. applicationContextexternalAuth-LDAP.xml).2. located in the <js-webapp>/WEB-INF directory of your previous version of JasperReports Server. you need to update your implementation: • If you implemented external authentication using one of the sample files included in the project. 51 .1. 2.0.0. However. Find the same bean in the JasperReports Server 6.0.xml. • If you implemented a custom external authentication solution. For example. rename sample-applicationContext-externalAuth-LDAP. you need to set this up before installation or upgrade. Locate each bean you modified in the previous version. 5. Migrating External Authentication Sample Files If you have implemented external authentication using one of the sample-applicationContext<customName>.1>/samples/externalAuth-sample-config/sample-applicationContext-externalAuth-LDAP. b.0. Configure the properties in the new sample file to match the properties in your existing sample file. In JasperReports Server 6.0. you need to migrate your solution to the new framework.x to 3. back up your applicationContext-<customName>. To do this: a.2.xml (for example. For example.1 sample.prefix. 3.0.do the following to migrate your changes to JasperReports Server 6. this upgrade will have no impact.0. In the new installation.1 That May Affect Your Upgrade JasperReports Server uses the Spring Security framework to implement security throughout the product. The names of the beans are the same in each version.1 External authentication – If you have implemented external authentication or single sign-on in your server implementation. you may need to make some changes if you have implemented the following: • • A. the Spring Security framework was updated from Spring Security 2.1.5. you need to change the names and paths of the Spring Security classes you reference in any customizations you've made to JasperReports Server.0.0.2. The Spring Security codebase was significantly restructured from 2.1 sample files. Place the modified file in the <js-webapp-6.2.0. e.x to 3. This table is for information only. “Mapping of Spring Classes from 2.0. A. Table A-3. Table A-2. Many classes were moved to new packages and some classes were renamed.2 Migrating Customizations At a minimum. It has not been verified with the Spring Security project and is not guaranteed to be correct.JasperReports Server Upgrade Guide Although the bean names are the same in the JasperReports Server 6.0.xml to applicationContext-externalAuth-LDAP. A.prefix.” on page 53 shows the correspondence between Spring Security classes in earlier versions of JasperReports Server and the new wrapper classes in JasperReports Server 6.1. we created wrapper classes for the Spring Security classes used in the external authentication sample files.” on page 55 shows the mapping from 2.1 sample file to remove sample.5 source code.0. Make sure not to overwrite the new names with the old ones. d.x to 3. rename sample-applicationContext-externalAuth-LDAP.1 Wrapper Classes To reduce the impact of future upgrades. You can also search the internet.0.x.2 for important Spring Security classes used in JasperReports Server. Rename the JasperReports Server 6.2.1 sample file. For example. Additional information is included in the Spring Security 3. . the name and package of the class in many bean definitions have changed.0.1.xml. Save the JasperReports Server 6.1>/WEB-INF directory.x to 3.5. 52 TIBCO Software Inc. “Wrapper Classes in JasperReports Server 6.2. f.1. security. spring.ui.api.jasperserver.x External Authentication Wrappers org.externalAuth.springframework.ui.jasperserver.jasperserver.cas.externalAuth.externalAuth.externalAuth.wrappers.jaspersoft.jasperserver.jasperserver.security.userdetails. spring.security.0.providers. spring.springframework.api.externalAuth.Appendix A  Planning Your Upgrade A.wrappers.JSLdapUserDetailsService TIBCO Software Inc.providers.Cas20ServiceTicketValidator com.jasig.api.security.JSEhCacheFactoryBean org.api. spring.cas.EhCacheBasedTicketCache com.JSExceptionTranslationFilter org.LdapUserDetailsService com.cache. spring.jaspersoft.cas.api.2.JSCasAuthenticationProvider org.springframework.security.wrappers.ui.JSEhCacheBasedTicketCache org.api.jaspersoft.CasAuthenticationProvider com.ehcache.client.security.security.jaspersoft. spring.api.jaspersoft.cas.wrappers.0.x Class 3.ProviderManager com.jasperserver.0. jasig.springframework.springframework.jaspersoft.jaspersoft.jasperserver.EhCacheFactoryBean com.3 Changes to Security Classes in JasperReports Server 6.externalAuth.wrappers.security.cas.springframework.validation.jaspersoft.security.api.security.ldap.JSAuthenticationDetailsSourceImpl org. spring.ExceptionTranslationFilter com.wrappers.wrappers.jaspersoft.JSCas20ServiceTicketValidator org.security.cas.externalAuth.1 Spring Security 2. spring. 53 .jasperserver.AuthenticationDetailsSourceImpl com.JSProviderManager org.externalAuth.JSCasAuthenticationEntryPoint org.security.providers.ldap.springframework.1 Table A-2 Wrapper Classes in JasperReports Server 6.security.cache.security.api.externalAuth.security.jasperserver.security.CasProcessingFilterEntryPoint com.wrappers.wrappers.springframework. externalAuth.ldap.ldap.api.ldap.springframework.security.providers.ldap.jasperserver.jasperserver.jdbc.springframework.jaspersoft.jasperserver.FilterBasedLdapUserSearch com.JSDriverManagerDataSource org.ldap.search.springframework.security.externalAuth.ldap.security.SimpleClientHttpRequestFactory com.jaspersoft.LdapAuthenticationProvider com.x External Authentication Wrappers org.security.jaspersoft.security.ldap.jasperserver. spring. .springframework. spring.JasperReports Server Upgrade Guide Spring Security 2.externalAuth.JSSimpleClientHttpRequestFactory org.wrappers.cas.PreAuthenticatedAuthenticationProvider com.JSPreAuthenticatedAuthenticationProvider 54 TIBCO Software Inc.security.0.wrappers.ldap.wrappers. spring.security.populator.populator.jaspersoft.springframework.externalAuth.security.externalAuth.wrappers.wrappers.springframework.security.externalAuth.JSDefaultLdapAuthoritiesPopulator org.springframework.wrappers.JSDefaultLdapAuthoritiesPopulator org.springframework.api.api.security.JSLdapAuthenticationProvider org.datasource.api.jaspersoft.jaspersoft.jasperserver.jasperserver.security.api.preauth.x Class 3.preauth. spring.JSCASServiceProperties org.jasperserver. spring.externalAuth. spring. spring.ui.http.externalAuth.security.jaspersoft.security.springframework.client.api.authenticator.ldap.api.ServiceProperties com.DefaultLdapAuthoritiesPopulator com.providers. spring. spring.ldap.jasperserver.jdbc.security.providers.wrappers.security.DefaultLdapAuthoritiesPopulator com.security.JSFilterBasedLdapUserSearch org.DriverManagerDataSource com.BindAuthenticator com.wrappers.wrappers.api.JSBindAuthenticator org.jasperserver.api.jaspersoft.cas.jaspersoft.externalAuth. springframework.core.springframework.security.springframework. BasicProcessingFilter org. AnonymousAuthenticationFilter org.2 Class org.security.ui.web.security.authentication.Authentication org.FilterChainProxy org.context.springframework.springframework.security.authentication.ExceptionTranslationFilter org.springframework.web.FilterChainProxy org.anonymous.ExceptionTranslationFilter ProviderManager moved to org.www.basicauth. Note that three of the Spring Security classes in the table have moved to different packages: ExceptionTranslationFilter moved to org.ui.2.basicauth.authentication.security.ui.webapp.web.ui.access.security.authentication.security.authentication.security.security.security.springframework.web.www.springframework.0.SecurityContextHolder org.0.security.security.ui.web.x to 3. BasicProcessingFilterEntryPoint org. AuthenticationProcessingFilter org.web. UsernamePasswordAuthenticationFilter TIBCO Software Inc.util. 55 .springframework.access.authentication.security.security.security.security.springframework. AuthenticationProcessingFilterEntryPoint org.security.security.SecurityContextHolder org.springframework.springframework. BasicAuthenticationEntryPoint org.x Class Spring Security 3.authentication.springframework.springframework.web. AnonymousProcessingFilter org.AuthenticationDetailsSourceImpl Table A-3 Mapping of Spring Classes from 2.springframework.context.springframework.5 Spring Security 2.ExceptionTranslationFilter org.providers.x Spring Security classes.Authentication org.security.webapp.core.springframework. BasicAuthenticationFilter org.security.springframework.springframework.springframework.ProviderManager AuthenticationDetailsSourceImpl moved to org. LoginUrlAuthenticationEntryPoint org.springframework.0.web.security.Appendix A  Planning Your Upgrade Table A-2 shows the 2. core.userdetails.springframework.war.springframework.security.Acl 56 TIBCO Software Inc.springframework.access.springframework.security.common.authentication.web.springframework.security.springframework. UsernamePasswordAuthenticationToken org.0. FilterSecurityInterceptor com.vote.jaspersoft.access.authority.AclObjectIdentity org.vote.springframework.springframework. SecurityContextPersistenceFilter org.access.core.AccessDecisionVoter org.userdetails.JSSwitchUserProcessingFilter com.springframework.security.JSSwitchUserProcessingFilter org.security.security.core.springframework.springframework.2 Class org.springframework.security.AuthorizationServiceException org.springframework.access.User org.security.security.security.jasperserver.AuthenticatedVoter org.security.springframework.security.security.security.security.AffirmativeBased org.api.springframework.security.springframework.security. HttpSessionContextIntegrationFilter org.GrantedAuthority org.intercept.security.GrantedAuthority org.jaspersoft. FilterSecurityInterceptor org.vote.acls. AuthenticationServiceException org.vote.springframework.acl.springframework.security.security.GrantedAuthorityImpl org.User org.vote.context.springframework.access.web.BasicAclEntryVoter org.security.core.acls.core.AclEntry org.intercept.AccessDecisionVoter org.springframework.springframework.security.acls. AuthenticationServiceException org.springframework.springframework.AclEntryVoter org.acl. UsernamePasswordAuthenticationToken org.AuthenticatedVoter org.authentication.springframework.security.model.security.basic.security.providers.context.GrantedAuthorityImpl org.security.web.springframework.springframework.security.AffirmativeBased org.security.security.AuthorizationServiceException org.jasperserver. .springframework.JasperReports Server Upgrade Guide Spring Security 2.springframework.model.x Class Spring Security 3.vote.ObjectIdentity org. security.security.providers.ui.security.AuthorizationServiceException org.encoding.springframework.security.security.springframework.springframework.AccessDeniedException org.security.springframework.security.security.ConfigAttribute org.security.springframework.Appendix A  Planning Your Upgrade Spring Security 2.AuthorizationServiceException org.security.security.springframework.providers.PasswordEncoder org.security.springframework.AbstractAclVoter org.ConfigAttribute org.springframework.security.security.ui.concurrent.DaoAuthenticationProvider org.security. SwitchUserGrantedAuthority org.x Class Spring Security 3.ConfigAttribute> org.WebAuthenticationDetails org.security.SessionInformation org.security.vote.springframework.PasswordEncoder org.security.springframework.authentication.security.session.springframework.anonymous.afterinvocation.AbstractAclVoter org.acl.ConfigAttributeDefinition Collection<org.springframework.security.core.security.springframework.security.AuthorizationServiceException org.springframework.security.springframework. AnonymousAuthenticationToken TIBCO Software Inc.security.switchuser.DaoAuthenticationProvider org.springframework.AfterInvocationProvider org.access. SwitchUserGrantedAuthority org.springframework.access.authentication.springframework.security.AclManager org.SessionRegistry org.springframework.access.springframework.SecurityConfig org.AccessDeniedException org.access.security.vote. 57 .AfterInvocationProvider org.security.springframework.SessionRegistry org.springframework.WebAuthenticationDetails org.authentication.authentication.security.concurrent.springframework.springframework.springframework.providers.access.dao.springframework.access.encoding.model.AuthorizationServiceException org.access.security.core.security.springframework.switchuser.0.springframework.springframework. AnonymousAuthenticationToken org.2 Class org.dao.access.acls.security.session.SecurityConfig org.AclService org.security.authentication.SessionInformation org.web.springframework.springframework.web.springframework. springframework.springframework.AuthenticationProvider org.authentication.security.context.security.method.web.web.springframework.SecurityContext org.authentication.security.springframework.ui.springframework.UserAttribute org.springframework.security.security.0.CasProcessingFilter org.RoleVoter org.JasperReports Server Upgrade Guide Spring Security 2.access.jdbc.security.springframework.springframework.security.vote.springframework.security.springframework.springframework.springframework.userdetails.UrlUtils org.AuthenticationProvider org.NullRememberMeServices org. .security.UserAttribute org.security.security.security.TestingAuthenticationToken org.security.JdbcDaoImpl org.providers.security.security.UrlUtils org.springframework.springframework.springframework.springframework.springframework.memory.web.authentication.intercept.intercept.security.BadCredentialsException org.RoleVoter org.SecurityContext org. MethodSecurityInterceptor org.security.security.userdetails.LdapUserDetails org.springframework.userdetails.security.2 Class org.cas.security.x Class Spring Security 3.core.springframework.jdbc.util.security.security.security.springframework.security.springframework.TestingAuthenticationToken org.springframework.util.AccessDeniedException org.security.authentication.ui.security.core.AfterInvocationProvider org.security.springframework.UnanimousBased org.springframework.springframework.BadCredentialsException org.providers.NullRememberMeServices org.springframework.cas.AuthenticationManager org.security.springframework.access.AuthenticationManager org.access.core.memory.springframework.afterinvocation.vote.aopalliance.springframework.aopalliance.springframework.ldap.AfterInvocationProvider org.access.security.JdbcDaoImpl org.AccessDeniedException org.LdapUserDetails org.CasAuthenticationFilter org.UnanimousBased 58 TIBCO Software Inc.security.userdetails.context.access.core.userdetails. MethodSecurityInterceptor org.springframework.security.vote.rememberme.authentication.springframework.userdetails.security.vote.ldap. springframework.servletapi.security.core.ProviderManager org.security. 59 .InMemoryDaoImpl org.2 Class org.afterinvocation.InMemoryDaoImpl org.security.concurrent.security.acls.springframework.LoggerListener org.springframework. BasicAclEntryAfterInvocationCollectionFilteringProvider org.authentication.core. SecurityContextHolderAwareRequestFilter org.AfterInvocationProviderManager org.security.springframework.intercept.access.memory.wrapper.security.security.springframework.security.springframework.security.AclEntryAfterInvocationCollectionFilteringProvider org.springframework.AfterInvocationProviderManager org.event. SecurityContextHolderAwareRequestFilter org.springframework.security.ui.security.acls.springframework.springframework.web.springframework.afterinvocation.Appendix A  Planning Your Upgrade Spring Security 2.userdetails.SessionRegistryImpl TIBCO Software Inc.userdetails.session.afterinvocation.security.security.security. BasicAclEntryAfterInvocationProvider org.springframework.security.event.springframework.0.afterinvocation .ProviderManager org.springframework.LoggerListener org.SessionRegistryImpl org.authentication.providers.springframework.security.springframework.security.security.authentication.x Class Spring Security 3.afterinvocation. AclEntryAfterInvocationProvider org.springframework.AuthenticationDetailsSourceImpl org.memory.AuthenticationDetailsSourceImpl org.authentication.springframework. The new drivers have the following impact: • • • 60 If you're upgrading and want to use your current driver for the repository.0. we added support for hierarchical attributes. either do a cast to that interface. which can be assigned at the server. or inject the property using the existing interface so no cast is needed. Jaspersoft added TIBCO JDBC drivers for the following commercial databases: • • • • Oracle SQL Server DB2 Hive — available as a data source only. Existing Domain security files only detect attributes assigned at the user level. you must copy the driver to the correct location and modify default_master. organization.properties for the driver you choose.4 Changes in 5. the security file does not detect them.1 Changes to Custom Data Sources Changes to the Spring configuration in JasperReports Server 6. A. See the section on your upgrade procedure for more information. You can update your custom data sources as follows: • • A. .2 To access methods on an existing interface. Prior to JasperReports Server 6.1.0 That May Affect Your Upgrade A. See the section "Working with Hierarchical Attributes" in the JasperReports Server Security Guide for information on how to update your security file. See the JasperReports Server Installation Guide or the JasperReports Server Administrator Guide for more information. if code in JasperReports Server accessed a bean of this type. To access methods not on an existing interface.1 That May Affect Your Upgrade In 5. In JasperReports Server 6. you need to set up the driver in your application server console. Since proxies can only represent interfaces. and it could be cast to the concrete class.3. Casting is usually done to get access to methods on a more specific class or interface.6. Even if other attributes are present.3 Changes in 6. If you're using WebLogic or WebSphere and want to use a TIBCO driver. TIBCO Software Inc. Changes to Domain Security Files In JasperReports Server 6. or user level. create an interface with the methods you need and have the target object implement that interface. it got the actual instance of the Spring bean as configured in the Spring XML file.0 and later.JasperReports Server Upgrade Guide A. cannot be used for the JasperReports Server repository database. beans of this type are intercepted and other code sees a dynamic proxy instead of the actual bean.3.6. you must use the TIBCO JDBC driver.0. This change specifically affects beans which implement the ReportDataSourceServiceFactory interface . existing code that tries to cast the bean to a concrete class will break.0 can affect custom data sources. For supported Hive platforms other than Impala and Cloudera 5. Removal of Commercial JDBC Drivers The following commercial database drivers were removed from the JasperReports Server 5. In this case.DataSource=Foodmart.6. You'll need to obtain a JDBC driver before running the upgrade. To test connections in servers that host multiple organizations. or DB2. During upgrade. For more information. XML/A connections will fail for superuser. you must take additional steps to complete your upgrade to 5.5 syntax includes a semicolon at the end). SQL Server. This is because of a change between versions of the OLAP engine. this connection must be changed to: Provider=Mondrian. we recommend that you log in as jasperadmin or another administrative account other than superuser. Once the new version of JasperReports Server is installed and running. you need to copy it to the correct location in your upgraded JasperReports Server.2 Changes to OLAP Engine If you use Jaspersoft OLAP’s XML/A functionality to connect to a remote JasperReports Server’s XML/A sources. 61 .6 package: Oracle. you must take additional steps to complete your upgrade to 5. the trailing semicolon should be removed (the older 5. because you most likely have an Oracle JDBC driver in your existing JasperReports Server instance.jar Copy to:  <js-install-5. refer to the Jaspersoft OLAP Ultimate Guide.DataSource=JR Note that for 5. locate all the XML/A connections that point to a remote JasperReports Server instance.6 That May Affect Your Upgrade The following changes in 5. Then edit the DataSource field to specify JRS as the DataSource portion of its value.Appendix A  Planning Your Upgrade A. if you use Jaspersoft OLAP’s XML/A functionality to connect to a remote JasperReports Server’s XML/A sources.6>/buildomatic/conf_source/db/oracle/jdbc A. refer to the Jaspersoft OLAP User Guide.5 Changes in 5. This limitation applies exclusively to the superuser account. Note that if your instance hosts multiple organizations.6. For more information about creating and editing XML/A connections. the Foodmart XML/A connection specified: Provider=Mondrian.6.1 Removal of commercial JDBC drivers: if you're using a commercial JDBC driver.6 and later can significantly affect your deployment: • • A. in previous versions.5. TIBCO Software Inc. Changes to OLAP engine: Due to change between version of the OLAP engine. it's simplest to copy it from that location: Copy from:  <js-install-existing>/buildomatic/conf_source/db/oracle/jdbc/<driver-name>. for Oracle. One reason you might have XML/A connections to remote instances of JasperReports Server is to create a loadbalanced Jaspersoft OLAP environment. For example.5.