Jasper Reports Server Install Guide

JASPERREPORTS SERVER
INSTALLATION GUIDE
RELEASE 4.1
http://www.jaspersoft.com
JasperReports Server Installation Guide
2
Copyright 2011 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo,
JasperAnalysis, JasperServer, JasperETL, JasperReports, JasperReports Server, and iReport, are trademarks and/or registered
trademarks of Jaspersoft Corporation 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 0511-JSP41-25 of the JasperReports Server Installation Guide.
Table of Contents
3
TABLE OF CONTENTS
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.1 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.2 Java Version Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.3 JasperReports Server Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4 Installer Distribution Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4.1 Installer Distribution Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.4.2 Installing with Existing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.4.3 Running Components as Windows Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5 WAR File Binary Distribution Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.6 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.7 Prerequisites for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.8 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.9 Support for Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 2 Installing JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1 Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.1 Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.2 Accepting the License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.3 Choosing an Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.4 Selecting Tomcat Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.5 Selecting MySQL Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.6 Installing Sample Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.7 Installing Jaspersoft iReport Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.8 Ready to Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.9 Installation Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.10 Logging into JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2 Post-Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.1 Updates Made by the Installer During Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.2 Installer Output Log File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.3 Installing a New License File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4
2.2.4 License File for Existing Tomcat as Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.5 Checking your Java JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Chapter 3 Starting and Stopping JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1 Using the Start/Stop Menu With Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2 Using Start/Stop Scripts Without Bundled Installation with Windows . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.3 Start/Stop Scripts for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4 Using Start/Stop Apps With Mac OSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.5 Logging into JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.6 Starting the Included Jaspersoft iReport Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.7 JasperReports Server Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 4 Uninstalling JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3 Mac OSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4 Uninstall Survey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 5 Installing the WAR File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.1 Applications Supported by the WAR File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.2 Obtaining the WAR File Distribution Zip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.3 Unpacking the WAR File Distribution Zip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.4 Introduction to Buildomatic Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.5 Pre-Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.5.1 Checking Your Java Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.5.2 About Bundled Apache Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.5.3 Checking Your Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.5.4 Checking Your Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.6 Configuring the Buildomatic Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.6.1 Creating your Default Master Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.7 Installing JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.7.1 Windows Auto-Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.7.2 Linux Auto-Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.7.3 Auto-Install with Minimal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.7.4 Output Log Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.7.5 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.8 Setting Up the JasperReports Server License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.8.1 License Configuration for All Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.8.2 Alternative JasperReports Server License Set Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.9 Setting Java JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.10 Starting JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.11.1 JasperReports Server Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.12 Troubleshooting Your JasperReports Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.12.1 JasperReports Server Startup Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table of Contents
5
5.12.2 Error Running a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.12.3 Error Running Auto-Install Scripts (js-install.bat/sh) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.12.4 Auto-Install Script Test Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.12.5 Auto-upgrade Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.12.6 Auto-Install Script Output Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.13 Running the Import and Export Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.13.1 Running Export from Buildomatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.13.2 Running Import from Buildomatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.13.3 Running the Import Export Shell Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.14 Pre-Test Validation mode of Auto-Install Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.14.1 Additional Command for Buildomatic Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.15 Manual Steps for DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.15.1 Creating Databases Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.16 Manual Buildomatic Install Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Chapter 6 Additional Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1 Setting JVM Options for Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1.1 Tomcat and JBoss JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1.2 Bundled Tomcat as a Windows Service JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.1.3 Existing Tomcat as a Windows Service JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1.4 GlassFish JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.2.1 License Configuration for Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2.2 Alternate License Setup for Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2.3 Alternate License Setup for Bundled Tomcat as a Windows Service . . . . . . . . . . . . . . . . . . 47
6.2.4 Alternate License Location for Existing Tomcat as a Windows Service . . . . . . . . . . . . . . . . 48
6.2.5 Alternate License Setup for JBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.2.6 Additional Evaluation Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.3 Additional Buildomatic Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.3.1 Buildomatic: Generated Property Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.3.2 Buildomatic: SQL Scripts Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.3.3 Buildomatic: Database Creation Statements Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.3.4 Buildomatic: JDBC Driver Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.3.5 Buildomatic: Change your Deployed JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.3.6 Buildomatic: JasperReports Server WAR File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.3.7 Buildomatic: Sample Data Catalog ZIP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.4 Additional Notes on Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.4.1 Notes on the MySQL Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.4.2 Notes on the Oracle Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.4.3 Notes on the DB2 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.5 Notes on the Hibernate Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.6 Notes on Database Connections for Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.7 Notes on Data Source Definitions for JBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.7.1 Notes on Extra JBoss Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.8 Notes on Database Connections for GlassFish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6
6.9 Report Scheduling Configuration with Quartz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.9.1 Mail Server Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.9.2 Database settings for the Quartz Driver Delegate Class . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.9.3 Settings for the Report Scheduler Web URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.9.4 Settings for the Quartz Table Prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.9.5 Settings for Import-Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.10 Notes on Updating XML/A Connection Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Chapter 7 Installing the WAR File for WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.3 Setting Up the JasperReports Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.4 Configuring Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.4.1 Configuring JDBC Data Sources for MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.4.2 Configuring JDBC Data Sources for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.4.3 Configuring JDBC Data Sources for DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.5 Configuring Hibernate and Quartz in the WAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.5.1 Additional Fix for Scheduled Report with JNDI Data Source . . . . . . . . . . . . . . . . . . . . . . . . 68
7.5.2 Additional Change for Mail Server Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.7 Deploying the JasperReports Server WAR to the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.8 Setting Java JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.9 Restarting the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.12 Configuring Report Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.13 Updating XML/A Connection Definitions (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.14 Restarting JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.15 Troubleshooting your JasperReports Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.15.1 Startup Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.15.2 Error Running Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.15.3 Filter Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.15.4 Error Creating Internationalized Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.15.5 Xerces Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.15.6 OLAP View Fails With Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.15.7 Analysis Options Page Throws Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Chapter 8 Installing the WAR File for WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
8.3 Setting Up the JasperReports Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.4 Configuring Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.4.1 Configuring Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.4.2 Setting Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
8.4.3 Testing Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Table of Contents
7
8.4.4 Selecting Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
8.5 Deleting JARs and Setting Configurations in the WAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
8.6 Additional Changes for WebLogic 10.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
8.7 Preparing the WebLogic Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
8.7.1 Editing the Domain Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
8.7.2 Preparing the Domain Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
8.7.3 Setting Java Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
8.8 Deploying JasperReports Server to WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
8.11 Configuring Report Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.12 Restarting JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.13 Updating XML/A Connection Definitions (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.14 Troubleshooting Your JasperReports Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.14.1 Startup Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.14.2 Error Running Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Chapter 9 Upgrade from 3.7 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.1 Standard Upgrade Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.2 Backing Up Your JasperServer 3.7 Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.3 Export Your 3.7 Repository Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.3.1 Export Using Buildomatic Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.3.2 Export Using js-export Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.4 Preparing the JasperReports Server 4.1 WAR File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.5 Configuring Buildomatic for Your Database and Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.5.1 Example Buildomatic Configuration (using MySQL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.6 Upgrading to JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.6.2 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.7 Starting JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.8 Logging into JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.8.1 Clearing Your Browser Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.9 Additional Notes on JasperReports Server Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.9.1 Handling JasperReports Server Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.9.2 Clearing the Application Server Work Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.9.3 Clearing the Application Server Temp Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.9.4 Clearing the Repository Cache Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.9.5 Updating the XML/A Connections (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.9.6 Upgrading the Liferay Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.10 Older Manual Upgrade Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
9.10.1 Manual Upgrade Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Chapter 10 Upgrade from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
10.1 Upgrade Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
8
10.2 Backing Up Your JasperServer 4.0 Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
10.2.1 Backing Up Your JasperServer WAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
10.2.2 Backing Up Your JasperServer Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
10.3 Preparing the JasperReports Server 4.1 WAR File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
10.4 Configuring Buildomatic for Your Database and Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . 92
10.4.1 Example Buildomatic Configuration (using MySQL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
10.5 Upgrading to JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
10.5.2 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.6 Starting JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.7 Logging into JasperReports Server 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.7.1 Clearing Your Browser Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.8 Additional Information on Post-Upgrade Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.8.1 Clearing the Repository Cache Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
10.9 Running Buildomatic DB Upgrade Steps Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Chapter 11 Upgrade Notes for JasperServer 3.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
11.1 Upgrade from JasperServer 3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Chapter 12 Upgrading From Community Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
12.1 General Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
12.2 Backing Up Your JasperReports Server CE Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
12.2.1 Backing Up Your JasperReports Server CE WAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
12.2.2 Backing Up Your JasperReports Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
12.3 Exporting Your CE Repository Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
12.4 Preparing the JasperReports Server Pro 4.1 WAR File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . 101
12.5 Configuring Buildomatic for Your Database and Application Server . . . . . . . . . . . . . . . . . . . . . . . . . 101
12.5.1 Example Buildomatic Configuration (using MySQL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
12.6 Upgrading to JasperReports Server Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
12.7 Starting JasperReports Server Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
12.8 Logging into JasperReports Server Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
12.8.1 Clearing Your Browser Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
12.8.2 Logging into JasperReports Server Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
12.9 Additional CE to Pro Upgrade Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
12.9.1 Notes on XML/A Configuration After Upgrade to Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Chapter 13 Changing Password Encryption in JasperReports Server . . . . . . . . . . . . . . . . . . . . 105
13.1 Backing Up Your JasperReports Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
13.2 Stopping Your Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.3 Running the Repository Export Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.4 Specifying Encryption Settings in the JasperReports Server WAR . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.4.1 Specifying Encryption Settings - Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
13.5 Specifying Encryption Settings for the Import Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
13.6 Recreating the JasperReports Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Table of Contents
9
13.6.1 Dropping and Recreating in MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
13.6.2 Dropping and Recreating in Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
13.6.3 Dropping and Recreating in Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
13.6.4 Dropping and Recreating in PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
13.7 Importing Your Repository Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
13.8 Starting the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
13.9 Logging into JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 14 Configuring the Import-Export Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
14.2 Import-Export Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
14.3 Changing Your Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
14.3.1 First Create a default_master.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
14.3.2 Here are the Configuration Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
14.3.3 Check your js.jdbc.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
14.3.4 If DB2 or PostgreSQL Check your js.quartz.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
14.4 Deploying a Database Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
14.5 Running Import or Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
14.5.1 Import-Export Updates for 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
14.6 Configuring the Import-Export Utility for JasperServer 3.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Appendix A Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
A.1 Installer Freezes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
A.2 Database Connectivity Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
A.2.1 Testing the Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
A.2.2 Configuration File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
A.2.3 Context.xml under Tomcat: Special Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
A.2.4 Connect to Installed/Bundled Version of MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
A.2.5 Case Sensitive Collation in SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
A.2.6 Maximum Packet Size in MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
A.3 License Not Found Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
A.4 License Not Found Error with Tomcat as a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
A.5 Error Running a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
A.6 Database Error after Changing MySQL Port Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
A.7 Case Sensitivity for Table and Column Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
A.8 Java Out of Memory Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
A.9 Error Running Scheduled Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
A.10 Exporting a Repository That Contains UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
A.10.1 Error During JasperServer 1.2 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
A.10.2 Error During Export from Repository on Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
A.11 Importing Scheduled Jobs with Update Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
A.12 JBoss Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
A.12.1 JBoss 4.2 XML/A Connection Fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
A.12.2 JBoss Large INFO Log Message on Analysis Drill-through . . . . . . . . . . . . . . . . . . . . . . . . 123
A.12.3 JBoss 4.0 Log4j Error on Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10
A.12.4 JBoss 5.0.1 and 5.1.x Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
A.13 WebSphere: Page Not Found Error on Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
A.14 PostgreSQL: Job Scheduling Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
A.15 Error Running Buildomatic Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
A.15.1 Missing Java JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
A.15.2 Forgot to Copy the File ant-contrib.jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
A.15.3 Older Apache Ant Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
A.16 Troubleshooting on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
A.17 Disabling User Session Persistence in Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
A.18 Linux Installer Issue with Unknown Host Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
A.19 Oracle auto-install Script Hangs with Oracle 10g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
A.20 Problem Starting JasperReports Server on the Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Introduction
11
CHAPTER 1 INTRODUCTION
JasperReports Server builds on JasperReports as a comprehensive family of Business Intelligence (BI) products, providing
robust static and interactive reporting, report server, and data analysis capabilities. These capabilities are available as either
stand-alone products, or as part of an integrated end-to-end BI suite utilizing common metadata and providing shared services,
such as security, a repository, and scheduling. The server exposes comprehensive public integration interfaces enabling
seamless integration with other applications and the capability to easily add custom functionality.
The heart of the Jaspersoft BI Suite is the server, which provides the ability to:
Easily create new reports using an intuitive web-based drag and drop Ad Hoc reporting interface.
Efficiently and securely manage many reports.
Interact with reports, including entering parameters and drilling on data.
Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey business trends.
For business intelligence users, Jaspersoft offers Jaspersoft OLAP, which runs on the server. This optional component is
described in its own user guide.
Jaspersoft provides several other sources of information to help extend your knowledge of JasperReports Server:
Our Ultimate Guides document advanced features and configuration. They also include best practice recommendations
and numerous examples. The guides are available as downloadable PDFs. Community project users can purchase
individual guides or bundled documentation packs from the Jaspersoft online store. Commercial customers can download
them freely from the support portal.
Our free Business Intelligence Tutorials let you learn at your own pace, and cover topics for developers, system
administrators, business users, and data integration users. The tutorials are available online from the Professional Services
section of our website.
Free samples installed with JasperReports, iReport, and JasperReports Server, are documented online: JasperReports
Samples Overview and JasperReports Samples Reference. For more information, visit our community website.
This chapter contains the following sections:
Conventions
Java Version Supported
JasperReports Server Distributions
Installer Distribution Support
WAR File Binary Distribution Support
Release Notes
Prerequisites for Installation
System Requirements
Support for Internationalization
12
1.1 Conventions
This document uses the following conventions when referring to file locations:
1.2 Java Version Supported
JasperReports Server supports both Java 1.5 and Java 1.6. Versions earlier than Java 1.5 are not supported.
1.3 JasperReports Server Distributions
There are two main distribution packages for JasperReports Server.
The installers have the capability of installing JasperReports Server, automatically configuring the JasperReports Server
database, and optionally installing sample data that highlight the server features.
The WAR file binary distribution contains the JasperReports Server web archive file as well as scripts to create and load the
database. The WAR file distribution supports additional applications that are not supported by the installers.
1.4 Installer Distribution Support
The installers support the following operating systems:
Convention Description
<js-install> The root directory where JasperReports Server will be installed.
For manual installations, the directory where you unpack the WAR file distribution.
<tomcat> The directory where Apache Tomcat is installed. If you use the instance of Tomcat
that is bundled by the installer, <tomcat> is located in <js-install>.
<jboss> The directory where JBoss is installed.
<glassfish> The directory where GlassFish is installed.
<mysql> The directory where MySQL is installed. If you use the instance of MySQL that is
bundled by the installer, <mysql> is located in the <js-install> directory.
<java> The directory where java is installed.
Distribution Package Description
Installer Runs on Windows, Linux, and Mac OSX.
WAR File Binary Distribution Zip Used for manual installation on Windows, Linux, Mac, and other platforms.
Platform Versions supported
Windows XP
Vista
Windows 7
Introduction
13
1.4.1 Installer Distribution Components
The installer is designed so that it is easy to get JasperReports Server up and running quickly. The server requires the Java
environment, an application server, and database to run. The installer distribution contains bundled versions of these
components:
1.4.2 Installing with Existing Components
You can choose to deploy the bundled application or if you have existing components, the installer can deploy to these
components. For instance, if you already have Tomcat on your computer you can choose an existing Tomcat. If you would
like the installer to install Tomcat for you, you can choose the bundled Tomcat. Both Apache Tomcat and the MySQL
database can be independently used as bundled or existing instances. For information on the specific versions of third party
applications that are supported by the installer refer to the JasperReports Server release notes for the distribution you are using.
The release notes are found in the root of the installation directory.
Note: If you use an existing Tomcat or existing MySQL, they must be on the local machine.
1.4.3 Running Components as Windows Services
Starting with release 4.0, the Windows installer now installs MySQL and Tomcat as Windows Services. This makes it more
convenient for users to manage JasperReports Server under the Windows operating system. JasperReports Server can still be
started and stopped from the Windows Startup menu. But, additionally, it can be managed from the Windows Services panel.
Also, the bundled MySQL and Tomcat applications are automatically restarted when the host Windows system is restarted.
If you do not want to run these components to automatically restart you can change the settings in the Windows Services
panel.
You can do this in the following location:
Control Panel > System and Security > Administrative Tools > Services
Then, change the Startup Type from automatic to manual
Linux Red Hat Enterprise Linux
SUSE
Ubuntu
And additional Linux distributions
Mac OSX 10.5 (Leopard)
10.6 (Snow Leopard)
Component Description
JasperReports Server
Application
WAR file and configuration support scripts.
iReport Designer JasperReports Designer that communicates directly with JasperReports
Server for editing, uploading, or executing reports on the server (optionally installed).
Java 1.6 Runtime Runs web application container.
MySQL Database Database server. Can use the bundled version or an existing version. If using an
existing MySQL, it must be on the local machine.
Apache Tomcat Web application container: Can use the bundled version or an existing version.
Documentation
Found in the <js-install>/docs directory.
Platform Versions supported
14
You can find the MySQL and Tomcat services under the following names:
jasperreportsMySQL
jasperreportsTomcat
1.5 WAR File Binary Distribution Support
The WAR file binary distribution is the package you would use to do a manual installation of the JasperReports Server
application. The WAR file supports many more applications than are supported by the installers. By using the WAR file to
install the server, you can use a database other than MySQL and an application server other than Apache Tomcat.
Note: The target database can be on a remote server. The application server should reside on the local machine.
Since version 4.0, there are auto-install scripts that will handle the installation tasks by putting your local settings in a single
property file. These scripts are named:
js-install.bat
js-install.sh
Contents of the WAR file binary distribution are:
1.6 Release Notes
Release notes are included with each distribution and with each new update to a distribution.
Not all applications are immediately supported when a new JasperReports Server version is released. For instance, some
applications require additional testing beyond what is completed for the initial General Availability (GA) release. To find out
exactly what applications are supported with a particular distribution refer to the release notes found in that distribution.
The Windows installer installs MySQL and Tomcat as Services that are automatically restarted on a Windows system
restart. If you dont want them to automatically restart, set these applications to manual Start Type in the Windows
Services panel.
For a complete list of applications supported by the WAR file distribution, refer to the release notes that are included
in the root directory of the distribution.
Content Item Description
JasperReports Server WAR file
archive
All of the JasperReports Server class files and dependent jars.
JasperReports Server Database
Scripts
SQL scripts for each supported database.
JasperReports Server Standard
Sample Data
Sample data that highlights JasperReports Server features.
JasperReports Server Extra
Samples
Web Service example applications, sample reports, custom data source
examples, and other sample files.
Documentation
Guides for end users and administrators.
JasperReports Server auto-install
scripts
Found at <js-install>/buildomatic/js-install.bat and js-install.sh.
Introduction
15
1.7 Prerequisites for Installation
JasperReports Server relies on third-party products, such as application servers and relational databases. Unless you use the
ones included with the installer, these third party products must be installed and configured before beginning an installation.
Refer to the sections below that relate to your preferred application server and database.
1.8 System Requirements
The following table contains the minimum and recommended resources for a full installation, including MySQL and an
application server. The values are based on our own testing. You may find that JasperReports Server can run on systems with
fewer resources or slower systems than stated in the minimum resources column. At the same time, it is possible to run out of
resources with the recommended configuration. The success of your deployment depends on the intended load of the system,
the number of concurrent users, the data sets and whether the databases are installed on the same system as the JasperReports
Server.
1.9 Support for Internationalization
JasperReports Server supports the full Unicode character set using UTF-8 encoding. It also depends on the underlying
database and application server to support the UTF-8 character encoding. If you are using the bundled Tomcat and MySQL
software, UTF-8 is configured by default. If you are using any other existing software, refer to the JasperReports Server
Administrator Guide for instructions on how to configure software to support UTF-8.
Resource Footprint Minimum Recommended
Disk ~700MB 10 GB free 40 GB +
RAM 2 GB 4 GB +
Processor 1.5 GHz single Pentium, UltraSparc II, or equivalent 2.5 GHz + multi-core Pentium
for Windows, Mac, and Linux
16
Installing JasperReports Server
17
CHAPTER 2 INSTALLING JASPERREPORTS SERVER
Installation Steps
Post-Installation Steps
2.1 Installation Steps
When you run the installation executable, you are prompted to specify information about the third party applications that
JasperReports Server relies on. These third party applications are Apache Tomcat and the MySQL database.
To begin, run the installer. The installed application server and database will be on the same host.
In Windows, the installer is an executable file that you can double-click to run. For example, double-click the following:
jasperreports-server-4.1-windows-x86-installer.exe
In Linux, the installer is a .bin file; you can run it from the command line or from a graphical environment. To start the
installer from the command line, open a bash shell, and enter the name of the installer file. For example:
./jasperreports-server-4.1-linux-x86-installer.bin
Whether you run the installer from the command line or in a graphical environment, you are prompted for the same
information. The following sections describe these prompts, and assume you are in a graphical environment. If you are
installing from the command line, use your keyboard to specify the same details. For example, with the license text, instead of
clicking I accept the agreement, you press Y and press Enter.
On Mac OSX, the download file has a ZIP format. Typically, after download, the installer will be found in your <user>/
Downloads folder. And it will already be unpacked. So, after the download is complete, double-click the following:
jasperreports-server-4.1-osx-x86-installer.app
2.1.1 Welcome
The first step introduces the installer and allows you to continue or exit. Click Next.
When you run the installer using an existing database instance, the database must be running at install time. When
you run the installer using an existing Apache Tomcat, it is recommended that the Tomcat instance be stopped,
18
2.1.2 Accepting the License Agreement
You are prompted to read and accept the license agreement. Read the agreement, agree to the terms by clicking I accept the
agreement, and click Next. On the command line, you must page through several screens of text to read the full agreement.
If you do not accept the agreement, you must exit the installer.
2.1.3 Choosing an Installation Directory
You are prompted for the directory where JasperReports Server is installed, referred to as the <js-install> directory. Accept the
default or click Browse and select a different location, and click Next. On the command line, press Enter to accept the default.
To choose a different directory location, enter that location at the prompt.
The default <js-install> directory depends on your operating system:
2.1.4 Selecting Tomcat Configuration
JasperReports Server requires a web application server in order to run. The installer is pre-configured to run with the Apache
Tomcat server. There are two options available for your Tomcat configuration.
The first option is to choose a bundled Tomcat. If you choose this option, the installer puts an instance of Tomcat 6 onto your
system. Click Next. You are prompted for the server port and shutdown port that Tomcat will use. Most users accept the
default values that are displayed. Accept the default values or enter alternate values, then click Next.
The second option is to choose an existing Tomcat. If you already have an instance of Tomcat on your system, then you can
choose this option. Choose the existing Tomcat option and click Next. You are prompted for its location. Enter the correct
location for Tomcat or click Browse to locate and select another location. Click Next. You are prompted for Tomcat's server
port and shutdown port. Accept the default values or enter alternate values, then click Next.
2.1.5 Selecting MySQL Configuration
JasperReports Server requires a database in order to run. The installer is pre-configured to run with the MySQL database.
There are two options available for your MySQL configuration.
The first option is to choose a bundled MySQL. If you choose this option, the installer puts an instance of MySQL 5 onto your
system. Click Next. The default MySQL port 3306 will be used. The installer will also create a MySQL database user with
administrator privileges and credentials of jasperdb/password. If the installer finds that port 3306 is already in use, you are
prompted to pick an alternate port. In this case, pick an alternative port value and click Next.
Values to be entered or set to defaults for the Bundled MySQL configuration:
The second option is to choose an existing MySQL. If you already have an instance of MySQL running on your local system,
then you can choose this option. Choose the existing MySQL option and click Next. You are prompted for the location of
MySQL, and the port to use. Note that the MySQL instance must reside on your local machine (i.e. localhost or 127.0.0.1).
Enter the correct location for MySQL or click Browse to locate and select another location. Click Next. You are prompted for
the root database account password of the MySQL root administrative user. The database administrative user account root is
used by default. Enter the root database user password and click Enter.
Windows: C:\Program Files\jasperreports-server-4.1
Linux: <USER_HOME>/jasperreports-server-4.1
Mac OSX /Applications/jasperreports-server-4.1
Parameter Default Value and Description
Port 3306 - User must choose an alternate port if 3306 is in use.
Database User Name Hard coded default: jasperdb - The installer creates this user which is used to
connect to the JasperReports Server database
Database User Password Hard coded default: password - The installer uses this password for the jasperdb
user. The same password is used for the root database user.
19
The first set of values below are values to be entered. The second set is a description of values used by the installer if installing
to an existing installation of MySQL:
2.1.6 Installing Sample Data
JasperReports Server can be installed with sample data that can help you evaluate its features. Sample data and resources
included are the following:
Sugar CRM data that simulates three years of operations for a fictitious company that relies on the SugarCRM open
source application
Foodmart data that simulates three years of operations for a fictitious company.
JasperReports Server repository resources such as Reports, OLAP Views, Ad Hoc Topics, Domains, Data Sources, and
Input Controls.
Jaspersoft strongly recommends that you install this data, unless you are not interested in testing or evaluating with the
default sample data. Click Yes to install the sample data and click Next.
2.1.7 Installing Jaspersoft iReport Designer
Jaspersoft iReport Designer (hereafter called iReport) is the leading GUI-based JasperReports Library creation tool. It has
the capability of communicating directly with a JasperReports Server instance and can thus retrieve existing JasperReports
Library from a JasperReports Server instance for editing, uploading or execution.
In the installer, iReport comes pre-configured with a plug-in that allows it to communicate with JasperReports Server via the
web services interface.
If you would like to install iReport click Yes.
2.1.8 Ready to Install
The components are now ready for installation. Click Install or Next to continue. Installation can take a number of minutes.
Parameter Default Value and Description
Binary Directory The directory where the mysql and mysqladmin binaries are located.
Port The port number that MySQL uses (default is 3306).
IP or Host Name The value is hard coded to 127.0.0.1. Note that your existing MySQL instance must
reside on the local machine.
MySQL Root Password Password of the database administrative user: root. The installer cannot handle
special characters at the end of a password string. Incompatible characters include:
& ; $
Defaults Used Hardcoded Default Values Used or Created
MySQL Root User Name The default administrative database user is root
Database User Name jasperdb - The installer creates this database user which is used to connect to
jasperserver database.
Database User Password password - The installer creates this password for the jasperdb database user.
To improve system security, Jaspersoft recommends that you change all default password for jasperdb as soon
as possible.
To change the jasperdb connection password in JasperReports Server, edit: <js-install>/apache-tomcat/
jasperserver-pro/META-INF/context.xml. (And delete, if it exists: <js-install>/apache-tomcat/conf/Catalina/
localhost/jasperserver-pro.xml.) Then, make the same change in MySQL to the mysql.user.password table.
20
2.1.9 Installation Complete Screen
After the files have been installed, you will see the final installation screen. There are several post-installation options that you
can choose from, each with its own check box. Simply click to make your choices then click Finish.
View Release Notes - If you choose to view the Release Notes, they are displayed in a new window. If you are running
from the command line, you can page through the Release Notes by pressing the Enter key.
Launch JasperReports Server Now - If you choose to launch JasperReports Server from the installer, the installer exits
and the application server starts if you chose the bundled Tomcat and MySQL. There is a 25 second or so pause to allow
the server to start up. When this pause is complete, the login page appears in your system default Browser. If youre
installing under Linux, do not close the terminal window running the start script. For information on logging in, see
section 3.5, Logging into JasperReports Server, on page 25.
Opt-in for JasperServer Heartbeat - The JasperReports Server heartbeat will help Jaspersoft create better products by
improving our understanding of customer installation environments. When the heartbeat is enabled, the server sends
anonymous system and version information to Jaspersoft via https. For more information, see section 5.11.1,
JasperReports Server Heartbeat, on page 36.
You can later enable or disable the heartbeat by modifying the jasperserver-pro/WEB-INF/applicationContext-logging.xml
file. For additional information on enabling and disabling the heartbeat component refer to the JasperReports Server
Administrator Guide.
2.1.10 Logging into JasperReports Server
You should now be ready to log into the server. For information on default login credentials, go to section 3.5, Logging into
JasperReports Server, on page 25.
2.2 Post-Installation Steps
2.2.1 Updates Made by the Installer During Installation
This sub-section lists the standard updates that the installer makes to your local environment if you install to existing
applications. When the installation completes, you can check to be sure the updates, or corresponding changes, were
successful.
Checking the Launch JasperReports Server Now check box may or may not start the server, depending on
your Tomcat and MySQL configuration choices. The start/stop scripts only control the bundled applications that
you chose to be installed. For more information, see Chapter 3, Starting and Stopping JasperReports
Server, on page 23.
Also, if you chose to view the Release Notes, JasperReports Server will not startup until you close the Release
Notes.
When you complete the evaluation or testing of your JasperReports Server instance, you should change the
administrative passwords and remove any sample end-users. Leaving the default passwords and end-users
weakens the security of your installation.
21
Updates made to the application server
If you installed to an existing Tomcat, the following modifications to the Tomcat environment were attempted:
Updates made to the MySQL database
If you installed to an existing MySQL database, new schemas and users are created in your database instance:
2.2.2 Installer Output Log File Location
The installer creates a log during installation that records information as the installation progresses. If you encounter any
problems when you install JasperReports Server, it can be helpful to look at the installer log for any potential errors. You can
find the installer log at <js-install>/install.log.
2.2.3 Installing a New License File
By default, JasperReports Server is installed with an evaluation license that expires a number of days after the software is
installed. Once the license expires, you can start the server, but you cannot log in.
To obtain a commercial license, contact Technical Support or your sales representative.
To upgrade the evaluation license to a commercial one, copy the commercial license file over the evaluation license file.
However, note that application servers have work directories where JSP files are compiled and cached and other objects are
stored. These directories can cause errors when updating to a new license. To avoid errors, Jaspersoft recommends that you
clear the work directory before upgrading your license. For instance, in Tomcat, you would do the following:
1. Change directory to <tomcat>/work.
2. Delete all the files in the directory.
By default, the license is found in the <js-install> directory. However, it can be located anywhere, so long as the -
Djs.license.directory Java Environment Variable points to its location (defined in the Tomcat startup scripts). Note that the
name of the file should be jasperserver.license. You may have to rename the new license file to this name.
Restart JasperReports Server and log in to see if the license is granting access properly. For information about license errors,
see the troubleshooting section A.3, License Not Found Error, on page 120.
File or Directory Updates
Windows: bin/setclasspath.bat
Linux: bin/setclasspath.sh
Modifies JAVA_OPTS to add -Djs.license.directory
Windows: bin/setenv.bat
Linux: bin/setevn.sh
This file gets newly created. Sets increased Java memory allocation
values to JAVA_OPTS. For additional settings, refer to section 5.9,
Setting Java JVM Options, on page 35.
Tomcat 5: common/lib
Tomcat 6: lib
Adds MySQL JDBC driver.
MySQL Updates Description
Database jasperserver created This is the JasperReports Server repository database. This database
holds all of system information, such as users, roles, datasources, and
report definitions.
Database user jasperdb created The JasperReports Server application uses this user to connect to the
database.
Sample database foodmart created (optional) Database created if install sample data option was chosen.
Sample database sugarcrm created (optional) Database created if install sample data option was chosen.
22
For additional license configuration options, refer to sections 5.8, Setting Up the JasperReports Server License, on
page 35 and 6.2, Setting Up the JasperReports Server License, on page 46.
2.2.4 License File for Existing Tomcat as Windows Service
If you are installing JasperReports Server into an existing Tomcat installation on a Windows system that is running as a
Windows Service and the license file is not in the default location (section 2.1.3), you will probably have to manually
configure Tomcat with the file location.
Follow the steps below to examine and/or update the license location:
1. Open the Tomcat configuration tool by right-clicking the Tomcat icon in your quick-launch bar (usually in the lower-right
corner of your desktop) or from the Windows menu at Start > All Programs > Apache Tomcat > Tomcat Configuration.
2. Click Configure and select the Java tab.
3. At the bottom of the Java Options field, enter the following:
-Djs.license.directory="<js-install>"
For example:
-Djs.license.directory="C:\Program Files\jasperreports-server-4.1"
4. Stop and restart the application server.
You should now be able to run JasperReports Server.
2.2.5 Checking your Java JVM Options
For both the bundled Tomcat and the existing Tomcat, the installer attempts to set Java JVM options to help with memory
allocation. You can double-check the values set to see that they are appropriate for your installation.
To check your Java JVM settings refer to section 5.9, Setting Java JVM Options, on page 35.
Starting and Stopping JasperReports Server
23
CHAPTER 3 STARTING AND STOPPING JASPERREPORTS SERVER
Using the Start/Stop Menu With Windows
Using Start/Stop Scripts Without Bundled Installation with Windows
Start/Stop Scripts for Linux
Using Start/Stop Apps With Mac OSX
Logging into JasperReports Server
Starting the Included Jaspersoft iReport Designer
JasperReports Server Log Files
3.1 Using the Start/Stop Menu With Windows
If you chose to install a bundled Tomcat and a bundled MySQL, then you can use the Windows Start menu items to start
and stop JasperReports Server.
To start or stop JasperReports Server, do the following:
From the Windows Start menu:
Click Start > All Programs > JasperReports Server 4.1 > JasperReports Server Service > Start Service.
Click Start > All Programs > JasperReports Server 4.1 > JasperReports Server Service > Stop Service.
Here is some extra information on the installed Tomcat and MySQL components. If you look at the Windows Services
Tool Panel, you can see entries for these components which are installed as Windows Services.
Go to the Windows Services Tool Panel:
Look for: jasperreportsTomcat
Look for: jasperreportsMySQL
Note that by default, these components are started automatically. This means that if your system is rebooted JasperReports
Server will be automatically restarted. You can set these components to manual if you dont wish them to automatically
start.
When JasperReports Server is running, in the Windows Task Manager you can see the following processes:
mysqld.exe
tomcat6.exe
24
3.2 Using Start/Stop Scripts Without Bundled Installation with Windows
If you used your own existing installation for one of either Tomcat or MySQL you can still use the Windows start/stop scripts
mentioned in the previous section. The scripts would only start the bundled application that you chose to have the installer
install.
For example, if you have an existing Tomcat and installed the bundled MySQL, the scripts and menus specified in the
previous section would only start and stop the MySQL application. For the existing Tomcat, you would use the existing start
and stop scripts provided by the Tomcat application.
3.3 Start/Stop Scripts for Linux
Starting and stopping JasperReports Server is typically done at the Linux command line. The following commands are meant
to be run in a Linux shell.
Start JasperReports Server:
cd <js-install>
./ctlscript.sh start
Stop JasperReports Server:
cd <js-install>
./ctlscript.sh stop
To start and stop individual components:
3.4 Using Start/Stop Apps With Mac OSX
After you complete the Mac OSX installation, you will typically find JasperReports Server installed to the following location:
/Applications/jasperreports-server-4.1
To Start JasperReports Server, locate this folder in Finder and double-click the following app:
jasperServerStart.app
To Stop JasperReports Server, locate this folder in Finder and double-click the following app:
jasperServerStop.app
Support for the Dock:
Using Finder, you may move the following apps into the Mac Dock in order to start, stop, and login to JasperReports
Server:
jasperServerStart.app
jasperServerStop.app
jasperServerLogin.app
cd <js-install>
./ctlscript.sh mysql start|stop
./ctlscript.sh tomcat start|stop
Starting and Stopping JasperReports Server
25
3.5 Logging into JasperReports Server
This section assumes that JasperReports Server is running. If it isnt, start it as described in the section above.
Log into JasperReports Server by entering the correct URL in your browsers address field and supplying the correct user
name and password. JasperReports Server supports Firefox, Internet Explorer, Chrome, and Safari. The URL depends upon
your application server. For the bundled Tomcat, use:
http://<hostname>:8080/jasperserver-pro
<hostname> is the name or IP address of the computer hosting JasperReports Server
8080 is the default port number for the Apache Tomcat application server. If you used a different port when installing
your application server, specify its port number when you connect to JasperReports Server.
Windows
Under Windows, you can launch the login page from the desktop of its host by clicking Start > All Programs >
JasperReports Server 4.1 > JasperReports Server Login.
Mac OSX
Under Mac, you can launch the login page by going to Finder and clicking the following script:
<js-install>/jasperServerLogin
For example: /Applications/jasperreports-server-4.1/jasperServerLogin
Support for the Dock:
From Finder, you can drag the <js-install>/jasperServerLogin.app to the Dock to handle logging in to JasperReports
Server using your default system browser.
If the login page appears, JasperReports Server has started properly. You may now login with the following credentials. These
default passwords should be changed for better system security.
If you installed the sample data, these additional sample end-users are also created. These users are non-administrative users
who have fewer system privileges than an administrative user. For better system security, delete these users when you stop
using them:
3.6 Starting the Included Jaspersoft iReport Designer
If you chose to install iReport as part of the JasperReports Server installation, you may start iReport from the Windows Start
menu. To do this, click Start > All Programs > JasperReports Server 4.1 > Start iReport Designer.
For Mac OSX, from Finder, you can double-click the iReport-mac.dmg file found in the root of the JasperReports Server
installation. This will bring up a new window where you can double-click the iReport Designer application.
User ID Password Description
superuser superuser System-wide administrator
jasperadmin jasperadmin Administrator for the default organization
joeuser joeuser Sample end-user
demo demo Sample end-user for the SuperMart Dashboard demonstration
26
To start on Mac OSX:
Double-click iReport-mac.dmg
Double-click Jaspersoft iReport Professional Designer
To start on Linux:
cd <js-install>
ireport/bin/iReportLoader.sh
3.7 JasperReports Server Log Files
Log files contain important information about how JasperReports Server is running. The log output goes to the following files:
You can configure the log outputs and logging levels in the log4j.properties file in the WEB-INF folder.
You can also change the logging levels while you are running JasperReports Server. Browse to the web page http://
<hostname>:8080/jasperserver-pro/log_settings.html. However, the settings on this page affect only the current session of
JasperReports Server. Logging levels revert to their settings in the properties files at the next startup.
For more information on system logging, see the JasperReports Server Administrator Guide.
Tomcat: <tomcat>/webapps/jasperserver-pro/WEB-INF/logs/jasperserver.log
JBoss: <jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/logs/jasperserver.log
GlassFish: <glassfish>/domains/domain1/autodeploy/jasperserver-pro.war/WEB-INF/logs/jasperserver.log
Uninstalling JasperReports Server
27
CHAPTER 4 UNINSTALLING JASPERREPORTS SERVER
Windows
Linux
Mac OSX
Uninstall Survey
4.1 Windows
Under Windows, click Start > All Programs > JasperReports Server 4.1 > Uninstall JasperReports Server to uninstall
JasperReports Server.
Note for Windows XP:
When uninstalling under Windows XP, it is typical to get a popup window that asks a question about which user account to run
as. In this case, you will need to uncheck the check box that says Protect my computer and data from unauthorized program
activity. Otherwise, the uninstaller will not execute.
4.2 Linux
Under Linux, the <js-install> folder includes an executable that removes JasperReports Server from the host. From the
command line as the root user (or any user with sufficient privileges), enter:
cd <js-install>
./uninstall
You are prompted whether to remove JasperReports Server. On your keyboard, press Y then press Enter to remove
JasperReports Server from this computer.
4.3 Mac OSX
Under Mac OSX, use Finder to go to the <js-install> folder and click the uninstall script. Do the following steps:
1. Navigate to the <js-install> folder.
For example: /Applications/jasperreports-server-4.1
28
2. Click the uninstall app to launch the uninstaller.
4.4 Uninstall Survey
After running the uninstaller, you are prompted to take an uninstall survey from Jaspersoft. Survey answers are anonymous
and help Jaspersoft improve the products we make. When you click Yes, the survey launches on the Jaspersoft web site in a
new browser window. Select all the reasons that led you to uninstall JasperReports Server, or enter a short explanation if none
match. Thank you for your feedback.
Installing the WAR File Distribution
29
CHAPTER 5 INSTALLING THE WAR FILE DISTRIBUTION
In addition to the installer binaries, the JasperReports Server application is distributed as a stand-alone WAR file distribution.
This distribution is packaged as a ZIP file. Customers who do not want to use the installer, or who have target configurations
other than those supported by the installer, should use the WAR file distribution.
Applications Supported by the WAR File Distribution
Obtaining the WAR File Distribution Zip
Unpacking the WAR File Distribution Zip
Introduction to Buildomatic Scripts
Pre-Installation Steps
Configuring the Buildomatic Scripts
Setting Up the JasperReports Server License
Setting Java JVM Options
Starting JasperReports Server
Troubleshooting Your JasperReports Server Configuration
Running the Import and Export Utilities
Pre-Test Validation mode of Auto-Install Scripts
Manual Steps for DB2
Manual Buildomatic Install Steps
30
5.1 Applications Supported by the WAR File Distribution
The instructions in this chapter and the following chapters support the following configurations:
For information on the specific versions of third party applications that are supported by the WAR file distribution ZIP refer to
the release notes for the distribution you are using. The release notes are found in the root of the unpacked distribution ZIP.
5.2 Obtaining the WAR File Distribution Zip
The WAR file distribution comes in a file named jasperreports-server-4.1-bin.zip in the compressed ZIP format. To download
the WAR file distribution, contact Jaspersoft technical support or your sales representative.
5.3 Unpacking the WAR File Distribution Zip
Once you have downloaded the WAR file distribution, you need to unpack it in order to access the files it contains.
Choose a top level directory location to unpack the ZIP file to. The ZIP file creates the directory jasperreports-server-4.1-bin.
Unpack to a directory such as Program Files or the root of the hard drive in Windows or your home directory in Linux. The
resulting location given in the following table will be referred to as <js-install> in this document:
5.4 Introduction to Buildomatic Scripts
The WAR file distribution contains a set of scripts known as the buildomatic scripts. These scripts automatically handle the
configuration and deployment of JasperReports Server.
These scripts are found in the buildomatic directory. They rely on the Apache Ant build tool and the Java JVM for execution.
Since JasperReports Server release 4.0, there are auto-install shell scripts included that automate the installation steps. These
scripts are located here:
<js-install>/buildomatic/js-install.bat
<js-install>/buildomatic/js-install.sh
Database App Server Instructions Located In
MySQL
PostgreSQL
Oracle
SQL Server
DB2
Apache Tomcat
JBoss
GlassFish
This chapter
WebSphere Chapter 7, Installing the WAR File for WebSphere, on page 61
WebLogic Chapter 8, Installing the WAR File for WebLogic, on page 75
Operating System Example Location Referenced As
Windows C:\Program Files\jasperreports-server-4.1-bin <js-install>
Windows C:\jasperreports-server-4.1-bin <js-install>
Linux /home/<user>/jasperreports-server-4.1-bin
or
/opt/jasperreports-server-4.1-bin
*
* Default location for the root user.
<js-install>
31
5.5 Pre-Installation Steps
5.5.1 Checking Your Java Installation
JasperReports Server is a Java application that requires either Java 1.5 or Java 1.6. Earlier Java versions such as Java 1.4 will
not work. You should check your installed Java version to see that it is at least Java 1.5. Additionally, JasperServer is certified
to run with the Sun Java Development Kit (JDK). Unfortunately, there are known bugs currently with other Java
implementations such as OpenJDK.
The buildomatic scripts are based on Apache Ant and they required the Java JDK. Therefore, you will need to verify that you
have the Java Development Kit (JDK) installed and not merely the Java Runtime Environment (JRE). The JDK has additional
tools and utilities required by Apache Ant.
You should also make sure that you have your JAVA_HOME variable set.
To check your Java version from the command line run:
java -version
5.5.2 About Bundled Apache Ant
The War File Distribution ZIP comes with a bundled version of Apache Ant so you do not need to download or install Ant.
The buildomatic scripts come with Windows and Linux batch scripts that are pre-configured to use the bundled version of
Apache Ant. The buildomatic scripts are called from the command line in the following manner:
The bundled Apache Ant is version 1.8.1. This version or higher is required if you want to run your own version of Ant.
The bundled Apache Ant has an additional jar that extends Ant functionality. This jar is: ant-contrib.jar. This jar enables
conditional logic in Ant. If you are running your own Ant you should copy the ant-contrib.jar to your Ant/lib folder.
5.5.3 Checking Your Application Server
To run JasperReports Server you will need to have an application server installed. The buildomatic scripts support automatic
deployment to the Tomcat, JBoss, and GlassFish application servers.
In the configuration step for the buildomatic scripts, you will need to specify the application server you are using and the
application server's home directory. Valid values will be:
tomcat5
tomcat6
jboss
glassfish2
glassfish3
5.5.4 Checking Your Database Server
To run JasperReports Server you will need to have a database available. The buildomatic scripts support automatic installation
to the MySQL, PostgreSQL, Oracle, SQL Server, and DB2 databases. When running the buildomatic scripts or performing
any manual installation, your database server should be running.
Windows: js-ant <target-name>
Linux: ./js-ant <target-name>
On Linux and Solaris, the js-ant commands may not be compatible with all shells. If you have errors, use the bash
shell explicitly. For more information, see section A.16, Troubleshooting on Solaris, on page 125.
32
In the configuration step for the buildomatic scripts, you will need to supply, at a minimum, the DB username, DB password,
and DB hostname information for your database. The default username and password for the installed database are:
The password is case-sensitive.
5.6 Configuring the Buildomatic Scripts
Since JasperReports Server release 4.0, there are auto-install shell scripts included that utilize buildomatic to automate the
installation steps. These scripts are located here:
<js-install>/buildomatic/js-install.bat
<js-install>/buildomatic/js-install.sh
You simply need to setup a properties file with your local settings.
5.6.1 Creating your Default Master Properties File
The buildomatic scripts read a file called default_master.properties in order to gather your application server path and your
database settings. You must create the default master properties file from one of the database-specific sample files provided.
1. Copy the file for your database:
2. And rename the file to:
<js-install>/buildomatic/default_master.properties
3. Make the buildomatic directory your current directory.
cd <js-install>/buildomatic
4. Edit the default_master.properties file to add the settings that are specific to your database and your application server.
The table below gives examples for each supported database. Be sure to replace the appServerDir property value with
the path to your installed application server.
User jasperserver
Password password
default password. Leaving it weakens the security of your installation.
Database Master Properties File
DB2 <js-install>/buildomatic/sample_conf/db2_master.properties
MySQL <js-install>/buildomatic/sample_conf/mysql_master.properties
Oracle <js-install>/buildomatic/sample_conf/oracle_master.properties
PostgreSQL <js-install>/buildomatic/sample_conf/postgresql_master.properties
SQL Server <js-install>/buildomatic/sample_conf/sqlserver_master.properties
Database Sample Property Values
DB2
appServerType=tomcat6 [tomcat, jboss, glassfish, skipAppServerCheck
*
]
appServerDir=c:\\apache-tomcat-6.0.26 [for example
]
dbUsername=db2admin
dbPassword=password
dbHost=localhost
For DB2 8.x, follow the instructions in section 6.3.5, Buildomatic: Change your Deployed
JDBC Driver, on page 51 after modifying these properties.
33
5.7 Installing JasperReports Server
Now that your default_master.properties file has been edited, you can install JasperReports Server.
Since JasperReports Server 4.0 there are Windows batch and Linux shell scripts that automatically handle the full installation
of JasperReports Server. These are referred to as the auto-install scripts.
MySQL
*
]
]
dbUsername=root
dbPassword=password
dbHost=localhost
Oracle
*
]
]
sysUsername=sys as sysdba
sysPassword=password
dbUsername=jasperserver
dbPassword=password
dbHost=hostname
PostgreSQL
*
]
]
dbUsername=postgres
dbPassword=postgres
dbHost=localhost
SQL Server
*
]
]
dbUsername=sa
dbPassword=sa
dbHost=localhost
If your app server runs on Java 1.5, follow the instructions in section 6.3.5, Buildomatic:
Change your Deployed JDBC Driver, on page 51 after modifying these properties.
* When the property appServerType is set to skipAppServerCheck, buildomatic skips any application server
validation. Use this setting when installing JasperReports Server with WebSphere and WebLogic, because they are not
directly supported by Buildomatic.
Backslashes in paths must be doubled in properties files, for example appServerDir=c:\\tomcat\\test. For
WebLogic 10, make sure there are no spaces in the path given in appServerDir.
Deploying to the DB2 Database. If you are deploying to the DB2 database, for more information see
section 5.15, Manual Steps for DB2, on page 41.
If you would like to run a pre-install validation test, you can run a command such as: js-install.bat test. For
more information, see section 5.12.3, Error Running Auto-Install Scripts (js-install.bat/sh), on page 37.
34
5.7.1 Windows Auto-Install
Make sure your database is running and run the following commands:
You may now proceed to the sections below on the JasperReports Server License, the Java JVM Options, and Starting
JasperReports Server (section 5.8, Setting Up the JasperReports Server License, on page 35). For troubleshooting, see
section 5.12, Troubleshooting Your JasperReports Server Configuration, on page 37.
5.7.2 Linux Auto-Install
Make sure your database is running and run the following commands:
JasperReports Server (section 5.8, Setting Up the JasperReports Server License, on page 35). For troubleshooting, see
section 5.12, Troubleshooting Your JasperReports Server Configuration, on page 37.
5.7.3 Auto-Install with Minimal Data
If you want to do a minimal installation that does not include any sample data, run the auto-install script with the minimal
option (Windows or Linux):
JasperReports Server (section 5.8, Setting Up the JasperReports Server License, on page 35).
5.7.4 Output Log Location
The auto-install script creates an output log that captures standard output and error output. If there are any problems during
the execution of the script or if you want to remember which options you chose, you can open the output log file.
The output log file is located here:
<js-install>/buildomatic/logs/js-install-<date>-<number>.log
5.7.5 Errors
If you encounter errors during the auto-install script execution, you should start by looking at the output log to see if you can
spot any errors. Additionally, you should refer to the Troubleshooting section 5.12, Troubleshooting Your JasperReports
Server Configuration, on page 37.
Commands Description
cd <js-install>/buildomatic Go to the buildomatic scripts directory.
js-install.bat Install JasperReports Server, create sample data and
sample databases (foodmart and sugarcrm).
js-install.sh Install JasperReports Server, create sample data and
sample databases (foodmart and sugarcrm).
js-install.bat minimal Install JasperReports Server with minimal data (for
Windows).
js-install.sh minimal Install JasperReports Server with minimal data (for Linux).
35
If you need to modify values in your default_master.properties file, you can simply edit the file. When the auto-install
script is run again, the new values will be used.
5.8 Setting Up the JasperReports Server License
JasperReports Server commercial editions require a license to run. The JasperReports Server WAR file distribution comes
with an evaluation license that is valid only for a number of days. Contact Technical Support or your sales representative to get
your commercial license.
The JasperReports Server license file is included in the root of the <js-install> directory and is named jasperserver.license. It
specifies the terms of your license, such as the following:
Expiration date, number of users, and/or number of CPUs
Also, features licensed separately from the basic commercial license, such as multi-tenancy
Jaspersoft receives information about your system periodically. The information is used only to monitor compliance with your
license. No personal information is collected or transmitted.
5.8.1 License Configuration for All Application Servers
At startup time, JasperReports Server automatically looks for the jasperserver.license file in the home directory of the system
user that is running the application server. So, all that is required is to determine the location of the application user home
directory and to copy the Jasperserver license file to this location.
Copy the file:
<js-install>/jasperserver.license
To:
5.8.2 Alternative JasperReports Server License Set Up
If you prefer your license to be located in a directory of your own choosing, you can modify your application server startup
script and set a JAVA_OPT value to explicitly point to that directory.
For this configuration, refer to one of the following sections: 6.2.2, Alternate License Setup for Tomcat, on page 47 or
6.2.4, Alternate License Location for Existing Tomcat as a Windows Service, on page 48.
5.9 Setting Java JVM Options
JasperReports Server requires that your Java JVM runtime options be set to values larger than the typical Java default values.
For Tomcat and JBoss these values can be directly set by editing the shell scripts which start the application server. See
section 6.1.1, Tomcat and JBoss JVM Options, on page 43 for detailed steps.
For GlassFish, you can set the JVM options using the asadmin utility or by editing the domain.xml config directly. See
section 6.1.4, GlassFish JVM Options, on page 45 for detailed steps.
Windows: C:\Documents and Settings\<user>\jasperserver.license
Windows 7: C:\Users\<user>\jasperserver.license
Windows 7: C:\jasperserver.license (if Win 7 Existing Tomcat as a Windows Service)
Linux: /home/<user>/jasperserver.license
36
5.10 Starting JasperReports Server
To run JasperReports Server start your application server with one of the following commands:
If your application server is set up as a Windows service, launch it through the Windows Start menu, for example Start > All
Programs > Apache Tomcat > ...
To view the JasperReports Server application logs, see section 3.7, JasperReports Server Log Files, on page 26.
If JasperReports Server started up cleanly you should be able to login.
Login by going to the following URL:
Example:
http://localhost:8080/jasperserver-pro
http://jasperserver.example.com:8080/jasperserver-pro
The login page should appear after taking some time to compile the necessary JSP file.
Use the following credentials to log into the system:
If you logged in successfully, your JasperReports Server home page appears.
Refer to the JasperReports Server User Guide to begin adding reports and other objects to the server.
5.11.1 JasperReports Server Heartbeat
Upon first login to a newly installed JasperReports Server, you will be asked whether to opt-in to the JasperReports Server
Heartbeat or not.
To opt-in, click OK. To opt-out, click the check box to remove the check and click OK.
The heartbeat helps Jaspersoft create better products by improving our understanding of customer installation environments. If
you choose to enable the heartbeat, at server startup time information like the following will be sent to Jaspersoft via an
HTTPS call:
Operating System type and version
JVM type and version
Application Server type and version
Database type and version
JasperReports Server type and version
Unique, anonymous identifier value
Tomcat: <tomcat>/bin/startup.bat (Windows) or <tomcat>/bin/startup.sh (Linux)
JBoss: <jboss>/bin/run.bat (Windows) or <jboss>/bin/run.sh (Linux)
GlassFish: asadmin start-domain domain1
37
You can also manually enable or disable the heartbeat by modifying the jasperserver-pro/WEB-INF/applicationContext-
logging.xml file. To disable, set the enabled property to false as shown below:
<property name="enabled" value="false"/>
For additional information on enabling and disabling the heartbeat component refer to the JasperReports Server Administrator
Guide.
5.12 Troubleshooting Your JasperReports Server Configuration
5.12.1 JasperReports Server Startup Problems
When trying to run a new JasperReports Server instance, the most typical issue that users encounter are problems with the
database configuration.
These problems are typically related to having incorrect configurations within the database configuration files or in the
application server configuration files.
For more information on resolving these types of errors, refer to troubleshooting section A.2, Database Connectivity
Errors, on page 118.
5.12.2 Error Running a Report
If you have trouble running reports in your new JasperReports Server instance, refer to troubleshooting section A.5, Error
Running a Report, on page 121.
5.12.3 Error Running Auto-Install Scripts (js-install.bat/sh)
If you received an error when you executed the js-install.bat or js-install.sh script, hopefully the error message was clear
enough to allow you to make changes to eliminate the error. Common errors would be such things as typos in the path for the
application server, or misspelling the hostname or password for the database.
The output log is found at:
<js-install>/buildomatic/logs
It is usually necessary to scroll back into the error message lines and see if there was an original error reported (that later
caused additional errors). During an auto-installation of JasperReports Server, a Java based import operation is executed in
order to put minimal and/or sample data in place.
Unfortunately, Java stack traces can be very long. Additionally, JasperReports Server uses the Spring framework to flexibly tie
application components together. An error that involves a Spring initialization XML file can also cause a long stack trace.
Again, it will be important to try and isolate the first error encountered by the auto-installation steps.
Recreate your default_master.properties settings
If you need to make a correction to your default_master.property files, you can make the edit and re-run the js-install script.
The js-install script will always use the most current values found in the default_master.properties file.
To help isolate errors, the auto-install scripts can be run in test mode. See subsequent sections for details.
5.12.4 Auto-Install Script Test Mode
The auto-install scripts can be run in a test mode using the test option. This can help debug issues such as a mis-typed
database password. Your system will not be altered when executing in test mode.
38
Run auto-install Script in Validation Test Mode
To run the auto-install scripts in test mode, do the following:
In test mode, the js-install scripts will check your settings to see if any setting can be determined to be incorrect. The
application server location will be validated and the ability to connect to the specified database will be validated.
Note if connecting to a Cloud database instance
It is typical for a cloud database instance (such as Amazon EC2) to have all non-used IP ports disabled. When the auto-install
script runs it makes a validation call to the database hostname. This validation call uses the built-in ant operation
<isreachable>. This operation is typically carried out similar to a network ping and may cause a hang issue if the port is
not available. In this case, the validateHost step can be commented out in the buildomatic/validation.xml file. See
the comment in the do-pre-install-test target.
5.12.5 Auto-upgrade Scripts
The same logic listed above for the auto-install scripts also applies to the auto-upgrade scripts. These scripts can also be
run in test mode.
5.12.6 Auto-Install Script Output Log File
When an auto-install or auto-upgrade script is executed it will generate an output log. This log is located at:
<js-install>/buildomatic/logs
5.13 Running the Import and Export Utilities
The buildomatic scripts automatically configure the database information needed by the buildomatic import and export
functionality. This functionality is invoked via ant targets used by buildomatic and located in the following directory:
This section describes the Ant targets and parameter setting you need to specify in order to send the standard options to the
import and export commands.
For complete information on the standard import-export options refer to the JasperReports Server Administrator Guide.
5.13.1 Running Export from Buildomatic
The export target for ant has the following syntax:
The export file format can be a ZIP file or it can be a set of files under a new directory name. If you specify the .zip extension
for your output filename then a ZIP archive will automatically be created. Otherwise, a directory with files and sub-directories
will be created as a non-compressed set of files.
cd <js-install>/buildomatic Go to the buildomatic scripts directory
js-install.bat test Run auto-install script in test mode (Windows)
js-install.sh test Run auto-install script in test mode (Linux)
Windows: js-ant export -DexportFile=<filename> -DexportArgs="<export-options>"
Linux: ./js-ant export -DexportFile=<filename> -DexportArgs=\"<export-options>\"
39
The exportArgs argument requires double quotes (") and can contain more than one export option, as shown in the Windows
examples below:
On Linux, all double quotes (") and other characters such as the | separator for organization names must be escaped with a
backslash (\). In addition, when giving a list of usernames, it must be enclosed in single quotes ('), as shown in the Linux
example below:
5.13.2 Running Import from Buildomatic
The import target for ant has the following syntax:
The imported file is handled as a ZIP archive if its name ends in .zip, otherwise it will be handled as a directory. The
importArgs argument is optional, it can contain more than one import option. On Linux, all double quotes (") must be
escaped with a backslash (\).
The following examples on Windows are typical import commands:
js-ant export-help-pro
js-ant export -DexportFile=my-domains.zip
-DexportArgs="--uris /organizations/organization_1/Domains"
js-ant export -DexportFile=my-reports-and-users.zip
-DexportArgs="--uris /organizations/organization_1/reports
--users jasperadmin|organization_1,joeuser|organization_1"
js-ant export -DexportFile=my-datasources
-DexportArgs="--uris /organizations/organization_1/datasources --roles ROLE_USER"
js-ant export -DexportFile=js-everything.zip -DexportArgs="--everything"
./js-ant export-help-pro
./js-ant export -DexportFile=my-reports-and-users.zip
-DexportArgs=\"--uris /organizations/organization_1/reports
--users 'jasperadmin\|organization_1,joeuser\|organization_1'\"
Windows: js-ant import -DimportFile=<filename> [-DimportArgs="<import-options>"]
Linux: ./js-ant import -DimportFile=<filename> [-DimportArgs=\"<import-options>\"]
js-ant import-help-pro
js-ant import -DimportFile=my-reports.zip
js-ant import -DimportFile=my-datasources -DimportArgs="--update"
40
The following examples on Linux are typical import commands:
5.13.3 Running the Import Export Shell Scripts
The import-export shell scripts used to be found in the scripts folder. They are now found in the buildomatic folder.
You can find them here:
<js-install>/buildomatic/js-export.bat/.sh
<js-install>/buildomatic/js-import.bat/.sh
The options available from these scripts can be displayed by typing:
js-export.bat/sh --help
js-import.bat/sh --help
These scripts are shell scripts and are distinct from the buildomatic import-export functionality which is auto-configured
(using the default_master.properties file).
To use these shell scripts, you must normally configure them yourself to, for instance, use the correct JDBC driver for your
database. If use these shell scripts from a binary installer installation then they should already be properly configured.
For information on configuring and running the import-export shell scripts, see Chapter 14, Configuring the Import-
Export Utilities, on page 111.
5.14 Pre-Test Validation mode of Auto-Install Scripts
The auto-install scripts can run in a test (validation) mode. In this mode, no changes will be made to you system.
5.14.1 Additional Command for Buildomatic Settings
Whenever you change your default_master.properties file and re-run the auto-install scripts (or any other buildomatic target),
your generated configuration settings are automatically updated. The generated settings are found in this location:
<js-install>/buildomatic/build_conf/default
The settings are automatically regenerated based on the new timestamp found on the properties file.
If you want to explicitly cause your generated configuration to be regenerated, you can run the following buildomatic targets:
js-ant clean-config
js-ant gen-config
./js-ant import-help-pro
./js-ant import -DimportFile=my-reports.zip
./js-ant import -DimportFile=my-datasources.zip -DimportArgs=\"--update\"
js-install.bat test Run a validation test of the JasperReports Server install (for
Windows)
js-install.sh test Run a validation test of the JasperReports Server install (for
Linux)
41
The first target will clear the configuration template files found in buildomatic/build_conf/default directory. The second will
re-build the configuration settings.
5.15 Manual Steps for DB2
The buildomatic scripts are not able to automatically connect to a remote DB2 database and carry out Admin operations. For
this reason, it is necessary to manually create the databases.
The DB2 client software, db2 or db2cmd, can be used to interact with DB2.
Use commands similar to the ones below:
Further considerations:
If you are using DB2 8.1, you should set the LOGFIL_SIZ parameter to at least 3000 to avoid possible log file errors while
loading the foodmart database. Configure your foodmart database right after creating it by using Control Center.
If JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts:
<db2>/SQLLIB/java/db2jcc.jar
Now, you may continue with the normal buildomatic steps in section 5.7, Installing JasperReports Server, on page 33.
5.15.1 Creating Databases Manually
If you encounter an error when running one of the create db targets (create-sugarcrm-db, create-foodmart-db, or create-js-db)
you may create the JasperReports Server database manually using the database administration tool for your particular database
type. After creating the database, you can continue with the remaining buildomatic steps. Additionally, keep in mind that the
sugarcrm and foodmart databases are optional, sample databases.
For procedures on MySQL, Oracle, and DB2, see section 6.4, Additional Notes on Databases, on page 52.
5.16 Manual Buildomatic Install Steps
These are the older manual target execution steps (before the implementation of the auto-install shell scripts in JasperReports
Server version 4.0). You can use this section if you are not able to use the auto-install scripts.
Older manual buildomatic install target steps:
These commands exist as a convenience. Whenever default_master.properties is edited the resulting configuration
templates are regenerated automatically (this is based on the updated time-stamp associated with the edited file).
db2 create database jsprsrvr using
codeset utf-8 territory us
Creates the JasperReports Server database with required
settings.
db2 create database sugarcrm
db2 create database foodmart
(Optional) Creates the sample databases.
js-ant create-js-db
js-ant create-sugarcrm-db
js-ant create-foodmart-db
Creates the JasperReports Server and sample databases.
For DB2, see section 5.8, Setting Up the JasperReports
Server License, on page 35.
42
js-ant load-sugarcrm-db
js-ant load-foodmart-db
js-ant update-foodmart-db
(Optional) Loads sample data into the sample databases.
js-ant init-js-db-pro
js-ant import-minimal-pro
Initializes database, loads core application data.
js-ant import-sample-data-pro (Optional) Loads the demos that use the sample data.
js-ant deploy-webapp-pro Configures and deploys the WAR file to Tomcat, JBoss, or
Glassfish,
For WebLogic and WebSphere, skip this step and return to
the instructions in the corresponding chapter.
On Linux and Solaris, the js-ant commands may not be compatible with all shells. If you have errors, use the
bash shell explicitly. For more information, see section A.16, Troubleshooting on Solaris, on page 125.
Additional Installation Information
43
CHAPTER 6 ADDITIONAL INSTALLATION INFORMATION
Setting JVM Options for Application Servers
Additional Buildomatic Configuration Information
Additional Notes on Databases
Notes on the Hibernate Properties File
Notes on Database Connections for Tomcat
Notes on Data Source Definitions for JBoss
Notes on Database Connections for GlassFish
Report Scheduling Configuration with Quartz
Notes on Updating XML/A Connection Definitions
6.1 Setting JVM Options for Application Servers
JasperReports Server runs better with certain Java options for the JVM in which its application server is running. The options
you need and how you set them depends on your version of Java, your application server, and how it is deployed. In addition,
there is a setting to support localization when running with an Oracle database.
The settings in this section apply specifically to the Sun JVM. Other JVMs may or may not have equivalent settings.
6.1.1 Tomcat and JBoss JVM Options
JasperReports Server is supported on Java 1.5 and 1.6. If you are using Java 1.6, there are some additional JVM settings to
avoid conflicts with JasperReports Server's AXIS-based web service classes. These conflicts could cause web services and the
resources which rely on them to fail (such as analysis XML/A connections). Similarly, JBoss 4.2 includes a web service that
conflicts with AXIS-based web service classes and requires the same additional settings.
JVM Options on Windows
Tomcat file <tomcat>/bin/setenv.bat (or <tomcat>/bin/setclasspath.bat)
JBoss file <jboss>/bin/run.bat
44
Add your JAVA_OPTS setting directly below the following lines:
6.1.2 Bundled Tomcat as a Windows Service JVM Options
As of release 4.0, the bundled Tomcat application that is included with the Windows installer binary is installed as a
Windows Service by default. Therefore, the steps required to change JVM options are different than they were in earlier
installer versions.
The location where you will make the JVM edits is different. And after your edits are complete you will need to re-install the
Tomcat service.
Here are the steps, for instance, to increase the Java heap values:
cd <js-install>/apache-tomcat/bin
Edit service.bat
Options for
Java 1.5 and
Java 1.6
set JAVA_OPTS=%JAVA_OPTS% -Xms1024m -Xmx2048m -XX:PermSize=32m
-XX:MaxPermSize=128m -Xss2m -XX:+UseConcMarkSweepGC
-XX:+CMSClassUnloadingEnabled
For Oracle set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true
Additional
options for
Java 1.6 or
JBoss 4.2
set JAVA_OPTS=%JAVA_OPTS%
-Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl
-Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl
-Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl
-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
JVM Options on Linux
Tomcat file <tomcat>/bin/setclasspath.sh or <tomcat>/bin/setenv.sh
JBoss file <jboss>/bin/run.sh
Options for
Java 1.5 and
Java 1.6
export JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m -XX:PermSize=32m
-XX:+CMSClassUnloadingEnabled"
For Oracle export JAVA_OPTS="$JAVA_OPTS -Doracle.jdbc.defaultNChar=true"
Additional
options for
Java 1.6 or
JBoss 4.2
export JAVA_OPTS="$JAVA_OPTS
-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl"
Add JVM Options Here
<tomcat>/bin/setclasspath.bat set JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed
<tomcat>/bin/setclasspath.sh JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed
<jboss>/bin/run.bat
<jboss>/bin/run.sh
set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% or
export JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME"
<tomcat>/bin/setenv.bat or
<tomcat>/bin/setenv.sh
JAVA_OPTS setting can go anywhere in this file.
JVM Options on Windows, continued
45
Look for the following line (first line of two that set JVM options):
Update the line above to increase the Java heap:
-Xms1024M;-Xmx2048M
Because Tomcat is installed as a service, you will need to re-install the service. From a Windows cmd shell:
Note: After running each of the commands above (in Windows XP testing), the cmd shell was closed after the commands were
executed. Also, note that the Tomcat service is removed and then installed. It is left in a running state after the INSTALL
command is executed. You can make these updates while the services are running or not. But, you should stop and restart both
MySQL and Tomcat after completing this work. You can use the normal JasperReports Server menu items to stop and start the
services.
6.1.3 Existing Tomcat as a Windows Service JVM Options
If you installed to an existing Tomcat that is running as a Windows service, then you would typically add the Java options for
JasperReports Server to the Java Tab of the Tomcat Properties dialog:
1. Launch the Tomcat configuration application from the Windows Start menu:
Start > Programs > Apache Tomcat > Configure Tomcat
2. In the Apache Tomcat Properties dialog, click the Java tab.
3. In the Java Options field, add your JAVA_OPTS values according to the table above.
Enter only the options preceded by -X or -D, not set JAVA_OPTS=%JAVA_OPTS%.
Enter only one java option setting per line.
4. For instance, add as shown here:
5. Click Apply, then click OK.
6.1.4 GlassFish JVM Options
For GlassFish, the JVM settings are identical for Java 1.5 and Java 1.6. The following sections show how to set the JVM
options for GlassFish either through the command line or in a configuration file.
"%EXECUTABLE%" //US//%SERVICE_NAME% --Startup auto --JvmOptions "-Xms128M;-Xmx512M;
-Xss2M;-Dcatalina.base=%CATALINA_BASE%;-Dcatalina.home=%CATALINA_HOME%;
-Djava.endorsed.dirs=%CATALINA_HOME%\endorsed" --StartMode jvm --StopMode jvm
cd <js-install>\apache-tomcat\scripts
serviceinstall.bat REMOVE
serviceinstall.bat INSTALL
-Xms1024m
-Xmx2048m
-XX:PermSize=32m
-XX:MaxPermSize=128m
-Xss2m
46
6.1.4.1 Setting GlassFish JVM Options with asadmin Command
First make sure your GlassFish instance is up and running, then run the following command (enter as a single line):
If you are not using an Oracle database, you can omit the last option in example above.
Now, restart the application server with the following commands:
asadmin stop-domain domain1
asadmin start-domain domain1
When running the asadmin create-jvm-options command above, you may see some error messages such as the
following:
This message indicates that one of the options specified was already set in the JVM. The command will succeed for all other
JVM options on the command line. No further action is necessary.
6.1.4.2 Setting GlassFish JVM Options by Editing domain.xml
Open the <glassfish>/domains/domain1/config/domain.xml configuration file for editing, and add the following lines to the
section entitled java-config:
If you are not using an Oracle database, you can omit the last option in example above.
If you are modifying the settings for a running instance of GlassFish, you must restart the application server with the following
commands:
asadmin stop-domain domain1
asadmin start-domain domain1
The commercial version JasperReports Server requires a license to run. The JasperReports Server WAR file distribution
comes with an evaluation license that is valid for 30 days. Please contact Technical Support or your sales representative to get
your commercial license.
asadmin create-jvm-options -Xms1024m:-Xmx2048m:-XX\:PermSize=32m:
-XX\:MaxPermSize=128m:-Xss2m:-XX\:+UseConcMarkSweepGC:
-XX\:+CMSClassUnloadingEnabled:-XX\:+CMSPermGenSweepingEnabled:
-Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl:
-Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl:
-Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl:
-Doracle.jdbc.defaultNChar=true
[exec] CLI167 Could not create the following jvm options. Options exist:
[exec] -Xmx512m
[exec] CLI137 Command create-jvm-options failed.
<jvm-options>-Xms1024m -Xmx2048m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2
-XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled
-Doracle.jdbc.defaultNChar=true
</jvm-options>
47
The JasperReports Server license file is named jasperserver.license and is found in the <js-install> directory. See 5.8, Setting
Up the JasperReports Server License, on page 35 for more information about the license.
Under Windows, since the JasperReports Server 4.0 release, both Tomcat and MySQL bundled components are installed as
Windows Services by default. You can see the status of these services in the Administrative Services panel.
Under Windows, these components are still executed from the <js-install> directory location. For instance, the bundled
Apache Tomcat would be installed to this location by default:
C:\Program Files\jasperreports-server-4.1\apache-tomcat (Windows XP)
C:\Program Files (x86)\jasperreports-server-4.1\apache-tomcat (Windows 7 64bit)
6.2.1 License Configuration for Application Servers
JasperReports Server will recognize the license file when it is located in the home directory of the user that runs your
application server.
6.2.2 Alternate License Setup for Tomcat
If your license will not be located in the home directory of the application server user, then you can set a JAVA_OPT value to
explicitly point to your license.
On Windows:
1. In the file <tomcat>/bin/setclasspath.bat, locate the following line:
set JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed
Alternatively, create an empty file called <tomcat>/bin/setenv.bat.
2. Below that line or in the new file, insert the following line:
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="<js-install>"
For example:
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-bin"
On Linux:
1. In the file <tomcat>/bin/setclasspath.sh, locate the following line:
JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed
Alternatively, create an empty file called <tomcat>/bin/setenv.sh.
2. Below that line or in the new file, insert the following line:
export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=<js-install>"
For example:
export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-bin"
6.2.3 Alternate License Setup for Bundled Tomcat as a Windows Service
As of release 4.0, the bundled Tomcat application that is included with the Windows installer binary is installed as a
Windows Service by default. Therefore, the steps required to change the license location are different than they were in earlier
installer versions.
Copy: <js-install>/jasperserver.license
To: C:\Documents and Settings\<user>\jasperserver.license (Windows XP)
C:\Users\<user>\jasperserver.license (Windows 7)
C:\jasperserver.license (Window 7, Existing Tomcat as Windows Service. User SYSTEM.)
/home/<user>/jasperserver.license (Linux)
/Users/<user>/jasperserver.license (Mac OSX)
48
The location where you will make the JVM edits is different. And after your edits are complete you will need to re-install the
Tomcat service.
Here are the steps to change the JasperReports Server bundled Tomcat to point to a different jasperserver.license location:
cd <js-install>/apache-tomcat/bin
Edit service.bat
Look for the following line (second line of two that set JVM options):
Update the line above to point to this example license location:
-Djs.license.directory=C:\MyLicenses
Because Tomcat is installed as a service, you will need to re-install the service. From a Windows cmd shell:
Note: After running each of the commands above (in Windows XP testing), the cmd shell was closed after the commands were
executed. Also, note that the Tomcat service is removed and then installed. It is left in a running state after the INSTALL
command is executed. You can make these updates while the services are running or not. But, you should stop and restart both
MySQL and Tomcat after completing this work. You can use the normal JasperReports Server menu items to stop and start the
services.
6.2.4 Alternate License Location for Existing Tomcat as a Windows Service
Windows XP:
If you have an existing Tomcat as a Windows Service under Windows XP, you may be required to put your license in a special
location if you want it to be picked up by default. This has been reported by some customers. The location would be the
following:
C:\Documents and Settings\LocalService\jasperserver.license
This location can be unusual because the LocalService directory is not displayed when you click on the Documents and
Settings directory in Windows Explorer. If you go to the Explorer Address Bar and type LocalService, it will be displayed.
You can copy the jasperserver.license file to this location if your Tomcat as a Windows Service is unable to find the license in
the Documents and Settings/<user> location described in the sections above.
Windows 7:
If you have an existing Tomcat as a Windows Service under Windows 7, then you should be able to copy your license to the
root of the C: drive. This is the home folder for the SYSTEM user. The location would be the following:
C:\jasperserver.license
6.2.5 Alternate License Setup for JBoss
If your license will not be located in the home directory of the application server user, you can set a JAVA_OPT value to
explicitly point to your license.
"%EXECUTABLE%" //US//%SERVICE_NAME% ++JvmOptions
"-Djs.license.directory=C:\Program Files\jasperreports-server-4.1;
-XX:PermSize=32m;-XX:MaxPermSize=128m;-XX:+UseConcMarkSweepGC;
-XX:+CMSClassUnloadingEnabled" "-Djava.io.tmpdir=%CATALINA_BASE%\temp;
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;
-Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties"
cd <js-install>\apache-tomcat\scripts
serviceinstall.bat REMOVE
serviceinstall.bat INSTALL
49
On Windows:
1. In the file <jboss>/bin/run.bat, locate the following line:
set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME%
2. Below that line, insert the following line:
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="<js-install>"
For example:
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-bin"
On Linux:
1. In the file <jboss>/bin/run.sh, locate the following line:
export JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME"
2. Below that line, insert the following line:
export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=<js-install>"
For example:
export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-bin"
6.2.6 Additional Evaluation Licenses
The Commercial version of JasperReports Server has some of its main features controlled by the jasperserver.license file. The
default evaluation license included with JasperReports Server is for the Enterprise edition. This edition has all Commercial
features enabled.
There is now a folder included in the release which holds evaluation licenses for different editions. This folder is located here:
<js-install>/eval-licenses
If you would like to evaluate how JasperReports Server will operate under a different license type, you can copy one of the
licenses found in the /eval-licenses folder on top of your existing license. You would need to rename the license to
jasperserver.license. You would then need to restart your server.
It is not recommended that you use these evaluation licenses if you are already running with a Commercial license (that is, a
non-evaluation license typically received from a Sales Representative).
6.3 Additional Buildomatic Configuration Information
The Ant-based buildomatic scripts contain support files that allow for the setup and configuration of a number of databases
and application servers. Here are some pointers to the locations and content of some of these files.
6.3.1 Buildomatic: Generated Property Files
After you set your database and application server property values, you initiate buildomatic which automatically generates the
database and application server configuration files needed to prepare for a JasperReports Server installation.
You will find the generated property files in the following location:
Here are some of the key configuration files:
js.jdbc.properties
js.quartz.properties
js-glassfish-ds.xml
js-jboss-ds.xml
maven_settings.xml - (used for source code build)
More generated property files:
50
<js-install>/buildomatic/build_conf/default/webapp
In this directory you will find config files such as:
META-INF/context.xml
WEB-INF/hibernate.properties
WEB-INF/js.quartz.properties
The autogenerated files above are removed if you run the buildomatic target: clean-config. You can then regenerate them
by running the target: gen-config. (Also, after running clean-config, any subsequent target will regenerate the
configuration files.)
6.3.2 Buildomatic: SQL Scripts Location
Buildomatic comes with SQL scripts and other utilities that support a number of databases. Here is where these files are found:
<js-install>/buildomatic/install_resources/sql/
Here is an example of some of the key files (same pattern for additional databases):
<js-install>/buildomatic/install_resources/sql/mysql/js-pro-create.ddl
<js-install>/buildomatic/install_resources/sql/mysql/quartz.ddl
<js-install>/buildomatic/install_resources/sql/mysql/upgrade-mysql-3.7.0-4.0.0-pro.sql
<js-install>/buildomatic/install_resources/sql/mysql/js-pro-drop.ddl
<js-install>/buildomatic/install_resources/sql/mysql/drop-quartz.ddl
6.3.3 Buildomatic: Database Creation Statements Location
For most databases the buildomatic scripts are able to create the metadata repository database used by JasperReports Server.
This is the database where the data defining users, roles, data sources, reports, OLAP views, domains, and other data are
stored. This database is normally named jasperserver.
Buildomatic attempts to create the jasperserver database via JDBC when the create-js-db target is executed.
The scripts and property files used to create the jasperserver database are here:
<js-install>/buildomatic/conf_source/db/
mysql/scripts.properties
postgresql/scripts.properties
oracle/scripts.properties
(same pattern for additional databases)
6.3.4 Buildomatic: JDBC Driver Locations
Buildomatic has default JDBC drivers for each supported database. These JDBC drivers are located here:
You can run these scripts manually by copying them to a location where your database client software is located.
Database Buildomatic JDBC Driver Location
DB2 <js-install>/buildomatic/conf_source/db/db2/jdbc/db2jcc-9.5.jar (for DB2 9.x)
<js-install>/buildomatic/conf_source/db/db2/jdbc/alt-drivers/db2jcc-8.2.jar (for DB2 8.x)
MySQL <js-install>/buildomatic/conf_source/db/mysql/jdbc/mysql-connector-java-5.1.10.jar
Oracle <js-install>/buildomatic/conf_source/db/oracle/jdbc/ojdbc5.11.2.0.jar
<js-install>/buildomatic/conf_source/db/oracle/jdbc/ojdbc14.10.2.0.jar
PostgreSQL <js-install>/buildomatic/conf_source/db/postgresql/jdbc/postgresql-9.0-801.jdbc3.jar
51
To change the jdbc driver used, you can update your default_master.properties file and add the following information:
Example for Oracle 5 driver:
maven.jdbc.artifactId=ojdbc5
maven.jdbc.version=11.2.0
The buildomatic scripts will automatically copy the appropriate JDBC driver to your application server when you run the
deploy-webapp-pro target. Here are some typical locations where you can expect the JDBC driver to by copied:
6.3.5 Buildomatic: Change your Deployed JDBC Driver
When you run the buildomatic target deploy-webapp-pro the JDBC driver for your specified database will be copied to
your application server.
However, you may find, for instance, that there is a different or more up to date JDBC driver that you would prefer to use. You
can change the driver used by updating your default_master.properties file:
<js-install>/buildomatic/default_master.properties
You will set the maven.jdbc.artifactId and the maven.jdbc.version to point to the name of the driver you would like to use:
maven.jdbc.artifactId=<first-part-of-filename>
maven.jdbc.version=<version-part-of-filename>
The buildomatic scripts will look in the default jdbc folder location that is associated with your DB type:
<js-install>/buildomatic/conf_source/db/<dbType>/jdbc
Change the deployed JDBC driver example for Oracle:
Say, for example, you would like to use the Oracle4 JDBC driver. You would like this driver to be automatically deployed to
your application server when you run the deploy-webapp-pro target. However, we can see by the settings in the following
file that the default driver that will be used will be the following:
<js-install>/buildomatic/conf_source/db/oracle/db.properties
So the driver used is: ojdbc5-11.2.0.jar
To change the driver used, edit your default_master.properties file, add the following lines:
Now, when you run deploy-webapp-pro, the 14 driver will be used.
Note: You should also manually update the JDBC driver version found in the <js-install>/buildomatic/conf_source/appro/lib
folder. (This is only in the case where you plan to run the js-import.bat/.sh, js-export.bat/.sh shell scripts.)
SQL Server <js-install>/buildomatic/conf_source/db/sqlserver/jdbc/sqljdbc-1.6.jar (for Java 6)
<js-install>/buildomatic/conf_source/db/sqlserver/jdbc/sqljdbc-1.5.jar (for Java 5)
Vertica (as a data
source only)
<js-install>/buildomatic/conf_source/db/vertica/jdbc/vertica_3.5_jdk_5.jar
Tomcat 5: <tomcat>/common/lib
Tomcat 6: <tomcat>/lib
JBoss: <jboss>/server/default/lib
GlassFish: <glassfish>/domains/domain1/lib/ext
Database Buildomatic JDBC Driver Location
52
To deploy other JDBC JAR files:
You can use the same logic above to deploy other JDBC drivers. You would put them in the same location as the existing
JDBC drivers for your DB type. Then, make sure that the property settings and the JDBC driver name exactly match.
6.3.6 Buildomatic: JasperReports Server WAR File Location
Buildomatic takes the JasperReports Server WAR file from the root of the <js-install> directory:
<js-install>/jasperserver-pro.war
When you run the deploy-webapp-pro target, buildomatic takes the war archive and unpacks it into your application server.
Next, the database configuration files needed by the application server are copied to the appropriate locations. For instance, in
the case of Tomcat:
<js-install>/jasperserver-pro.war
Unpacked and copied to <tomcat>/webapps/jasperserver-pro/*
<js-install>/buildomatic/build_conf/default/webapp/META-INF/context.xml
Copied to <tomcat>/webapps/jasperserver-pro/META-INF/context.xml
<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties
Copied to <tomcat>/webapps/jasperserver-pro/WEB-INF/hibernate.properties
<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/js.quartz.properties
Copied to <tomcat>/webapps/jasperserver-pro/WEB-INF/js.quartz.properties
<js-install>/buildomatic/build_conf/db/mysql/jdbc/mysql-connector-java-5.1.10.jar
Copied to <tomcat>/lib
6.3.7 Buildomatic: Sample Data Catalog ZIP Files
Buildomatic includes export files which hold the JasperReports Server sample data (that have examples of new features). This
sample data is loaded when you run the buildomatic target import-sample-data-pro, for instance. These export files along
with other important export files are located here:
<js-install>/buildomatic/install_resources/export/
Here are some key files (same pattern for additional databases):
js-catalog-mysql-minimal-pro.zip
js-catalog-mysql-pro.zip
js-catalog-postgresql-minimal-pro.zip
js-catalog-postgresql-pro.zip
js-catalog-oracle-minimal-pro.zip
js-catalog-oracle-pro.zip
6.4 Additional Notes on Databases
This section provides additional information on the following databases:
Notes on the MySQL Database
Notes on the Oracle Database
Notes on the DB2 Database
For each database, there are commands to:
Manually create and initialize the JasperReports Server database.
Manually import the default users and organization.
Manually create and load the sample databases.
53
6.4.1 Notes on the MySQL Database
The MySQL client software, mysql.exe or mysql, can be used to interact with the MySQL database. The example commands
below have been tested at Jaspersoft. The commands to be used on your MySQL instance may be different.
These commands are run from the Windows or Linux command line.
6.4.1.1 Manual Creation of the JasperReports Server Database
Please check your database user documentation for how to set up a database and how to create a database user.
Run the following commands:
6.4.1.2 Manual Import of Default Minimal Data
First, follow the instructions in Chapter 14, Configuring the Import-Export Utilities, on page 111.
Note: The commands shown below can be run from the buildomatic ant import task instead.
Then run the following commands to perform the import:
The next (optional) command loads the sample data resources. No need to run this command if you do not create and load the
sample databases from the next section.
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-mysql-pro.zip
6.4.1.3 Manual Creation of Sample Databases
cd <js-install>/buildomatic/install_resources/sql/mysql
mysql -u root -p
mysql>create database jasperserver character set utf8;
mysql>grant all on *.* to jasperdb@localhost identified by 'password';
mysql>flush privileges; (reload privilege tables)
mysql>use jasperserver;
mysql>source js-pro-create.ddl
mysql>source quartz.ddl
mysql>exit
If you are going to access MySQL on a remote server you should run an additional grant statement:
mysql>grant all on *.* to jasperdb@'%' identified by 'password';
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-mysql-
minimal-pro.zip
cd <js-install>/buildomatic/install_resources/sql/mysql
mysql -u root -p
mysql>create database sugarcrm;
mysql>create database foodmart;
mysql>use sugarcrm;
mysql>source sugarcrm-mysql.sql;
mysql>use foodmart;
mysql>source foodmart-mysql.sql; (first make sure the file is unzipped)
mysql>source supermart-update.sql;
mysql>exit
54
6.4.2 Notes on the Oracle Database
The Oracle client software, sqlplus.exe or sqlplus, can be used to interact with Oracle. The example commands below have
been tested at Jaspersoft. The commands to be used on your Oracle instance may be different.
These commands should be run from the Windows or Linux command line.
Please check your database user documentation for how to set up a database and how to create a database user.
6.4.2.2 Manual Import of Minimal Data
The next (optional) command loads the sample data resources. No need to run this command if you do not create and load the
sample databases from the next section.
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-oracle-pro.zip
The sugarcrm database has test data that requires a specific NLS_LANG setting in order to load into Oracle correctly. You will
need to set this in your shell environment if you are manually loading the sugarcrm database.
Set the NLS_LANG variable that Oracle should use for the sugarcrm database:
cd <js-install>/buildomatic/install_resources/sql/oracle
sqlplus /nolog (start sqlplus client)
SQL> connect SYS/password@ORCL as SYSDBA (use your SYS password, your SID)
SQL> create user jasperserver identified by password;
SQL> grant connect, resource to jasperserver;
SQL> connect jasperserver/password@ORCL (use your password, your SID)
SQL> @js-pro-create.ddl
SQL> @quartz.ddl
SQL> exit
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-oracle-
minimal-pro.zip
If you build and load the sample databases using buildomatic, the NLS_LANG setting is automatically handled via a
JDBC driver setting.
Windows: set NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1
Linux: export NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1
55
6.4.3 Notes on the DB2 Database
The DB2 client software, db2 or db2cmd, can be used to interact with DB2.
The example commands below have been tested at Jaspersoft. The commands to be used on your DB2 instance may be
different.
These commands should be run from the Windows or Linux command line.
Change to the following directory:
cd <js-install>/buildomatic/install_resources/sql/db2
Run the following commands in the DB2 command window:
6.4.3.2 Manual Import of Default Users
The next (optional) command loads the sample data resources. No need to run this command if you do not create the and load
the sample databases from the next section.
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-db2-pro.zip
Change to the following directory:
cd <js-install>/buildomatic/install_resources/sql/db2
cd <js-install>/buildomatic/install_resources/sql/oracle
sqlplus /nolog (start sqlplus client)
SQL> connect SYS/password@ORCL as SYSDBA (use your SYS password, your SID)
SQL> create user sugarcrm identified by password;
SQL> create user foodmart identified by password;
SQL> grant connect, resource to sugarcrm;
SQL> grant connect, resource to foodmart;
SQL> connect sugarcrm/password@ORCL
SQL> @sugarcrm-oracle.sql (populate data - runs slowly)
SQL> connect foodmart/password@ORCL
SQL> @foodmart-oracle.sql (populate data - runs slowly. Make sure file is unzipped)
SQL> @supermart-update.sql
SQL> exit
db2 create database jsprsrvr using codeset utf-8 territory us
db2 -tf js-pro-create.ddl
db2 -tf quartz.ddl
js-import --input-zip ../buildomatic/install_resources/export/js-catalog-db2-
minimal-pro.zip
56
Run the following commands in the DB2 command window:
6.5 Notes on the Hibernate Properties File
Your hibernate.properties settings will be found in the following directory after buildomatic has been run to automatically
generate your configuration files:
<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties
Within the jasperserver-pro WAR file the hibernate.properties file is found at the following location:
<appserver-path>/jasperserver-pro/WEB-INF/hibernate.properties
The buildomatic scripts automatically create this configuration file. When you run the buildomatic target deploy-webapp-
pro this file is copied to JasperReports Server in your application server.
Here are some example hibernate property values.
6.6 Notes on Database Connections for Tomcat
After setting up the buildomatic configuration for your database, the Tomcat context.xml will be automatically created with
the appropriate settings for JasperReports Server.
When the buildomatic target deploy-webapp-pro is run, the context.xml will be automatically copied into the jasperserver-
pro WAR set of files.
You can view the automatically generated context.xml at the following location:
<js-install>/buildomatic/build_conf/default/webapp/META-INF/context.xml
The final location of the context.xml is:
<tomcat>/webapps/jasperserver-pro/META-INF/context.xml
Tomcat will often create a copy of the context.xml file with a changed name that will be read instead of the one found in the
jasperserver-pro war file. This is often a source of confusion for Tomcat users who attempt change their database settings. If
you change your settings, you should delete the file in this location:
<tomcat>/conf/Catalina/localhost
6.7 Notes on Data Source Definitions for JBoss
After setting up the buildomatic configuration for your database, the JBoss data source definition file will be automatically
created with the appropriate settings for JasperReports Server.
When the buildomatic target deploy-webapp-pro is run, the js-jboss-ds.xml will be automatically copied into the JBoss
instance.
db2 create database sugarcrm
db2 -tf sugarcrm-db2.sql
db2 create database foodmart
db2 -tf foodmart-db2.sql (first make sure file is unzipped)
db2 -tf supermart-update.sql (if script is available)
MySQL: metadata.hibernate.dialect=org.hibernate.dialect.MySQLDialect
Oracle: metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.OracleUnicodeDialect
DB2: metadata.hibernate.dialect=org.hibernate.dialect.DB2Dialect
57
You can view the automatically generated js-jboss-ds.xml at the following location:
<js-install>/buildomatic/build_conf/default/js-jboss-ds.xml
The final location of the js-jboss-ds.xml is:
<jboss>/server/default/deploy/js-jboss-ds.xml
6.7.1 Notes on Extra JBoss Configuration Steps
When JasperReports Server is running under JBoss, there are a couple of INFO log messages and an XML/A connection error
that might occur depending on the version of JBoss you are running with.
For more information, refer to troubleshooting section A.12, JBoss Modifications, on page 123.
6.8 Notes on Database Connections for GlassFish
After setting up the buildomatic configuration for your database, the GlassFish data source definition file js-glassfish-ds.xml
will be automatically created with the appropriate settings. When the buildomatic target deploy-webapp-pro is run, the file
is automatically deployed to the GlassFish instance.
You can view the automatically generated js-glassfish-ds.xml at the following location:
<js-install>/buildomatic/build_conf/default/js-glassfish-ds.xml
To deploy the datasource definition manually, you can run a command similar to the following:
asadmin add-resources "<js-install>/buildomatic/build_conf/default/js-glassfish-ds.xml"
6.9 Report Scheduling Configuration with Quartz
The JasperReports Server report scheduling feature is powered by the Quartz scheduler tool. The configuration settings for
Quartz based report scheduling is automatically handled by buildomatic.
In a deployed JasperReports Server instance, you will find the js.quartz.properties file in the following location:
<app-server-path>/jasperserver-pro/WEB-INF/js.quartz.properties
For mail server configuration, there is an additional property setting for authentication in the following file:
<app-server-path>/webapps/jasperserver-pro/WEB-INF/applicationContext-report-scheduling.xml
There are four main configurations to be discussed in this section:
Mail Server Configuration
Quartz Driver Delegate Class
Report Scheduler Web URI
Quartz Table Prefix
6.9.1 Mail Server Configuration Settings
If you schedule reports or run them in the background, you can specify email addresses to notify when the report completes. In
order to use this feature, you must configure JasperReports Server to contact an email server:
Configuration File
<app-server>/<deployment>/WEB-INF/js.quartz.properties
Property Description
report.scheduler.mail.sender.host The name of the computer hosting the mail server.
58
6.9.2 Database settings for the Quartz Driver Delegate Class
The Quartz driver delegate class is a class which Quartz uses to interact with the JDBC driver. For the PostgreSQL and DB2
databases it needs a non-default setting.
To set this value manually, edit the following file:
6.9.3 Settings for the Report Scheduler Web URI
For the web URI setting, the exact settings depend on what port your application server is running on and the name of your
deployed jasperserver web application (that is, if you do not use the default name jasperserver-pro).
report.scheduler.mail.sender.username The name of the user in the mail server that JasperReports
Server can use.
report.scheduler.mail.sender.password The password of the mail server user.
report.scheduler.mail.sender.from The address that appears in the From field on email
notifications.
report.scheduler.mail.sender.protocol The protocol that the mail server uses. JasperReports
Server only supports SMTP.
Note: Your entry must be lower case. For example: smtp
report.scheduler.mail.sender.port The port number that the mail server uses. For SMTP, the
default is typically 25 (values other than 25 may not work in
earlier JasperServer versions).
Configuration File
<app-server>/<deployment>/WEB-INF/applicationContext-report-scheduling.xml
Property Bean Description
javaMailProperties
key="mail.smtp.auth"
reportScheduler
MailSender
If your mail server requires authentication, change this
property from false to true.
If you installed using buildomatic these settings are handled automatically.
Configuration File
Property Database Value
quartz.delegateClass MySQL org.quartz.impl.jdbcjobstore.StdJDBCDelegate
PostgreSQL org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
Oracle org.quartz.impl.jdbcjobstore.StdJDBCDelegate
SQL Server org.quartz.impl.jdbcjobstore.StdJDBCDelegate
DB2 org.quartz.impl.jdbcjobstore.DB2v8Delegate
59
To manually edit, you would edit the following file:
6.9.4 Settings for the Quartz Table Prefix
For databases that support schemas, such as Oracle, SQL Server, and DB2, you can set the Quartz table prefix so that it
includes the schema if you use one. In the default configuration, only DB2 requires an explicit schema name
6.9.5 Settings for Import-Export
If you are manually configuring the import-export shell scripts (that is, not using the buildomatic scripts), then depending on
the database you are using, you will need to make sure your settings are correct for the Quartz driver delegate class property
and the Quartz table prefix property.
To configure the import-export scripts manually, edit the following file:
Configuration File
Property App Server Example Value
report.scheduler.
web.deployment.uri
Apache Tomcat http://localhost:8080/jasperserver-pro
JBoss http://localhost:8080/jasperserver-pro
GlassFish http://localhost:8080/jasperserver-pro
WebSphere http://localhost:9080/jasperserver-pro
WebLogic http://localhost:7001/jasperserver-pro
Configuration File
quartz.tablePrefix The prefix for the quartz table, including any schema name, for
example JSPRSRVR.QRTZ_ for DB2.
If you installed using buildomatic these settings are handled automatically (in buildomatic import-export).
Configuration File
<js-install>/buildomatic/conf_source/iePro/js.quartz.properties
quartz.delegateClass Set to the same value as described in section 6.9.2, Database
settings for the Quartz Driver Delegate Class, on page 58.
quartz.tablePrefix Set to the same value as described in section 6.9.4, Settings
for the Quartz Table Prefix, on page 59
60
6.10 Notes on Updating XML/A Connection Definitions
Sample XML/A connections are included with the JasperReports Server sample data. If you plan to use XML/A Web Services
in your environment, then you may want to check and possibly update the hard coded values in the sample connections.
If you have Jaspersoft OLAP enabled (via your license), JasperReports Server is able to make XML/A connections over the
Web Services interface. These HTTP-based connections use a user account for authentication. You may have different
usernames and passwords than the defaults that get loaded from the sample data load in the sections above. Additionally, your
application server hostnames and port values might be different than the default values.
There are two sample OLAP views that use this connection:
Foodmart Sample XMLA OLAP View
SugarCRM Sample XMLA OLAP View
If you would like to validate and update these resources, do the following:
1. Log into JasperReports Server as an administrator (such as jasperadmin).
2. Navigate to the Repository Management page by selecting the View > Repository menu item.
3. Click to expand the Analysis Components folder, then the Analysis Connections folder. Click to highlight the Foodmart
XMLA Connection resource, then click Edit.
4. Edit the following information on this screen:
URI (hostname and port)
Login Username
Login Password
5. Click Next, then Save.
6. Make the same updates for the SugarCRM XMLA Connection resource.
Installing the WAR File for WebSphere
61
CHAPTER 7 INSTALLING THE WAR FILE FOR WEBSPHERE
JasperReports Server supports deployment on the IBM WebSphere Application Server. Deployment is performed by the
WebSphere administrator using the WebSphere Administrative Console.
Setting Up the JasperReports Server Database
Configuring Database Connections
Configuring Hibernate and Quartz in the WAR File
Deploying the JasperReports Server WAR to the Application Server
Setting Java JVM Options
Restarting the Application Server
Configuring Report Scheduling
Updating XML/A Connection Definitions (Optional)
Restarting JasperReports Server
Troubleshooting your JasperReports Server Configuration
Refer to section 5.3, Unpacking the WAR File Distribution Zip, on page 30.
62
7.3 Setting Up the JasperReports Server Database
JasperReports Server requires its own database to store information such as users, organizations, and the repository. In
addition, the WAR file distribution includes two sample databases containing data for optional demos. For evaluation,
Jaspersoft recommends you install the sample databases and the demos that use them. In a production environment, you only
need to set up the database. In either case, the databases must be created and initialized before JasperReports Server is
deployed in WebSphere.
To setup the database and optional sample databases, you can use either the buildomatic scripts or perform the commands
manually. For simplicity, Jaspersoft recommends you use the buildomatic scripts.
To use the buildomatic scripts, refer to section 5.6, Configuring the Buildomatic Scripts, on page 32 and section 5.7,
Installing JasperReports Server, on page 33. The condition for using the buildomatic scripts is that WebSphere must
be installed in the default location.
To perform the commands manually, refer to section 6.4, Additional Notes on Databases, on page 52.
In either case, follow the steps that describe the commands for your specific database vendor.
7.4 Configuring Database Connections
By default, the database configuration files included with the JasperReports Server WAR file distribution are set to connect to
a database with the following settings:
The settings in the table above are used in the following sections to configure JDBC providers, database users, and JDBC data
sources in WebSphere, according to your database:
7.4.1, Configuring JDBC Data Sources for MySQL, on page 62
7.4.2, Configuring JDBC Data Sources for Oracle, on page 64
7.4.3, Configuring JDBC Data Sources for DB2, on page 65
The Hibernate and Quartz information is used in section 7.5, Configuring Hibernate and Quartz in the WAR File, on
page 68. For SQL Server and PostgreSQL, follow similar procedures using the values from the table above.
7.4.1 Configuring JDBC Data Sources for MySQL
To define a JDBC provider:
1. In the Administrative Console, navigate to Resources > JDBC > JDBC Providers.
2. Click New button to create a new JDBC Provider.
Database
Setting
MySQL Oracle DB2 SQL Server PostgreSQL
Host localhost localhost localhost localhost localhost
Name or SID jasperserver Orcl jsprsrvr jasperserver jasperserver
User root jasperserver db2admin sa postgres
Password password password password sa postgres
Port 3306 1521 50000 1433 5432
Hibernate
Dialect
MySQLDialect OracleUnicode
Dialect
DB2SQLDialect SQLServerDialect PostgresqlNoBlob
Dialect
Quartz Driver
Delegate
StdJDBCDelegate StdJDBCDelegate DB2v8Delegate StdJDBCDelegate PostgreSQL
Delegate
63
3. Enter the following values:
4. Click Next and enter the following JAR file, including its path:
<js-install>\buildomatic\conf_source\db\mysql\jdbc\mysql-connector-java-<ver>-bin.jar
The version number <ver> must be 3.1.14 or greater. You may also copy the JAR file to a location in your WebSphere
deployment and specify that location here.
5. Click Next, review the information and click Finish.
6. On the JDBC Providers page, click Save directly to the master configuration.
To define a database user:
1. In the Administrative Console, navigate to:
2. In the Authentication section, expand Java Authentication and Authorization Service, and click J2C authentication data.
3. Click New and enter the following user alias, user ID, and password. These are the credentials that will be used to access
the database:
4. Click OK, review the new user in the table, and click Save directly to the master configuration again.
To define the JDBC data source and expose it through JNDI:
1. In the Administrative Console, navigate to Resources > JDBC > Data Sources.
2. Click New button to create a new JDBC Data Source.
4. Click Next and choose Select an existing JDBC provider, then select MySQL JDBC Provider from the drop-down list.
5. Click Next and specify the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Also select the
check box to use this data source in container managed persistence (CMP).
6. Click Next, review the summary information and click Finish.
7. In the list of JDBC data sources, click the link for the newly created jasperserver data source.
Field Name Value
Database type User-defined
Implementation class name com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
Name MySQL JDBC Provider
WebSphere 6.1: Security > Secure administration, application and infrastructure
WebSphere 7.0: Security > Global Security
Field Name Value
Alias mysql_jasperdb
User ID root
Password password
Field Name Value WebSphere Version
Data source name jasperserver 6.1 and 7.0
JNDI name jdbc/jasperserver 6.1 and 7.0
Component-managed authentication alias <node>/mysql_jasperdb 6.1 and 7.0
Mapping conf alias DefaultPrincipalMapping 7.0
Container-managed authentication alias <node>/mysql_dbname 7.0
64
8. In the section labeled Additional Properties on the right, click Custom Properties.
9. Click on the filter icon button, select Name as the filter and enter url as the search term.
10. Click Go, then click on the url property. Enter the following value and save the change:
jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&characterEncoding=UTF-8
11. Go back to the list of JDBC data sources, select the check box for the jasperserver data source, and click Test to verify
the connection.
12. If you plan to run the sample reports, repeat step 2 through step 11 with the following values to create the foodmart and
sugarcrm JNDI data sources:
13. Click Save directly to the master configuration.
7.4.2 Configuring JDBC Data Sources for Oracle
4. Click Next and enter the following path:
<js-install>\buildomatic\conf_source\db\oracle\jdbc\
You may also copy the ojdbc5-11.2.0.jar file to a location in your WebSphere deployment and specify that location here.
7. On the JDBC Providers page, click the newly created Oracle JDBC Driver to edit it.
8. Locate the filename ojdbc14.jar and replace it with the filename ojdbc5-11.2.0.jar, then save the changes.
To define database users:
1. In the Administrative Console, navigate to Security > Secure administration, application and infrastructure.
3. Click New and enter the following user alias, user ID, and password for each of the three users. These are the credentials
that will be used to access the database:
Field Name Value
Data source name foodmart sugarcrm
JNDI name jdbc/foodmart jdbc/sugarcrm
Component-managed authentication alias <node>/mysql_jasperdb <node>/mysql_jasperdb
Field Name Value
Database type Oracle
Provider type Oracle JDBC Driver
Implementation type Connection pool data source
Name Oracle JDBC Driver
Field Name Values
Alias jasperserver_user foodmart_user sugarcrm_user
65
4. Click OK after entering the information for each user.
5. Review the new users in the table and click Save directly to the master configuration.
4. Click Next and choose Select an existing JDBC provider, then select Oracle JDBC Provider from the drop-down list.
5. Click Next and enter the following values:
7. In the list of JDBC data sources, select the check box for the jasperserver data source, and click Test to verify the
connection.
7.4.3 Configuring JDBC Data Sources for DB2
User ID jasperserver foodmart sugarcrm
Password password password password
Field Name Value
Data source name jasperserver
JNDI name jdbc/jasperserver
Component-managed authentication alias <node>/jasperserver_user
Field Name Value
URL jdbc:oracle:thin:@localhost:1521:orcl
Data store helper class name Oracle11g data store helper
Use this data source in CMP selected
Field Name Value
Component-managed authentication alias <node>/foodmart_user <node>/sugarcrm_user
Field Name Value
Database type DB2
66
4. Click Next and enter the following path:
You may also copy the db2jcc-x.y.jar file to a location in your WebSphere deployment and specify that location here. If
JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts:
<db2>/SQLLIB/java/db2jcc.jar
7. On the JDBC Providers page, click the newly created DB2 Universal JDBC Driver Provider to edit it.
8. Locate the filename db2jcc.jar and replace it with the appropriate filename, then save the changes:
To define a database user:
1. In the Administrative Console, navigate to Security > Secure administration, application and infrastructure.
3. Click New and enter the following user alias, user ID, and password. These are the credentials that will be used to access
the database:
4. Click OK, review the new user in the table, and click Save directly to the master configuration.
4. Click Next and choose Select an existing JDBC provider, then select DB2 Universal JDBC Driver Provider from the
drop-down list.
Provider type DB2 Universal JDBC Driver Provider
Implementation type Connection pool data source
Name DB2 Universal JDBC Driver Provider
DB2 8.x: <js-install>\buildomatic\conf_source\db\db2\jdbc\alt-drivers
DB2 9.x: <js-install>\buildomatic\conf_source\db\db2\jdbc
DB2 8.x: db2jcc-8.2.jar
DB2 9.x: db2jcc-9.5.jar
Field Name Value
Alias db2admin_user
User ID db2admin
Password password
Field Name Value
Data source name jasperserver
JNDI name jdbc/jasperserver
Component-managed authentication alias <node>/db2admin_user
67
5. Click Next and enter the following values:
7. In the list of JDBC data sources, click the link for the newly created jasperserver data source.
8. In the section labeled Additional Properties on the right, click Custom Properties.
9. Edit the following properties, including adding the ones that dont exist, then save the changes:
10. Go back to the list of JDBC data sources, select the check box for the jasperserver data source, and click Test to verify
the connection.

Field Name Value
Database name jsprsrvr
Driver type 4
Server name localhost
Port number 50000
Use this data source in CMP selected
Property Name Value
currentSchema JSPRSRVR
fullyMaterializeLobData true
fullyMaterializeInputStreams true
progressiveStreaming 2
progresssiveLocators 2
Field Name Value
Component-managed authentication alias <node>/db2admin_user <node>/db2admin_user
Field Name Value
Database name foodmart sugarcrm
Driver type 4 4
Server name localhost localhost
Port number 50000 50000
Use this data source in CMP selected selected
Property Name Value
currentSchema FOODMART SUGARCRM
resultSetHoldability 1 1
68
The other properties (fullyMaterializeLobData, fullyMaterializeInputStreams, progressiveStreaming, and
progresssiveLocators) are not needed for the sample databases.
7.5 Configuring Hibernate and Quartz in the WAR File
Before deploying the JasperReports Server WAR file, you must update the Hibernate and Quartz settings that it contains, as
described in the following procedure.
1. The WAR file is an archive format in a single file. To access the configuration files it contains, you must extract them
with the following commands:
The jar command will create the WEB-INF directory in the current location and place the extracted files there.
2. Open the file WEB-INF/hibernate.properties for editing and locate the metadata.hibernate.dialect property. Set
its value according to your database:
3. Open the file WEB-INF/js.quartz.properties for editing and locate the report.scheduler.web.deployment.uri
property. Set its value to the hostname, port, and path where you intend to deploy JasperReports Server, for example:
report.scheduler.web.deployment.uri=http://localhost:9080/jasperserver-pro
If you are using PostgreSQL or DB2, set the Quartz delegate class in the js.quartz.properties file:
4. If you want to configure JasperReports Server to automatically schedule and email reports, enter your mail server
information in the js.quartz.properties file. Modify all report.scheduler.mail.sender.* properties as necessary for
your mail server.
5. Now that you have modified the individual configuration files, you must replace them into the WAR file archive. Use the
following command:
6. Delete the WEB-INF directory that was created, along with the edited files it contains.
7.5.1 Additional Fix for Scheduled Report with JNDI Data Source
Under the WebSphere application server, if you have a scheduled report that uses a JNDI data source you will need to make an
additional configuration in order for the JNDI lookup to be resolved correctly.
cd <js-install>
"%JAVA_HOME%\bin\jar" xf jasperserver-pro.war WEB-INF/hibernate.properties
"%JAVA_HOME%\bin\jar" xf jasperserver-pro.war WEB-INF/js.quartz.properties
PostgreSQL: quartz.delegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
DB2: quartz.delegateClass=org.quartz.impl.jdbcjobstore.DB2v8Delegate
All others: quartz.delegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
cd <js-install>
"%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/hibernate.properties
"%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/js.quartz.properties
69
There are special WebSphere specific configuration files included in the jasperserver-pro.war archive. In order to enable this
fix, you will need to rename the WebSphere specific files to remove the prefix webSphere. Two of the file rename operations
will overwrite the existing configuration file names.
Notes on this configuration change:
Since JasperServer 3.7 and 4.0, for WebSphere, a new work manager class is used to run scheduled report jobs. The JNDI
name of the work manager is configured in the WebSphere version of js.scheduling.properties. Also, for WebSphere, we need
a different default value for the specified JNDI name (wm/default). This is also defined in the WebSphere version of
js.scheduling.properites.
The number of threads that run report jobs is no longer configured in js.quartz.base.properties, but is instead provided by the
work manager configuration.
7.5.2 Additional Change for Mail Server Authentication
If your mail server requires authentication, edit the applicationContext-report-scheduling.xml file after applying the changes
above.
1. Extract the file from the WAR archive:
"%JAVA_HOME%\bin\jar" xf jasperserver-pro.war WEB-INF/applicationContext-report-
scheduling.xml
2. Open the file for editing and locate the reportSchedulerMailSender bean.
3. Set the javaMailProperties key="mail.smtp.auth" value to true.
4. Save the file and replace it in the archive:
"%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/applicationContext-report-
scheduling.xml
5. Delete the WEB-INF directory that was created, along with the file it contains.
JasperReports Server Professional or Enterprise requires a license to run. The JasperReports Server WAR distribution comes
with an evaluation license that is valid for a number of days. Please contact Technical Support or your sales representative to
get your commercial license.
The license file is in the following location:
<js-install>/jasperserver.license
You must put your license file into a home folder of a user account being used to start WebSphere Application Server. This
account may differ from the logged user account. For example, if WebSphere is running on Windows Server as a service, the
system account is used to start the WebSphere, and its home folder would be:
%SystemRoot%\system32\config\systemprofile
Rename: WEB-INF/webSphere-applicationContext-report-scheduling-wm.xml
To: WEB-INF/applicationContext-report-scheduling-wm.xml
Rename: WEB-INF/webSphere-js.quartz.base.properties
To: WEB-INF/js.quartz.base.properties (overwrite existing file)
Rename: WEB-INF/webSphere-js.scheduling.properties
To: WEB-INF/js.scheduling.properties (overwrite existing file)
70
7.7 Deploying the JasperReports Server WAR to the Application Server
Now that the databases are created and all files are configured, you can deploy the JasperReports Server WAR file in
WebSphere.
2. Enter the following information:
3. Click Next.
4. On the Select installation options page, leave all the default settings.
5. Click Next.
6. On the Map modules to servers page, make sure the JasperReports Server module is mapped to the cell, node, and server
that you want.
7. Click Next.
8. Set the correct target JNDI name for each of the resource references.
9. Click Next.
10. On the Map virtual hosts page, choose the virtual host where JasperReports Server is exposed, usually the default one.
11. Click Next, review the summary information and start the installation process.
12. Make sure JasperReports Server is successfully installed, then click Save directly to the master configuration.
7.8 Setting Java JVM Options
In order for the JasperReports Server analysis XML/A functionality to work, special Java JVM options need to be set. This is
because both WebSphere and JasperReports Server provide a full web services implementation and there are class conflicts
between the two.
JVM options also provide the optimal resources for running JasperReports Server.
To configure your Java JVM options:
1. Select:
WebSphere 6.1: Applications > Install New Application
WebSphere 7.0: Applications > New Application > New Enterprise Application
Field Name Value
Path to the new application Local File System
Full path <js-install>/jasperserver-pro.war
Context root jasperserver-pro
WebSphere 6.1: Application Servers > (server name) > Process Definition > Java Virtual Machine > Generic JVM
Options
WebSphere 7.0: Enterprise Applications > jasperserver-pro_war > Target specific application status >
(server name), and then expand Java and Process Management > Process Definition >
Java Virtual Machine > Generic JVM arguments
71
2. In the text box named Generic JVM Options, paste in the following JVM options that will explicitly specify
JasperReports Server classes for AXIS and Xalan, as well as optimize JVM resources:
3. Click Save on the console task bar.
4. Restart the application server.
7.9 Restarting the Application Server
You have completed the configuration steps for JasperReports Server. Because JAVA options and other configuration changes
were made, you should restart the application server.
2. Select the check box next to the jasperserver-pro application, then click Start to start the application.
1. Log in by going to the following URL:
Generic JVM Options on Windows
Options for
all databases
set JAVA_OPTS=%JAVA_OPTS% -Dclient.encoding.override=UTF-8 -Xms128m -Xmx512m
-XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m -XX:+UseConcMarkSweepGC
-XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled
-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
For Oracle set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true
Generic JVM Options on Linux
Options for
all databases
export JAVA_OPTS="$JAVA_OPTS -Dclient.encoding.override=UTF-8 -Xms128m -Xmx512m
-XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m -XX:+UseConcMarkSweepGC
-XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled
-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl"
For Oracle export JAVA_OPTS="$JAVA_OPTS -Doracle.jdbc.defaultNChar=true"
You can cut and paste these options from <js-install>/samples/extra/java-settings/java-settings-
websphere.txt.
WebSphere 6.1: Applications > Enterprise Applications
WebSphere 7.0: Applications > Application Types > WebSphere Enterprise Application
72
Where <hostname> could be localhost, a machine name, or an IP address. The login page should appear after some time
to compile the necessary JSP files.
2. Use the following administrative identity to log into the system:
If you logged in successfully, the JasperReports Server home page appears. If you have trouble logging in and get a Page
cannot be found, HTTP 404 error, you may be running at a WebSphere patch level that needs a further configuration. Refer to
troubleshooting section A.13, WebSphere: Page Not Found Error on Login, on page 124.
Refer to the JasperReports Server User Guide to begin adding reports and other resources to JasperReports Server.
7.12 Configuring Report Scheduling
The scheduled reporting feature of JasperReports Server allows reports to be run at pre-configured time intervals. Optionally,
notification emails can be sent to users to let them know that new reports are available.
For more information about setting up report scheduling, refer to section 6.9, Report Scheduling Configuration with
Quartz, on page 57.
7.13 Updating XML/A Connection Definitions (Optional)
If you have loaded the JasperReports Server sample data, and you would like to run the Analysis XML/A examples, you will
need to update the XML/A connection resources to use the correct web port.
The typical port used by WebSphere is 9080. Follow the procedure in section 6.10, Notes on Updating XML/A Connection
Definitions, on page 60.
7.14 Restarting JasperReports Server
If you have made configuration changes to your JasperReports Server instance, you should restart JasperReports Server.
7.15 Troubleshooting your JasperReports Server Configuration
7.15.1 Startup Problems
When trying to run a new JasperReports Server instance, most typical problems encountered are errors in the database
configuration.
application server configuration files. For more information on resolving these types of errors, refer to troubleshooting
section A.2, Database Connectivity Errors, on page 118.
The first time you log into JasperReports Server, you will be prompted to opt-in or opt-out of the JasperReports Server
Heartbeat. For more information, refer to section 5.11.1, JasperReports Server Heartbeat, on page 36.
73
7.15.2 Error Running Report
If you are having trouble running the MDX example Topic or SugarCRM OLAP view, you need to update the port for XML/
A connections. See section 7.13, Updating XML/A Connection Definitions (Optional), on page 72.
7.15.3 Filter Error
If you encounter the following error:
Error 500: Filter [characterEncodingProxyFilter]: cold not be initialized
it could be caused by an incorrect ampersand setting on your data source configuration.
The data source line needs to have & and not & in order to be evaluated correctly.
The URL in section 7.4.1, Configuring JDBC Data Sources for MySQL, on page 62 should look like the following:
jdbc:mysql://localhost/jasperserver?useUnicode=true&characterEncoding=UTF-8
Note the ampersand string is & and not &.
7.15.4 Error Creating Internationalized Name
If you encounter errors in JasperReports Server when creating resources with internationalized names, and you have an Oracle
database, you need to configure your Oracle JDBC driver. Be sure to set the Oracle-specific option listed in the tables of
section 7.8, Setting Java JVM Options, on page 70.
7.15.5 Xerces Error
If you have a WebSphere log with the following error:
It is caused by a conflict between the IBM JDK which is used by WebSphere and the xercesImpl-2.6.2 library which is
bundled with JasperReports Server. There are two solutions:
Remove the xercesImpl library from the following location:
<websphere>\profiles\AppSrv<NN>\installedApps\<node>\jasperserver-pro_war.ear\
jasperserver-pro.war\WEB-INF\lib
Update the xercesImpl library to a new version. For example, xercesImpl-2.8.1 does not cause the error.
7.15.6 OLAP View Fails With Exception
If you see the following error:
java.lang.NoSuchMethodError: org/aspectj/runtime/reflect/Factory.makeMethodSig(
java/lang/String;
...)
org/aspectj/lang/reflect/MethodSignature;
it could caused by AspectJ requiring class loaders to be tried out in a specific order. Change the default class loader policy with
the following procedure:
1. In the WebSphere Administrative Console, navigate to Applications > (app-name) > Manage Modules > JasperServer
UI application
SRVE0068E: Uncaught exception thrown in one of the service methods of the servlet:
jasperserver. Exception thrown: org.springframework.web.util.NestedServletException:
javax.xml.validation.SchemaFactoryFinder$ConfigurationError: Provider
org.apache.xerces.jaxp.validation.XMLSchemaFactory could not be instantiated:
org.apache.xerces.impl.dv.DVFactoryException: DTD factory class
org.apache.xerces.impl.dv.dtd.DTDDVFactoryImpl does not extend from DTDDVFactory.
74
2. Change the following setting:
3. Click OK.
4. Save the master configuration.
5. Restart the WebSphere server.
7.15.7 Analysis Options Page Throws Exception
If you see the following error:
com.ibm.ws.jsp.JspCoreException: JSPG0049E: /WEB-INF/jsp/olap/editProperties.jsp failed to
compile
it could be caused by the JSP compiler using Java 1.3 by default. Try either of the following solutions:
Add a custom property to the Web Container:
Add the following property to the WEB-INF/ibm-web-ext.xmi file:
<jspAttributes xmi:id="JSPAttribute_113" name="jdkSourceLevel" value="15"/>
Property Name Value
Class loader order Classes loaded with application class loader first
Property Name Value
com.ibm.ws.jsp.jdkSourceLevel 15
Installing the WAR File for WebLogic
75
CHAPTER 8 INSTALLING THE WAR FILE FOR WEBLOGIC
JasperReports Server supports deployment on the WebLogic Application Server. Deployment is performed by the WebLogic
administrator using the WebLogic Administrative Console or domain config.xml.
Setting Up the JasperReports Server Database
Configuring Database Connections
Deleting JARs and Setting Configurations in the WAR File
Additional Changes for WebLogic 10.3.0
Preparing the WebLogic Domain
Deploying JasperReports Server to WebLogic
Configuring Report Scheduling
Restarting JasperReports Server
Updating XML/A Connection Definitions (Optional)
Troubleshooting Your JasperReports Server Configuration
Refer to section 5.3, Unpacking the WAR File Distribution Zip, on page 30.
76
8.3 Setting Up the JasperReports Server Database
JasperReports Server requires its own database to store information such as users, organizations, and the repository. In
addition, the WAR file distribution includes two sample databases containing data for optional demos. For evaluation,
Jaspersoft recommends you install the sample databases and the demos that use them. In a production environment, you only
need to set up the database. In either case, the databases must be created and initialized before JasperReports Server is
deployed in WebLogic.
To setup the database and optional sample databases, you can use either the buildomatic scripts or perform the commands
manually. For simplicity, Jaspersoft recommends you use the buildomatic scripts.
To use the buildomatic scripts, refer to section 5.6, Configuring the Buildomatic Scripts, on page 32 and section 5.7,
Installing JasperReports Server, on page 33. The condition for using the buildomatic scripts is that WebLogic must
be installed in the default location.
To perform the commands manually, refer to section 6.4, Additional Notes on Databases, on page 52.
In either case, follow the steps that describe the commands for your specific database vendor.
8.4 Configuring Database Connections
By default, the database configuration files included with the JasperReports Server WAR file distribution are set to connect to
a database with the following settings:
The following sections show how to configure database connections for a MySQL database in WebLogic. The Hibernate and
Quartz information is used in section 8.5, Deleting JARs and Setting Configurations in the WAR File, on page 77. For
other databases, follow similar procedures using values from the table above.
8.4.1 Configuring Data Sources
1. In Administrative Console window, navigate to JDBC > Data Sources.
2. Click New for each of the data source columns in the following table, and enter the corresponding values:

Database
Setting
MySQL Oracle DB2 SQL Server PostgreSQL
Host localhost localhost localhost localhost localhost
Name or SID jasperserver Orcl jsprsrvr jasperserver jasperserver
User root jasperserver db2admin sa postgres
Password password password password sa postgres
Port 3306 1521 50000 1433 5432
Hibernate
Dialect
MySQLDialect OracleUnicode
Dialect
DB2SQLDialect SQLServerDialect PostgresqlNoBlob
Dialect
Quartz Driver
Delegate
StdJDBCDelegate StdJDBCDelegate DB2v8Delegate StdJDBCDelegate PostgreSQL
Delegate
Parameter Name JasperReports Server Foodmart Example Sugar CRM Example
Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase
JNDI Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase
Database Type MySQL MySQL MySQL
77
8.4.2 Setting Connection Properties
The following table gives sample connection properties for a MySQL database:

8.4.3 Testing Database Connection
In the Test Database Connection page, you should check the Data Base URL.
For SugarCRM and Foodmart, it should be correct by default:
jdbc:mysql://localhost:3306/sugarcrm
jdbc:mysql://localhost:3306/foodmart
The URL for JasperServer Data Base should be changed to the following:
8.4.4 Selecting Targets
All data sources should be checked AdminServer.
8.5 Deleting JARs and Setting Configurations in the WAR File
As of JasperServer 4.0, you must delete a number of JasperServer jar files so that they do not conflict with Weblogic jars.
Additionally, you will need to update your Hibernate, Quartz, and Mail Server config.
Unpack the jasperserver-pro.war file
The jasperserver-pro.war file will be unpacked and turned into a folder. You can use the Java jar tool to unpack or you can
use an unzip. These instructions will use the jar tool:
Database Driver MySQLs Driver (Type 4)
Versions: using
com.mysql.jdbc.Driver
MySQLs Driver (Type 4)
Versions: using
MySQLs Driver (Type 4)
Versions: using
Supports Global
Transactions
Selected Selected Selected
One-Phase Commit Selected Selected Selected
Parameter Name JasperReports Server Foodmart Example Sugar CRM Example
Database Name jasperserver foodmart sugarcrm
Host Name localhost localhost localhost
Port 3306 3306 3306
Database User Name root root root
Password password password password
Confirm Password password password password
mkdir jasperserver-pro
cd jasperserver-pro
"%JAVA_HOME%/bin/jar" xvf ../jasperserver-pro.war
78
Delete conflicting JARs
cd jasperserver-pro/WEB-INF/lib
Delete the following jars:
xercesImpl-<ver>.jar
xml-apis-<ver>.jar
xml-apis-ext-<ver>.jar
xalan-<ver>.jar
serializer-<ver>.jar
Update Hibernate, Quartz, and Mail Server settings
1. Open the file jasperserver-pro/WEB-INF/hibernate.properties for editing and locate the
metadata.hibernate.dialect property. Set its value according to your database:
2. Open the file jasperserver-pro/WEB-INF/js.quartz.properties for editing and locate the
report.scheduler.web.deployment.uri property. Set its value to the hostname, port, and path where you intend to
deploy JasperReports Server, for example:
report.scheduler.web.deployment.uri=http://localhost:7001/jasperserver-pro
If you are using PostgreSQL or DB2, set the Quartz delegate class in the js.quartz.properties file:
3. If you want to configure JasperReports Server to automatically schedule and email reports, enter your mail server
information ) 4] O4C4=OEO]4)] )]. Modify all
report.scheduler.mail.sender.* properties as necessary for your mail server.
If your mail server requires authentication, edit the applicationContext-report-scheduling.xml file in the same manner:
4. Open the jasperserver-pro/WEB-INF/applicationContext-report-scheduling.xml file for editing and locate the
reportSchedulerMailSender bean.
5. Set the javaMailProperties key="mail.smtp.auth" value to true.
jasperserver-pro folder complete
You now have a jasperserver-pro folder that can be used for deploying to WebLogic.
8.6 Additional Changes for WebLogic 10.3.0
Edit the weblogic.xml file as described below:
1. Go to the unpacked jasperserver-pro/WEB-INF folder:
cd jasperserver-pro/WEB-INF
2. Open the file weblogic.xml for editing and locate the following element:
3. Remove the entire session-descriptor element shown above (or comment it out).
PostgreSQL: quartz.delegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
DB2: quartz.delegateClass=org.quartz.impl.jdbcjobstore.DB2v8Delegate
All others: quartz.delegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
<session-descriptor>
<cookie-http-only>false</cookie-http-only>
</session-descriptor>
79
8.7 Preparing the WebLogic Domain
In this section, <wl-domain> is the path of the domain within WebLogic that contains your JasperReports Server deployment.
For example <weblogic>/samples/domains/wl_server.
8.7.1 Editing the Domain Configuration File
Edit your WebLogic domain configuration file <wl-domain>/config/config.xml. Locate the server and security-
configuration elements, and insert the following parameters:
It is important that the stuck-thread-max-time element appear above the listen-address element before the closing
</server> tag.
8.7.2 Preparing the Domain Library
For WebLogic 9.2 only, copy the following file:
<js-install>/buildomatic/conf_source/db/mysql/jdbc/mysql-connector-java-5.1.10.jar
To: <wl-domain>/lib/
8.7.3 Setting Java Properties
Edit your WebLogic startup script to include the settings described in the following tables, according to your platform. Enter
each command on a single line, and substitute the location of your JasperReports Server license file where necessary:
<server>
...
<stuck-thread-max-time>1200</stuck-thread-max-time>
<listen-address></listen-address>
</server>
<security-configuration>
...
<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
</security-configuration>
WebLogic Startup Settings on Windows
Filename <wl-domain>\bin\startWebLogic.cmd
All versions
of WebLogic
set JAVA_OPTIONS=%JAVA_OPTIONS% -Djs.license.directory=C:\Jasperserver-pro\
-Dfile.encoding=UTF-8 -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0
WebLogic 10
and 10.3
set JAVA_OPTIONS=%JAVA_OPTIONS% -Xms256m -Xmx1024m -XX:PermSize=128m
-XX:MaxPermSize=256m -Xss2m -XX:+UseConcMarkSweepGC -
XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled
80
For WebLogic 9.2, you must also update the JRockit JDK from jrockit90_150_04 to jrockit_150_11. For more information
about JDKs with WebLogic 9.2, refer to the product documentation.
8.8 Deploying JasperReports Server to WebLogic
Now that the databases are created and all files are configured, you can deploy the JasperReports Server WAR file in
WebLogic.
1. In the Administrative Console, click the Lock & Edit button and navigate to Deployments.
2. On the Deployments page click the Install button.
3. Select the path to <js-install>.
4. Select the servers or clusters to which you want to deploy JasperReports Server.
5. When prompted, enter the following parameter values:
1. In the Administrative Console, navigate to Deployments.
2. Select the jasperserver-pro application with a checkmark, and click Start.
3. In the Start Application Assistant page, click Yes.
1. Login by going to the following URL:
Where <hostname> could be localhost, a machine name, or an IP address. The login page should appear after some time
to compile the necessary JSP files.
WebLogic Startup Settings on Linux
Filename <wl-domain>/bin/startWebLogic.sh
All versions export JAVA_OPTIONS="$JAVA_OPTIONS
-Djs.license.directory=/home/<user>/weblogic/jasperlicense/
-Dfile.encoding=UTF-8 -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0
-Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl"
WebLogic 10
and 10.3
export JAVA_OPTIONS="$JAVA_OPTIONS -Xms256m -Xmx1024m -XX:PermSize=128m
-XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled"
Parameter Name Example Value
Name jasperserver-pro
Security Custom Roles and Policies
Source accessibility Use the defaults defined by the deployment's targets
81
2. Use the following credentials to log into the system:
If you logged in successfully, the JasperReports Server home page appears.
Refer to the JasperReports Server User Guide to begin adding reports and other resources to JasperReports Server.
8.11 Configuring Report Scheduling
The scheduled reporting feature of JasperReports Server allows reports to be run at pre-configured time intervals. Optionally,
notification emails can be set to users to let them know that new reports are available.
For more information about setting up report scheduling, refer to section 6.9, Report Scheduling Configuration with
Quartz, on page 57.
8.12 Restarting JasperReports Server
If you have made configuration changes to your JasperReports Server instance, you should restart JasperReports Server.
8.13 Updating XML/A Connection Definitions (Optional)
If you have loaded the JasperReports Server sample data, and you would like to run the Analysis XML/A examples, you will
need to update the XML/A connection resources to use the correct web port.
The typical port used by WebSphere is 7001. Follow the procedure in section 6.10, Notes on Updating XML/A Connection
8.14 Troubleshooting Your JasperReports Server Configuration
8.14.1 Startup Problems
When trying to run a new JasperReports Server instance, most typical problems encountered are errors in the database
configuration.
application server configuration files. For more information on resolving these types of errors, refer to troubleshooting
section A.2, Database Connectivity Errors, on page 118.
8.14.2 Error Running Report
The first time you log into JasperReports Server, you will be prompted to opt-in or opt-out of the JasperReports Server
Heartbeat. For more information, refer to section 5.11.1, JasperReports Server Heartbeat, on page 36.
82
Upgrade from 3.7 to 4.1
83
CHAPTER 9 UPGRADE FROM 3.7 TO 4.1
It is typical for JasperReports Server to have database schema updates with new major or minor releases. However, in the case
of release 4.1, there are no database changes between 4.0 and 4.1.
Because of this, the best procedure to upgrade from 4.0 to 4.1 is the procedure described in Chapter 10, Upgrade from 4.0
to 4.1, on page 91.
Because there are no database changes, it is also possible to upgrade from release 3.7 to release 4.1 in one set of steps. This
current chapter describes the recommended procedure for upgrading from 3.7 to 4.1.
These steps use the JasperReports Server WAR File Distribution ZIP release package and the included buildomatic scripts for
the upgrade procedure.
Standard Upgrade Steps
Backing Up Your JasperServer 3.7 Instance
Export Your 3.7 Repository Data
Preparing the JasperReports Server 4.1 WAR File Distribution
Configuring Buildomatic for Your Database and Application Server
Upgrading to JasperReports Server 4.1
Starting JasperReports Server 4.1
Logging into JasperReports Server 4.1
Additional Notes on JasperReports Server Upgrade
Older Manual Upgrade Steps
9.1 Standard Upgrade Steps
This section lists the standard upgrade steps. These general steps are always available with each new JasperReports Server
release.
1. Back up your 3.7 JasperServer instance.
2. Export your 3.7repository data.
3. Download and setup the 4.1 JasperReports Server WAR file distribution zip.
There are no database changes between 4.0 to 4.1. To upgrade from 4.0 to 4.1 use the steps described in
Chapter 10, Upgrade from 4.0 to 4.1, on page 91.
84
4. Run auto-upgrade script.
If your instance of JasperServer 3.7 has any custom modifications or extensions, you will need to keep track of these and re-
integrate them into your 4.1 instance after the upgrade is complete.
9.2 Backing Up Your JasperServer 3.7 Instance
First you must backup your JasperServer WAR file and your jasperserver database so that they can be restored in case there is
a problem with the upgrade. These steps are performed from the command line in a Windows or Linux shell.
The following instructions are for the MySQL database. For other databases, consult your DB administration documentation
for back up information.
1. Back up the jasperserver-pro directory in Tomcat to a backup directory:
2. Back up the jasperserver database. Go to the location where you originally unpacked the 3.7 WAR file distribution zip or
installed from the JasperServer 3.7 installer:
a. cd <js-install-3.7> (the location of your original unpacked 3.7 WAR file distribution)
b. Run the following command:
9.3 Export Your 3.7 Repository Data
You will need to export your 3.7 repository data using the JasperReports Server export utility. There are two ways to export.
One is using the buildomatic scripts (if you originally installed using buildomatic). Or you will use the js-export.bat/.sh script
found in the <js-install>/scripts folder.
9.3.1 Export Using Buildomatic Scripts
If you have buildomatic and your default_master.properties file configured, you can export your 3.7 repository data using the
following commands:
1. cd <js-install-3.7>/buildomatic
2. Run buildomatic with the export target:
This operation uses the export option --everything which exports all your repository data.
Note the location of this export file so that you can point to it for the 4.1 upgrade.
cd <tomcat>
mkdir js-3.7-war-backup
copy <tomcat>/webapps/ jasperserver-pro to <tomcat>/js-3.7-war-backup
delete the <tomcat>/webapps/jasperserver-pro directory
Windows: mysqldump --user=root --password=<password> jasperserver > js-db-3.7-dump.sql
Linux: mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver >
js-db-3.7-dump.sql
If you installed the previous release from the installer, specify --user=jasperdb in this command.
If you receive a packet size error, see section A.2.6, Maximum Packet Size in MySQL, on page 120.
Jaspersoft has tested the mysqldump utility for backing up and restoring MySQL databases, but there are
other MySQL backup mechanisms, some of which may work better for your JasperServer installation.
Windows: js-ant.bat export-everything -DexportFile=js-3.7-export.zip
Linux: ./js-ant export-everything -DexportFile=js-3.7-export.zip
85
9.3.2 Export Using js-export Script
To use the js-export.bat/.sh script, you will move to the <js-install-3.7>/scripts folder. If you are using the MySQL database
then the js-export script should already be configured to run. If you are using a different database, or you have changed
database passwords you will need to update the js-export configuration. For information on configuring the 3.7 import-export
utility see section 14.6, Configuring the Import-Export Utility for JasperServer 3.7, on page 115.
1. cd <js-install-3.7>/scripts
2. Run the export script:
This operation uses the export option --everything which exports all your repository data.
Note the location of this export file so that you can point to it for the 4.1 upgrade.
9.4 Preparing the JasperReports Server 4.1 WAR File Distribution
We will use the buildomatic scripts included in the 4.1 WAR file distribution ZIP release package in order to carry out the
upgrade. Follow the steps in the sections listed below to obtain and unpack the WAR file distribution ZIP file:
1. Follow steps in section 5.2, Obtaining the WAR File Distribution Zip, on page 30.
2. Follow steps in section 5.3, Unpacking the WAR File Distribution Zip, on page 30.
After you unpack the WAR File Distribution Zip, the resulting location will be known as:
<js-install-4.1>
9.5 Configuring Buildomatic for Your Database and Application Server
This upgrade procedure is based on using the buildomatic scripts which are included with the WAR File Distribution ZIP
release package. The buildomatic scripts are based on the ant utility and require the Java Development Kit (JDK) to run. If
you dont have Java available in your environment, see section 9.9.1, Handling JasperReports Server Customizations,
on page 87.
Follow the configuration steps that match your database and application server in section 5.6, Configuring the Buildomatic
Scripts, on page 32. Below is an example configuration using the MySQL database.
9.5.1 Example Buildomatic Configuration (using MySQL)
All upgrade configuration is handled by a single file that is named default_master.properties. Jaspersoft provides a sample
configuration file for each database. You must specify your database credentials and your application server location, and
rename the file to default_master.properties.
This procedure uses MySQL as an example (the same general logic applies to other databases).
You must rename and copy the sample file to this location: <js-install-4.1>/buildomatic.
1. Locate the mysql_master.properties file:
Windows: js-export.bat --everything --output-zip js-3.7-export.zip
Linux: js-export.sh --everything --output-zip js-3.7-export.zip
There are no database changes between 4.0 to 4.1. If you are upgrading from 4.0 to 4.1, use the steps described
in Chapter 10, Upgrade from 4.0 to 4.1, on page 91 instead.
MySQL <js-install-4.1>/buildomatic/sample_conf/mysql_master.properties
86
2. Copy the file to <js-install-4.1>/buildomatic.
3. Rename the file default_master.properties.
4. Edit default_master.properties for your database and application server:
9.6 Upgrading to JasperReports Server 4.1
Now that your buildomatic scripts have been configured, you can complete the upgrade. Run the following commands:
The auto-upgrade script creates an output log that captures standard output and error output. If there are any problems during
<js-install>/buildomatic/logs/js-upgrade-<date>-<number>.log
9.6.2 Errors
If you encounter errors during the auto-upgrade script execution, you should start by looking at the output log to see if you
can spot any errors. Additionally, you should refer to the Troubleshooting section 5.12, Troubleshooting Your
JasperReports Server Configuration, on page 37. The information in this section applies to both auto-upgrade scripts
and the auto-install scripts.
MySQL appServerType=tomcat6 (or tomcat, jboss, glassfish)
appServerDir=c:\\apache-tomcat-6.0.26 (for example)
dbUsername=root
dbPassword=password
dbHost=localhost
There are no database changes between 4.0 to 4.1. If you are upgrading from 4.0 to 4.1 use the steps described
in Chapter 10, Upgrade from 4.0 to 4.1, on page 91 instead.
Make sure you have backed up your jasperserver database before proceeding.
Make sure you have backed up your JasperServer 3.7 WAR file before proceeding.
cd <js-install-4.1>/buildomatic
js-upgrade-newdb.bat <path>/js-3.7-export.zip (Windows) Upgrade jasperserver-pro war file,
drop and recreate database, import 3.7 data
js-upgrade-newdb.sh <path>/js-3.7-export.zip (Linux) Upgrade jasperserver-pro war file, data,
drop and recreate database, import 3.7 data
You can use a fully specified path or a relative path. If the path you specify has spaces in it, you should use
quotation marks: <path>/js-3.7-export.zip
On MySQL, if you receive an error about packet size, see section A.2.6, Maximum Packet Size in
MySQL, on page 120.
87
If you need to modify values in your default_master.properties file, you can simply edit the file. When the auto-
upgrade script is run again, the new values will used.
9.7 Starting JasperReports Server 4.1
You may now start your Tomcat, JBoss, or GlassFish application server. Your database should already be running.
9.8 Logging into JasperReports Server 4.1
If your application server and JasperReports Server 4.1 were started cleanly, you can now prepare to login.
9.8.1 Clearing Your Browser Cache
Before you log into 4.1, make sure and clear your Browser cache. JavaScript files, which enable UI elements of JasperReports
Server, are typically cached by the Browser. The cache should be cleared to ensure that the most current files are used.
For JasperReports Server 4.1, the UI has been significantly enhanced. It will be very important to clear the browser cache.
Your end users should also be reminded to clear their Browser caches before logging in.
Login using the following URL, user IDs, and passwords:
URL: http://localhost:8080/jasperserver-pro
Your JasperReports Server instance has now been upgraded to 4.1. If there are problems on startup or login refer to
troubleshooting section A.2, Database Connectivity Errors, on page 118.
9.9 Additional Notes on JasperReports Server Upgrade
9.9.1 Handling JasperReports Server Customizations
If you made modifications or customizations to your JasperServer 3.7 application, these configurations are typically found in
the WEB-INF/applicationContext-*.xml set of files.
Configuration modifications such as client specific security classes or LDAP server configurations, need to be hand copied
from the older 3.7 environment and re-integrated into the new 4.1environment.
9.9.2 Clearing the Application Server Work Directory
Application servers have work directories where JSP files are compiled and cached and other objects are stored. Before you
update to a new WAR file or license, the /work directory should be cleared. The buildomatic deploy-webapp target
superuser <your-password> System-wide administrator
jasperadmin <your-password> Administrator for the default organization
If you updated your sample data in the sections above, your jasperadmin password might be reset to
jasperadmin. You should change it as soon as possible.
88
automatically clears the application servers work directory but it is a good practice to double-check (in case of permission
issues, etc).
To clear the /work directory in Tomcat, for instance, you would do the following:
1. Change directory to <tomcat>/work.
2. Delete all the files and folders in this directory.
9.9.3 Clearing the Application Server Temp Directory
JasperReports Server uses caching to speed operations within the application. In the application server, caching files are
created and stored for this caching functionality. Typically, these cached files are stored in a /temp directory. It is a good
practice to clear this /temp folder to avoid any conflicts after the upgrade is complete.
To clear the /temp directory in Tomcat, for instance, you would do the following:
1. Change directory to <tomcat>/temp
2. Delete all the files and folders in this directory
9.9.4 Clearing the Repository Cache Table
In the jasperserver database, compiled JasperReports Library resources are cached in the JIRepositoryCache table for
increased efficiency at runtime. In some cases, you may encounter errors running reports after an upgrade. Because the
JasperReports Library JAR is typically updated with each new JasperReports Server release, old cached items can get out of
date and thus cause errors at runtime. If you encounter errors that mention a JasperReports Library local class incompatible,
you should check your repository cache table. In summary, you can clear your jasperserver database cache table whether there
are errors or not as part of this upgrade process.
To manually clear this table, run a SQL command similar to the following:
update JIRepositoryCache set item_reference = null;
delete from JIRepositoryCache;
9.9.5 Updating the XML/A Connections (Optional)
When you upgrade your sample data to 4.1, your XML/A connection sample data will be updated. XML/A connections use
JasperReports Server login accounts for authentication. Because of this, and because you would normally modify your default
jasperadmin password as a standard security procedure, your XML/A connection may fail due to a mismatched password.
If you would like to update your XML/A connections, refer to section 6.10, Notes on Updating XML/A Connection
9.9.6 Upgrading the Liferay Portal
JasperReports Server can be configured to run with the Liferay Portal. If your JasperReports Server is set up to run with
Liferay, you must do the following steps as part of the upgrade process.
1. You will need to delete the webapps/Jaspersoft folder of the application server hosting Liferay. This deletes libraries used
in older versions that conflict with libraries in the latest version.
2. Once this folder is deleted, you can deploy the new portlet WAR.
For more information, refer to the JasperReports Server Administrator Guide.
You can clear your server repository cache manually using the above command (or a similar command).
89
9.10 Older Manual Upgrade Steps
This section has some of the older, manual upgrade steps that were in place before the auto-upgrade shell scripts were
implemented for JasperReports Server release 4.0. These are here as a reference. It is recommended that you use the auto-
upgrade steps from the top of this upgrade chapter.
9.10.1 Manual Upgrade Steps
Older buildomatic targets upgrade steps:
js-ant drop-js-db
js-ant create-js-db
This will delete your jasperserver db. Make sure it is backed
up.
js-ant import-minimal-pro
js-ant import-upgrade
-DimportFile="<path-and-filename>"
The -DimportFile should point to the <path> and <filename>
of the js-3.7-export.zip file you created earlier.
On Windows, you must use double quotes (") if your path or
filename contains spaces. On Linux, you must use double
quotes escaped with a backslash (\") in this case.
js-ant import-sample-data-upgrade-pro This step is optional; it loads the 4.1 sample data. The old
sample data is overwritten, so you may need to redo certain
changes such as configuring the sample data sources for
your database.
js-ant deploy-webapp-pro Delete existing 3.7 war file, deploy 4.1 war file.
MySQL, on page 120.
90
91
CHAPTER 10 UPGRADE FROM 4.0 TO 4.1
This chapter covers how to upgrade a commercial version of JasperReports Server 4.0 to a commercial version of
JasperReports Server 4.1.
This section uses an auto-upgrade shell script to carry out the upgrade. This script will update your JasperServer repository
database resources with the new 4.1 resources, and it will deploy the 4.1 WAR file to your application server.
Upgrade Steps
Backing Up Your JasperServer 4.0 Instance
Preparing the JasperReports Server 4.1 WAR File Distribution
Upgrading to JasperReports Server 4.1
Starting JasperReports Server 4.1
Logging into JasperReports Server 4.1
Additional Information on Post-Upgrade Steps
Running Buildomatic DB Upgrade Steps Manually
10.1 Upgrade Steps
These are the general steps used in this section.
1. Back up your 4.0 JasperServer instance.
2. Download and setup the 4.1 JasperReports Server WAR file distribution zip.
3. Run auto-upgrade script.
If your instance of JasperServer 4.0 has any custom modifications or extensions, you will need to keep track of these and re-
integrate them into your 4.1 instance after the upgrade is complete.
There are no database changes between 4.0 and 4.1. So this upgrade procedure will work for all database types.
The procedure in this chapter is the recommended upgrade path.
92
10.2 Backing Up Your JasperServer 4.0 Instance
First you must backup your JasperServer WAR file and your jasperserver database so that they can be restored in case there is
a problem with the upgrade. These steps are performed from the command line in a Windows or Linux shell.
The following instructions are for the MySQL database. For other databases, consult your DB administration documentation
for back up information.
10.2.1 Backing Up Your JasperServer WAR File
Back up the jasperserver-pro directory in Tomcat to a backup directory.
1. Go to the <tomcat> directory.
2. Make a new directory named js-4.0-war-backup.
3. Copy <tomcat>/webapps/ jasperserver-pro to <tomcat>/js-4.0-war-backup.
4. Delete the <tomcat>/webapps/jasperserver-pro directory.
10.2.2 Backing Up Your JasperServer Database
Go to the location where you originally unpacked the 4.0 WAR file distribution zip.
1. Go to the <js-install-4.0> (the location of your original unpacked 4.0 WAR file distribution).
2. Run the following command:
10.3 Preparing the JasperReports Server 4.1 WAR File Distribution
We will use the buildomatic scripts included in the 4.1 WAR file distribution ZIP release package in order to carry out the
upgrade. Follow the steps in the sections listed below to obtain and unpack the WAR file distribution ZIP file:
1. Follow steps in section 5.2, Obtaining the WAR File Distribution Zip, on page 30.
2. Follow steps in section 5.3, Unpacking the WAR File Distribution Zip, on page 30.
<js-install-4.1>
release package. The buildomatic scripts are based on the ant utility and require the Java Development Kit (JDK) to run. If
you dont have Java available in your environment, see section 9.9.1, Handling JasperReports Server Customizations,
on page 87.
Windows: mysqldump --user=root --password=<password> jasperserver > js-db-4.0-dump.sql
js-db-4.0-dump.sql
If you receive an error about packet size, see section A.2.6, Maximum Packet Size in MySQL, on page 120.
93
All upgrade configuration is handled by a single file that is named default_master.properties. Jaspersoft provides a sample
configuration file for each database. You must specify your database credentials and your application server location, and
rename the file to default_master.properties.
This procedure uses MySQL as an example (the same general logic applies to other databases).
You must rename and copy the sample file to this location: <js-install-4.1>/buildomatic.
1. Locate the mysql_master.properties file:
2. Copy the file to <js-install-4.1>/buildomatic.
3. Rename the file to default_master.properties.
10.5 Upgrading to JasperReports Server 4.1
Now that your buildomatic scripts have been configured, you can complete the upgrade. Run these commands to upgrade a
commercial version of JasperReports Server 4.0 to a commercial version of JasperReports Server 4.1:
To upgrade the Community Project version of the server, see Chapter 12, Upgrading From Community Project, on
page 99.
The auto-upgrade script creates an output log that captures standard output and error output. If there are any problems during
<js-install>/buildomatic/logs/js-upgrade-<date>-<number>.log
MySQL <js-install-4.1>/buildomatic/sample_conf/mysql_master.properties
MySQL appServerType=tomcat6 (or tomcat5, jboss, glassfish)
dbUsername=root
dbPassword=password
dbHost=localhost
Make sure you have backed up your JasperServer 4.0 WAR file before proceeding.
js-upgrade-samedb.bat Upgrade jasperserver-pro war file, add 4.1 repository
resources into the jasperserver database (for Windows)
js-upgrade-samedb.sh Upgrade jasperserver-pro war file, add 4.1 repository
resources into the jasperserver database (for Linux)
94
10.5.2 Errors
If you encounter errors during the auto-upgrade script execution, you should start by looking at the output log to see if you
can spot any errors. Additionally, you should refer to the Troubleshooting section 5.12, Troubleshooting Your
JasperReports Server Configuration, on page 37. The information in this section applies to both auto-upgrade scripts
and the auto-install scripts.
If you need to modify values in your default_master.properties file, you can simply edit the file. When the auto-upgrade script
is run again, the new values will used
10.6 Starting JasperReports Server 4.1
10.7 Logging into JasperReports Server 4.1
If your application server and JasperReports Server 4.0were started cleanly, you can now prepare to login.
Before you log into 4.1, make sure and clear your Browser cache. JavaScript files, which enable UI elements of JasperReports
Server, are typically cached by the Browser. The cache should be cleared to ensure that the most current files are used.
For JasperReports Server 4.1, the UI has been significantly enhanced. It will be very important to clear the browser cache.
You may now log into JasperReports Server using the same URL and credentials that you used before the upgrade.
10.8 Additional Information on Post-Upgrade Steps
There is additional information on optional steps that can be done after the main upgrade steps are complete. See section 9.9,
Additional Notes on JasperReports Server Upgrade, on page 87.
10.8.1 Clearing the Repository Cache Table
In the jasperserver database, compiled JasperReports Library resources are cached in the JIRepositoryCache table for
increased efficiency at runtime. In some cases, you may encounter errors running reports after an upgrade. Because the
JasperReports Library JAR is typically updated with each new JasperReports Server release, old cached items can get out of
date and thus cause errors at runtime. If you encounter errors that mention a JasperReports Library local class incompatible,
you should check your repository cache table. In summary, you can clear your jasperserver database cache table whether there
are errors or not as part of this upgrade process.
To manually clear this table, run a SQL command similar to the following:
update JIRepositoryCache set item_reference = null;
delete from JIRepositoryCache;
You can clear your jasperserver repository cache manually using the above command (or a similar command).
95
10.9 Running Buildomatic DB Upgrade Steps Manually
The auto-upgrade scripts (js-upgrade-samedb.bat/.sh) execute buildomatic Ant targets in order to carry out the upgrade. Here
are the key buildomatic targets executed by the auto-upgrade scripts:
js-ant upgrade-4.0-4.1-pro Execute SQL script for database upgrade to 4.1.
Executes script buildomatic/install_resources/sql/<dbType>/
upgrade-<dbType>-4.0.0-4.1.0-pro.sql
(Note: This upgrade script is a dummy script, but this manual
step is kept in place for consistency.)
js-ant import-minimal-for-upgrade-pro Loads themes and other core resources for 4.1.
js-ant import-sample-data-upgrade-pro (Optional) This step is optional. Loads the 4.1 sample data.
js-ant deploy-webapp-pro Delete existing 4.0 war file, deploy 4.1 war file.
96
Upgrade Notes for JasperServer 3.7
97
CHAPTER 11 UPGRADE NOTES FOR JASPERSERVER 3.7
If you are currently running JasperReports Server 3.7, then you can follow the set of steps in Chapter 9 Upgrade from 3.7 to
4.1 in order to upgrade to 4.1
If you are running a JasperReports Server version older than 3.7, then you will first have to upgrade to 3.7 before you can
upgrade to 4.1. In order to upgrade to 3.7, you should download the WAR File Distribution zip package for 3.7 (jasperreports-
server-3.7-bin.zip).
11.1 Upgrade from JasperServer 3.5
If your current instance is JasperServer 3.5, you must first upgrade to version 3.7 before upgrading to 4.1. The steps to carry
out a 3.5 to 3.7 upgrade are documented in the JasperServer Installation Guide for the 3.5 release. You will need to download
the JasperServer 3.5 release package to get the relevant files and documentation. To download the JasperServer 3.5 WAR file
distribution zip package, go to the Jaspersoft Technical Support product downloads area. Or contact Technical Support or your
sales representative.
98
Upgrading From Community Project
99
CHAPTER 12 UPGRADING FROM COMMUNITY PROJECT
If you are currently running a Community Edition (CE) instance of JasperReports Server 4.1 and you would like to upgrade to
a commercial version of JasperReports Server, you may follow the instructions in this chapter.
Jaspersofts Community Edition is now being called Community Project. JasperReports Server Professional is now being
called a commercial version of JasperReports Server.
To upgrade a commercial version of JasperReports Server 4.0 to a commercial version of JasperReports Server 4.1, see
Chapter 10, Upgrade from 4.0 to 4.1, on page 91.
The steps in this section will use the JasperReports Server commercial WAR File Distribution release package and the
included buildomatic scripts to carry out the upgrade.
General Procedure
Backing Up Your JasperReports Server CE Instance
Exporting Your CE Repository Data
Preparing the JasperReports Server Pro 4.1 WAR File Distribution
Upgrading to JasperReports Server Pro
Starting JasperReports Server Pro
Logging into JasperReports Server Pro
Additional CE to Pro Upgrade Notes
12.1 General Procedure
In order to carry out the upgrade procedure, you will be doing the following main steps:
1. Back up your JasperReports Server CE instance.
2. Export your CE repository data.
3. Upgrade your instance to JasperReports Server Professional.
4. Import your CE repository data.
This CE to commercial upgrade procedure is only valid for upgrade within a major JasperReports Server release. For
instance, 4.0.x CE to 4.1.0 Professional. or 4.1 CE to 4.1 Professional.
100
If your instance of JasperReports Server CE has any custom modifications or extensions, you will need to keep track of these
and re-integrate them into your JasperReports Server Professional instance after the upgrade is complete.
12.2 Backing Up Your JasperReports Server CE Instance
First you must backup your JasperReports Server CE WAR file and your jasperserver database so that they can be restored in
case there is a problem with the upgrade. These steps are performed from the command line in a Windows or Linux shell.
The following instructions are for the Tomcat application server and the MySQL database. For other application servers you
should do steps similar to what is described below. For other databases, consult your DB administration documentation for
back up information.
12.2.1 Backing Up Your JasperReports Server CE WAR File
Back up the jasperserver directory in Tomcat to a backup directory.
1. Go to the <tomcat> directory.
2. Make a new directory named js-ce-war-backup.
3. Copy <tomcat>/webapps/ jasperserver to <tomcat>/js-ce-war-backup.
4. Delete the <tomcat>/webapps/jasperserver directory.
12.2.2 Backing Up Your JasperReports Server Database
Go to the location where you originally unpacked your CE WAR file distribution zip.
1. Go to the <js-install-ce> directory.
2. Run the following command:
12.3 Exporting Your CE Repository Data
You should first check to see that you have the following file in place in your buildomatic directory: default_master.properties.
This file holds the settings that are specific to your JasperReports Server instance. Such as your application server type and
location, and your database type and location.
You should see this file in the following location:
<js-install-ce>/buildomatic/default_master.properties
If you do not have a default_master.properties file in place, then you should go to the following section for instructions on how
to set up this file. See section 5.6.1, Creating your Default Master Properties File, on page 32.
To export your CE repository data:
1. cd <js-install-ce>/buildomatic
2. Run buildomatic with the export target:
Windows: mysqldump --user=root --password=<password> jasperserver > js-db-ce-dump.sql
js-db-ce-dump.sql
If you installed JasperReports Server CE from the installer, you may specify --user=jasperdb in this
command.
If you receive an error about packet size, see section A.2.6, Maximum Packet Size in MySQL, on page 120.
Windows: js-ant.bat export-everything-ce -DexportFile=js-ce-export.zip
Linux: ./js-ant export-everything-ce -DexportFile=js-ce-export.zip
101
This operation uses the export option --everything which preserves all your repository data.
Remember the path to your exported file, because you will need to specify it when you import into JasperReports Server
Professional.
12.4 Preparing the JasperReports Server Pro 4.1 WAR File Distribution
We will use the buildomatic scripts included in the Pro WAR file distribution release package in order to carry out the
upgrade. Follow the steps in the sections listed below to obtain and unpack the Pro WAR file distribution ZIP file:
Follow steps in section 5.2, Obtaining the WAR File Distribution Zip, on page 30.
Follow steps in section 5.3, Unpacking the WAR File Distribution Zip, on page 30.
<js-install-pro>
release package. The buildomatic scripts are based on the ant utility and require the Java Development Kit (JDK) to run. If you
dont have Java available in your environment, see section 9.9.1, Handling JasperReports Server Customizations, on
page 87.
All upgrade configuration is handled by a single file which will be named default_master.properties. You will need to specify
your database credentials and your application server location.
There is a sample configuration file for each database. This procedure uses MySQL as an example (the same general logic
applies to other databases).
The sample file will be renamed and copied to the following location: <js-install-pro>/buildomatic
1. Copy mysql_master.properties.
2. To: <js-install-pro>/buildomatic
3. Rename to: default_master.properties
MySQL <js-install-pro>/buildomatic/sample_conf/mysql_master.properties
MySQL appServerType=tomcat6 (or tomcat5, jboss, glassfish)
dbUsername=root
dbPassword=password
dbHost=localhost
102
12.6 Upgrading to JasperReports Server Pro
Now that your buildomatic scripts have been configured, you can complete the upgrade. Stop your application server and run
the following commands:
12.7 Starting JasperReports Server Pro
Before starting the server:
1. Delete any files that might exist in the <tomcat-install>\temp directory.
2. Delete any files, directories, or sub-directories that exist in the <tomcat-install>\work directory.
3. Delete any jasperserver* file that exists in the directory: <tomcat-install>\conf\Catalina\localhost.
4. Move any existing <tomcat-install>\logs files into a backup directory to clean up old CP log data. (optional).
For information about how to clear directories, see sections 9.9.2, Clearing the Application Server Work Directory, on
page 87, 9.9.3, Clearing the Application Server Temp Directory, on page 88, and 9.9.4, Clearing the Repository
Cache Table, on page 88.
12.8 Logging into JasperReports Server Pro
If your application server and JasperReports Server Pro were started cleanly, you can now prepare to login.
cd <js-install-pro>/buildomatic
js-ant drop-js-db
js-ant create-js-db
The first command will delete your jasperserver db. Make
sure it is backed up. The other commands will recreate and
initialize the database.
js-ant import-minimal-for-upgrade-pro Creates superuser and default tenant structure.
js-ant import-upgrade
-DimportFile="<path-and-filename>"
The -DimportFile argument should point to the
js-ce-export.zip file you created earlier.
On Windows, you must use double quotes (") if your path or
filename contains spaces. On Linux, you must use double
quotes escaped with a backslash (\") in this case.
js-ant import-minimal-pro Load resources needed by JasperReports Server pro.
js-ant import-sample-data-upgrade-pro (Optional) This step is optional. Loads the pro sample data.
js-ant deploy-webapp-ce-to-pro Delete CE war file, deploy pro war file.
MySQL, on page 120.
103
Before you log into JasperReports Server, make sure and clear your browser cache. JavaScript files, which enable UI elements
of JasperReports Server, are typically cached by the Browser. The cache should be cleared to ensure that the most current files
are used.
12.8.2 Logging into JasperReports Server Pro
Login using the following URL, user IDs, and passwords:
URL: http://localhost:8080/jasperserver-pro
Your JasperReports Server instance has now been upgraded from Community Edition (CE) to commercial. If there are
problems on startup or login refer to troubleshooting section A.2, Database Connectivity Errors, on page 118.
12.9 Additional CE to Pro Upgrade Notes
This section has additional notes for both before upgrade and after upgrade.
12.9.1 Notes on XML/A Configuration After Upgrade to Pro
XML/A connection definitions contain a username and password definition in order to make the Web Services connection to
the server. A commercial edition of JasperReports Server supports multi-tenancy which allows multiple organizations to co-
existing on a single instance. JasperReports Server users must belong to a specific organization (except for superuser). The
default organization in JasperReports Server is organization_1.
Therefore after upgrade, any XML/A connections that you have will need to be updated to include the Organization that the
user belongs to. After the upgrade operation, users will belong to the default organization that is part of the core data setup in
the commercial edition.
In addition, the XML/A connection specifies an instance URI. This URI will need to be updated to point to a commercial URI.
You should edit your XML/A connections to specify the following:
Change user IDs from, for example:
jasperadmin to jasperadmin|organization_1
joeuser to joeuser|organization_1
Change the URI value from, for instance:
http://localhost:8080/jasperserver/xmla
To:
http://localhost:8080/jasperserver-pro/xmla
If you updated your sample data in the sections above, your password might be reset to the default
jasperadmin. You should change it as soon as possible.
104
Changing Password Encryption in JasperReports Server
105
CHAPTER 13 CHANGING PASSWORD ENCRYPTION IN JASPERREPORTS
SERVER
By default, password encryption is enabled in JasperReports Server and passwords are stored as cipher text in the database.
System administrators can change the encryption algorithm, as well as specify the salt key used to initiate the encryption
algorithm.
This chapter describes the procedure to enable password encryption if you have a JasperReports Server instance without
encryption turned on. For more information on encryption options, refer to the JasperReports Server Administrator Guide.
Backing Up Your JasperReports Server Database
Stopping Your Application Server
Running the Repository Export Utility
Specifying Encryption Settings in the JasperReports Server WAR
Specifying Encryption Settings for the Import Utility
Recreating the JasperReports Server Database
Importing Your Repository Data
Starting the Application Server
13.1 Backing Up Your JasperReports Server Database
As a precaution, you must back up your jasperserver database in case there is any problem while enabling encryption.
To back up the default MySQL database, go to the <js-install> directory and run the following command:
For Oracle, Microsoft SQL Server, DB2, and PostgreSQL databases, refer to your product documentation for details.
Windows: mysqldump --user=root --password=<password> jasperserver > js-db-dump.sql
js-db-dump.sql
If you installed JasperReports Server from the installer, you may specify --user=jasperdb in this
command. If you receive an error about packet size, see section A.2.6, Maximum Packet Size in
MySQL, on page 120.
106
13.2 Stopping Your Application Server
You can now stop your application server. You should leave your database running.
13.3 Running the Repository Export Utility
The repository export utility writes out all of the JasperReports Server repository objects to a set of XML and binary format
files. The output of the export operation is known as an export catalog.
To create the export catalog, go to the <js-install>/scripts directory and run the following commands. Note that there are two
dashes (--) in front of the command options:
For information on running the export utility, refer to Chapter 14, Configuring the Import-Export Utilities, on page 111.
13.4 Specifying Encryption Settings in the JasperReports Server WAR
JasperReports Server uses the Spring configuration and security to enable and configure encryption. These options can allow
you to have a strong encryption setup. This section is focused on the minimal configuration necessary for enabling encryption.
For more specific information in the JasperReports Server Administrator Guide about the security algorithms and settings.
1. Open the following file for editing:
<tomcat>/jasperserver-pro/WEB-INF/ApplicationContext-security.xml
2. In the definition of the daoAuthenticationProvider bean, there is a commented-out reference to the
passwordEncoder bean. Look for the section of the XML file that starts with:
<bean id="daoAuthenticationProvider"
In this bean definition, uncomment the reference to passwordEncoder. This causes the passwordEncoder logic to be used.
After removing the commenting characters the line should look like the following:
<property name="passwordEncoder"><ref local="passwordEncoder"/></property>
3. Enable encryption in the passwordEncoder bean by modifying the allowEncoding property. Change the value from
false to true so that it looks like the following:
<property name="allowEncoding"><value>true</value></property>
4. If the default DESede algorithm is used, the secretKey represents the salt key and must be 24 characters. By default, the
keyInPlainText property is true, meaning the key can be in plain text to make it easier to enter, for example:
<property name="keyInPlainText"><value>true</value></property>
<property name="secretKey"><value>jaspersoftInSanFrancisco</value></property>
5. The last two properties may be left unchanged. They are set to DESede by default. The default values are the following:
<property name="secretKeyAlgorithm"><value>DESede</value></property>
<property name="cipherTransformation"><value>DESede/CBC/PKCS5Padding</value></property>
6. Save and close the file. Encryption is now enabled for the JasperReports Server application upon the next restart.
Windows: js-export.bat --everything --output-dir js-backup-catalog
Linux: js-export.sh --everything --output-dir js-backup-catalog
The text jaspersoftInSanFrancisco is 24 characters long, therefore the two properties above work with
their default values. However, for better security, we recommend that they be changed.
As described in the JasperReports Server Administrator Guide, the secretKey, secretKeyAlgorithm, and
cipherTransformation property settings must be consistent with each other. For example, different
algorithms expect different key lengths.
107
13.4.1 Specifying Encryption Settings - Reference Table
The information in the table below is a summary of the options described in the section above.
The following table describes the available password encryption configuration options:
The secretKey, secretKeyAlgorithm, and cipherTransformation must be consistent with each other. For example, if the
secretKeyAlgorithm is DESede, the secretKey must be 24 bytes long. For more information about secretKey,
secretKeyAlgorithm, and cipherTransformation, see Suns javax.crypto documentation.
13.5 Specifying Encryption Settings for the Import Utility
Before starting JasperReports Server, you must convert the plain text passwords that are currently stored in the repository
export catalog that you created in section 13.1, Backing Up Your JasperReports Server Database, on page 105. These
plain-text passwords need to be converted to cipher text and reloaded into the database in order to successfully login after the
server restarts. To do this, you must add the same encryption settings to the configuration file that is used by the import and
export utilities.
1. Open the following configuration file for editing:
<js-install>/buildomatic/conf_source/iePro/applicationContext-security.xml
2. This file contains the passwordEncoder bean definition, the same as in the JasperReports Server WAR, only by itself.
Perform the same modifications to this file as in the procedure in section 13.4, Specifying Encryption Settings in the
JasperReports Server WAR, on page 106.
Configuration File
\WEB-INF\applicationContext-security.xml
Property Bean Description
passwordEncoder daoAuthentication
Provider
Comment this property out to disable the encryption of
passwords.
allowEncoding passwordEncoder Determines whether JasperReports Server should
encrypt the passwords it writes to the database. Set it to
TRUE to use encrypted passwords
secretKey passwordEncoder The salt key to use as a pass phrase when encrypting
passwords. This string is used to encrypt passwords.
This value can be a simple string or a numeric
representation that can be parsed by Integer.decode().
For example:
String:
This is my secret key
Numeric representation:
0xC8 0x43 0x29 0x49 0xAE 0x25 0x2F 0xA1 0xC1
keyInPlainText passwordEncoder Determines whether the secret key is a simple string or a
numeric representation. Set this parameter to TRUE if
the secretKey is a string; set it to FALSE if the key is a
numeric representation.
secretKeyAlgorithm passwordEncoder The name of the algorithm to use, such as DESede.
cipherTransformation passwordEncoder The name of the transformation, such as DES/CBC/
PKCS5Padding.
108
13.6 Recreating the JasperReports Server Database
Next, drop your existing jasperserver database and recreate an empty jasperserver database.
13.6.1 Dropping and Recreating in MySQL
1. Change directory to <js-install>/buildomatic/install_resources/sql/mysql.
2. Log into your MySQL client:
mysql -u root -p
3. Drop the jasperserver database, create a new one, and load the jasperserver schema:
13.6.2 Dropping and Recreating in Oracle
1. Change directory to <js-install>/buildomatic/install_resources/sql/oracle.
2. Log into your SQLPlus client:
sqlplus jasperadmin/password@MY_SID
13.6.3 Dropping and Recreating in Microsoft SQL Server
1. Change directory to <js-install>/buildomatic/install_resources/sql/sqlserver.
13.6.4 Dropping and Recreating in PostgreSQL
1. Change directory to <js-install>/buildomatic/install_resources/sql/postgresql.
2. Start psql using an administrator account such as postgres:
psql -U postgres
mysql>drop database jasperserver;
mysql>create database jasperserver character set utf8;
mysql>use jasperserver;
mysql>source js-pro-create.ddl;
mysql>source quartz.ddl;
SQL> drop tablespace jasperserver including contents and datafiles;
SQL> create tablespace jasperserver datafile 'jasperserver.dbf' size 100m reuse \
autoextend on next 50m maxsize 1000m extent management local autoallocate \
segment space management auto;
SQL> connect jasperadmin/password@MY_SID
SQL> @js-pro-create.ddl
SQL> @quartz.ddl
sqlcmd -S localhost\jasperserver -Q "DROP DATABASE jasperserver"
sqlcmd -S localhost\jasperserver -Q "CREATE DATABASE jasperserver"
sqlcmd -S localhost\jasperserver -d jasperserver -i js-pro-create.ddl
sqlcmd -S localhost\jasperserver -d jasperserver -i quartz.ddl
109
13.7 Importing Your Repository Data
The import utility reloads all of your repository data. As the data is being saved to the repository, the password fields that were
plain text are encrypted using the encryption settings you made in the sections above.
To import your backup catalog to the repository:
1. Change directory to <js-install>/buildomatic.
2. Run the import utility with the command for your platform. Note that there are two dashes (--) in front of the command
options.:
For information on running the import utility, see Chapter 14, Configuring the Import-Export Utilities, on page 111.
13.8 Starting the Application Server
You can now start your application server. Your database should already be running.
You can now log into JasperReports Server.
Enter your user ID and password in the same manner as you did before encryption was turned on. You can check the contents
of the JIUser table in the jasperserver database and examine the password column to see that the password is no longer
stored in plain text.
drop database jasperserver;
create database jasperserver encoding='utf8';
\c jasperserver
\i js-pro-create.ddl
\i quartz.ddl
Windows: js-import.bat --input-dir js-backup-catalog
Linux: js-import.sh --input-dir js-backup-catalog
110
Configuring the Import-Export Utilities
111
CHAPTER 14 CONFIGURING THE IMPORT-EXPORT UTILITIES
The import and export utilities let you add resources to or extract resources from the JasperReports Server repository.
Typically, users export data from their previous instance and import it into their new installation when upgrading
JasperReports Server. The import utility is also used at installation time in order to load the sample data into the repository.
Please refer to the JasperReports Server Administrator Guide for more information on command options for the import and
export utilities.
Introduction
Import-Export Configuration Files
Changing Your Configuration Settings
Deploying a Database Driver
Running Import or Export
Configuring the Import-Export Utility for JasperServer 3.7
14.1 Introduction
The import-export functionality can be run using the auto-configured buildomatic Ant scripts or it can be run using the shell
based js-import.sh/bat and js-export.sh/bat scripts.
The different command styles would look like the following:
These two ways of running import-export commands are being merged so that all database configuration work will be done
automatically by the buildomatic/default_master.properties. However, as of JasperReport Server version 4.0, this merging
work is not complete. This means that if you are running the js-import.sh/bat or js-export.sh/bat shell scripts, you might have
to do manual configuration depending on the database used.
In particular, the JDBC drivers will not be in place for non-MySQL databases.
Example Command Description
cd <js-install>/buildomatic Change to buildomatic folder
[buildomatic] js-ant export-everything -DexportFile=js-catalog-exp.zip Export using buildomatic Ant script
[shell script] js-export.sh --everything --output-file=js-catalog-exp.zip Export using shell script
112
And you will need to make sure that there is a buildomatic/default_master.properties file in place before you run the js-export
and js-import scripts.
The following sub-sections describe how to configure import-export if you are running from the shell scripts for different
database types.
14.2 Import-Export Configuration Files
In the buildomatic folder, you will find the following files that make up the main parts of the import-export utility. These are
the files to use or to modify to make configuration changes.
14.3 Changing Your Configuration Settings
If you are running the js-import.bat/.sh or js-import.bat/.sh shell scripts, then this section applies.
When you install JasperReports Server from the installer binary, the import and export shell scripts are automatically
configured. However, if you are doing a manual installation from the WAR file distribution you must modify the following
configuration file to include your database settings.
14.3.1 First Create a default_master.properties File
If you dont have a <js-install>/buildomatic/default_master.properites file in place then you should create one. For instance,
copy and rename buildomatic/sample_conf/mysql_master.properties to buildomatic/default_master.properties. Then edit
default_master.properties for you local settings. For more information see section 5.6.1, Creating your Default Master
Properties File, on page 32.
Do the following:
Edit: <js-install>/buildomatic/default_master.properties.
Run: js-ant gen-config.
In Release 4.0, the js-import.sh/bat and js-export.sh/bat shell scripts have been moved to the <js-install>/buildomatic
folder. (The old location was <js-install>/scripts.)
File or Location Purpose
<js-install>/buildomatic/js-import.bat and .sh Import scripts for Windows and Linux, respectively
<js-install>/buildomatic/js-export.bat and .sh Export scripts for Windows and Linux, respectively
<js-install>/buildomatic/default_master.properties File that you must edit (already in place if you installed from
the binary installer)
<js-install>/buildomatic/build_conf/default/
js.jdbc.properties
Database and hibernate dialect settings file (put in place
after you run js-ant gen-config)
<js-install>/buildomatic/conf_source/iePro/
log4j.properties
log4j.properties file controls output logging levels
<js-install>/buildomatic/conf_source/iePro/
applicationContext-*.xml
Spring configuration files
<js-install>/buildomatic/conf_source/iePro/lib All of the JasperReports Server jar files and the JDBC driver
location
113
14.3.2 Here are the Configuration Locations
<js-install>/buildomatic/build_conf/default:
<js-install>/buildomatic/build_conf/default/js.jdbc.properties
<js-install>/buildomatic/build_conf/default/js.quartz.properties (only for DB2 and PostgreSQL)
<js-install>/buildomatic/conf_source/iePro/lib:
<js-install>buildomatic/conf_source/iePro/lib (copy your DB type JDBC driver to this folder)
14.3.3 Check your js.jdbc.properties
The following tables give sample settings for each database.
This file will be automatically configured by buildomatic. You can double-check the file by looking here:
<js-install>/buildomatic/build-conf/default/js.jdbc.properties
You may specify an encrypted password instead of the clear-text password by default.
If your repository contains international characters, you may need to perform additional configuration for the import and
export utilities. See section A.10, Exporting a Repository That Contains UTF-8, on page 122.
Table 14-1 JDBC Settings in the js.jdbc.properties File
MySQL metadata.hibernate.dialect=org.hibernate.dialect.MySQLDialect
metadata.jdbc.driverClassName=com.mysql.jdbc.Driver
metadata.jdbc.url=jdbc:mysql://localhost:3306/
jasperserver?useUnicode=true&characterEncoding=UTF-8
metadata.jdbc.username=root
metadata.jdbc.password=password or
metadata.jdbc.encryptedPassword=encrypted-password
Oracle metadata.hibernate.dialect=
com.jaspersoft.ji.hibernate.dialect.OracleUnicodeDialect
metadata.jdbc.driverClassName=oracle.jdbc.OracleDriver
metadata.jdbc.url=jdbc:oracle:thin:@localhost:1521:orcl
metadata.jdbc.username=jasperadmin
DB2 metadata.hibernate.default_schema=JSPRSRVR
metadata.hibernate.dialect=org.hibernate.dialect.DB2SQLDialect
metadata.jdbc.driverClassName=com.ibm.db2.jcc.DB2Driver
metadata.jdbc.url=jdbc:db2://localhost:50000/jsprsrvr:driverType=4;
fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;
progressiveStreaming=2;progresssiveLocators=2;currentSchema=JSPRSRVR;
metadata.jdbc.username=db2admin
metadata.jndi=jdbc/jasperserver
metadata.upperCaseNames=true
114
14.3.4 If DB2 or PostgreSQL Check your js.quartz.properties
This file will be automatically configured by buildomatic. You can double-check the file by looking here:
14.4 Deploying a Database Driver
In order for the import-export shell scripts to run, they will need the proper JDBC driver. This allows a connection to be made
to the JasperReports Server repository database.
Put the appropriate JDBC driver JAR into the following directory:
<js-install>/buildomatic/conf_source/iePro/lib
All Jaspersoft distributed JDBC drivers can be found at this location:
<js-install>/buildomatic/conf_source/db/<db-type>/jdbc
14.5 Running Import or Export
To see that the import and export shell scripts are properly configured, you can run the scripts using the --help option (with
two dashes --) that displays the command options.
SQL Server metadata.hibernate.dialect=org.hibernate.dialect.SQLServerDialect
metadata.jdbc.driverClassName=
com.microsoft.sqlserver.jdbc.SQLServerDriver
metadata.jdbc.url= jdbc:sqlserver://localhost:1433;
databaseName=jasperserver;SelectMethod=cursor
metadata.jdbc.username=sa
metadata.jdbc.password=sa or
metadata.jdbc.encryptedPassword=encrypted-sa
PostgreSQL metadata.hibernate.dialect=
com.jaspersoft.hibernate.dialect.PostgresqlNoBlobDialect
metadata.jdbc.driverClassName=org.postgresql.Driver
metadata.jdbc.url=jdbc:postgresql://localhost:5432/jasperserver
metadata.jdbc.username=postgres
metadata.jdbc.password=postgres or
metadata.jdbc.encryptedPassword=encrypted-postgres
Table 14-2 Quartz Settings in the js.quartz.properties File
DB2 quartz.delegateClass=org.quartz.impl.jdbcjobstore.DB2v8Delegate
quartz.tablePrefix=JSPRSRVR.QRTZ_
PostgreSQL quartz.delegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
quartz.tablePrefix=QRTZ_
Table 14-1 JDBC Settings in the js.jdbc.properties File, continued
115
On Windows and Linux, run these commands:
If your repository contains international characters, you may need to perform additional configuration for the import and
export utilities. See section A.10, Exporting a Repository That Contains UTF-8, on page 122.
For complete information on the standard import-export options refer to the JasperReports Server Administrator Guide.
14.5.1 Import-Export Updates for 4.0
As of JasperReports Server 4.0, there is a new option for import and export. This option is --include-access-events.
Specifying this option will allow the import or export of access event records stored in the JasperServer repository database.
14.6 Configuring the Import-Export Utility for JasperServer 3.7
You may need to configure your 3.7 import-export utility as part of the upgrade to 4.1 process.
In 3.7, the import-export shell scripts and configurations are located in the <js-install-3.7>/scripts folder.
There are two sub-folders that hold the configuration property files and the required jar files:
<js-install-3.7>/scripts/config
<js-install-3.7>/scripts/lib
To configure import-export for your database type and/or to handle database password changes you have made in your system,
you would update the following files in the same manner as is described in the sections above:
<js-install-3.7>/scripts/config/js.jdbc.properties
Additionally, you will need to copy the appropriate JDBC driver to the following folder (using the same copy information
found in sections above):
<js-install-3.7>/scripts/lib
Windows: js-import.bat --help
js-export.bat --help
Linux: js-import.sh --help
js-export.sh --help
116
Troubleshooting
117
APPENDIX A TROUBLESHOOTING
This appendix contains the following sections:
Installer Freezes
Database Connectivity Errors
License Not Found Error
License Not Found Error with Tomcat as a Service
Error Running a Report
Database Error after Changing MySQL Port Number
Case Sensitivity for Table and Column Names
Java Out of Memory Error
Error Running Scheduled Report
Exporting a Repository That Contains UTF-8
Importing Scheduled Jobs with Update Option
JBoss Modifications
WebSphere: Page Not Found Error on Login
PostgreSQL: Job Scheduling Error
Error Running Buildomatic Scripts
Troubleshooting on Solaris
Disabling User Session Persistence in Application Servers
Linux Installer Issue with Unknown Host Error
Oracle auto-install Script Hangs with Oracle 10g
Problem Starting JasperReports Server on the Mac
A.1 Installer Freezes
If you run the JasperReports Server installer on any platform and the installer freezes, it is helpful to look at the log file created
by the installer. This log file records the status and completion of installer operations. If your installer has had an explicit error,
there may be a specific error message in the log. At a minimum, the log file should help narrow where the error has occurred
even if there is not a specific error message.
118
You can find the installer log in the following locations:
If you have tried multiple installs, make sure you view the most recent install log file.
A.2 Database Connectivity Errors
The most common problems encountered with a new JasperReports Server instance are database configuration problems. This
section contains information that may help resolve such issues.
A.2.1 Testing the Database Connection
The simplest database configuration problem is an incorrect user name or password. If you encounter database problems upon
startup or login, check the user name and password by logging directly into your RDBMS as described in the following
sections.
You can connect to your database using the database configuration settings that are found in JasperReports Server. This
validates the database hostname, port, username, and password that are being used.
If you are having trouble logging into JasperReports Server on the login page, you can check the users and passwords that exist
by viewing the contents of the jasperserver.JIUser table.
A.2.1.1 Logging into MySQL
Start MySQL from the command line and try to log in directly using the jasperdb user, for example:
<mysql>/bin/mysql -u jasperdb -p or
<mysql>/bin/mysql -u root -p
You are prompted for a password for the user you specified on the command line. Enter the appropriate password to login. The
default password used in the sample configuration scripts is password (jasperadmin in 2.1 and earlier).
A.2.1.2 Logging into Oracle
Start SQL*Plus and try to log into Oracle directly. Three users are created during installation:
jasperserver - schema user for the JasperReports Server metadata.
sugarcrm - schema user for the SugarCRM sample data.
foodmart - schema user for the foodmart sample data.
To log in as each of these users, supply the password specified during installation.
A.2.1.3 Logging into Microsoft SQL Server
Run the sqlcmd and try to log into MSSQL Server directly. For example:
sqlcmd -S localhost\jasperserver -d jasperserver -U jasperadmin -P password
A.2.2 Configuration File Locations
JasperReports Server configuration properties are found in the following files, according to your application server.
Windows: <js-install>/installation.log
Linux: <js-install>/installation.log
Mac <js-install>/installation.log
Troubleshooting
119
The following list shows the location of the properties for supported application servers:
A.2.3 Context.xml under Tomcat: Special Case
If you do multiple deploys of JasperServer to Tomcat, the context.xml (database connection configuration) can be superseded
by a file in this location: <tomcat>/conf/Catalina/localhost/jasperserver-pro.xml file.
When JasperServer is deployed, the context.xml will be copied to <tomcat>/conf/Catalina/localhost/jasperserver-pro.xml
(Tomcat does this by default).
Now, if you make changes to your <tomcat>/webapps/jasperserver-pro/META-INF/context.xml, Tomcat will not see them.
Instead, the jasperserver-pro.xml will be used. This is confusing, but is the way that Tomcat operates.
If you edit your context.xml to fix a database problem:
<tomcat>/webapps/jasperserver-pro/META-INF/context.xml
Make sure and delete the jasperserver-pro.xml file:
<tomcat>/conf/Catalina/localhost/jasperserver-pro.xml (delete this file)
A.2.4 Connect to Installed/Bundled Version of MySQL
These steps are for connecting under Linux.
If you have installed JasperReports Server using the bundled version of MySQL, you may want to connect to MySQL with the
mysql command line application to examine the database. In order to connect, you will need to specify the socket that MySQL
is using, as specified in the file <install-dir>/jasperctl.sh.
1. Get the socket file location by using the Linux ps (process status) command:
ps -ef | grep mysql
2. This displays lots of information. Look for the --socket value, for example:
... /home/devuser/jasperreports-server-4.0/mysql/bin/mysqld_safe --port=3306 \
--socket=/home/devuser/jasperreports-server-4.0/mysql/tmp/mysql.sock ...
3. Then run a command similar to the following:
/home/devuser/jasperreports-server-4.0/mysql/bin/mysql -u jasperdb -p \
--socket=/home/devuser/jasperreports-server-4.0/mysql/tmp/mysql.sock
A.2.5 Case Sensitive Collation in SQL Server
In Microsoft SQL Server, setting the collation to be case-sensitive is not supported. When collation is case-sensitive in SQL
Server, column and table names are also treated as case-sensitive. This can happen when setting a locale that includes
case-sensitive collation and will cause an error:
Tomcat: <tomcat>/webapps/jasperserver-pro/META-INF/context.xml
<tomcat>/webapps/jasperserver-pro/WEB-INF/hibernate.properties
<tomcat>/apache-tomcat/webapps/jasperserver-pro/WEB-INF/web.xml (JNDI config)
<tomcat>/apache-tomcat/config/Catalina/localhost/jasperserver-pro.xml (delete: see below)
JBoss: <jboss>/server/default/deploy/js-mysql-ds.xml or js-oracle-ds.xml
<jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/hibernate.properties
<jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/web.xml
<jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/jboss-web.xml
GlassFish: <glassfish>/domains/domain1/autodeploy/jasperserver-pro.war/WEB-INF/hibernate.properties
<glassfish>/domains/domain1/autodeploy/jasperserver-pro.war/WEB-INF/js.quartz.properties
<glassfish>/domains/domain1/config/domain.xml
120
Use a different locale or remove the case-sensitivity setting.
A.2.6 Maximum Packet Size in MySQL
If you are upgrading or importing into a MySQL database and your repository contains large objects such as images, you may
see an error such as:
ERROR 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes
The default max_allowed_packet on the MySQL server is 1M (one Megabyte = 1,048,576 bytes). The most effective fix is to
change this value in the server configuration to accommodate the largest resource stored in your repository. The server
configuration file is typically named my.ini and is located in the MySQL root directory, although this may vary. Change the
configuration setting to a larger value, for example:
max_allowed_packet = 4M
For more information, see http://dev.mysql.com/doc/refman/5.0/en/packet-too-large.html.
After changing this value, restart the MySQL server. Then perform the upgrade or import step again.
A.3 License Not Found Error
Normally, the JasperReports Server installer includes an evaluation license file that you replace with a commercial license file,
as described in section 2.2.3, Installing a New License File, on page 21. If JasperReports Server returns an error after you
replace the license file, make sure you did the following:
Cleared your application servers work directory, as explained in section 2.2.3.
Set the Djs.license.directory property in your application server startup environment properly:
-Djs.license.directory="<js-install>"
For example, in Linux the command might be:
-Djs.license.directory="/opt/jasperserver-pro-4.1
The specified directory must contain the license file, which should be named jasperserver.license. The property is
typically set for your application server in the environment startup script. It must give the location of your license file,
which is typically in the <js-install> directory:
For additional information about licenses, see section 5.8, Setting Up the JasperReports Server License, on page 35.
A.4 License Not Found Error with Tomcat as a Service
If you have an existing Tomcat running as a service under Windows, the installer attempts to make the proper updates so that
the JasperReports Server license file is found at application server startup time. If the installer is unsuccessful, be sure that you
took the steps described in section 2.2.4, License File for Existing Tomcat as Windows Service, on page 22.
[sql] Failed to execute:
INSERT INTO JIUserRole (userId,roleId) select u.id, r.id
from JIUser u, JIRole r
where u.username = \'anonymousUser\' and r.roleName = \'ROLE_ANONYMOUS\'
[sql] com.microsoft.sqlserver.jdbc.SQLServerException: Invalid column name \'roleName\'
Tomcat: <tomcat>/bin/setclasspath.bat/.sh or bin/setenv.bat/.sh
JBoss: <jboss>/bin/run.bat or .sh
Troubleshooting
121
A.5 Error Running a Report
If you can log into JasperReports Server but encounter an error when running a report within it, you can browse the repository
to identify and resolve the problem.
One common problem with an individual report is the data source being used. To validate a data source connection:
1. Log into JasperReports Server as a user with administrative permissions and locate the report unit that returns errors.
2. Select the report and click the Edit button in the toolbar to identify the data source the report uses. The data source name
is found on the fourth edit page.
3. Select this data source in the repository and click the Edit button in the toolbar.
4. Review the information specified for this data source.
5. Click the Test Connection button in order to validate the connection.
6. Click Save or Cancel when you are done.
7. Test your report. If it still returns errors, edit the data source again and try checking other values, such as the port used by
the database.
A.6 Database Error after Changing MySQL Port Number
The default port for MySQL is 3306. If you entered a different port when you installed MySQL, the JasperReports Server
installer configures them to communicate properly. If the MySQL port number has changed, or if you encounter a problem,
check the database configuration files to verify your port number.
If it is incorrect, change it to the correct port number, save the file, and restart the application server. For more information, see
section A.2.2, Configuration File Locations, on page 118.
A.7 Case Sensitivity for Table and Column Names
Some databases are case-sensitive with respect to table names and will consider customer and Customer to be two
different tables. If JasperReports Server is using a case-sensitive database, its important that the table names specified in
query strings in the JRXML file of a saved report match the actual table names found in the database. A mismatch may occur
if you are transferring data from one database to another, which may cause the capitalization of table names to change.
Under Windows MySQL, table and column names are not case-sensitive.
Under Linux MySQL, table and column names are case-sensitive. Linux MySQL can be configured to be non-case-sensitive
by setting the configuration parameter lower_case_table_names to 1 in the my.ini or my.cnf file. For more information
search the MySQL documentation for a section about identifier case sensitivity.
Table and column names in Oracle and PostgreSQL are case-sensitive.
A.8 Java Out of Memory Error
If you encounter a Java out of memory error, it is suggested that you increase your Java heap size setting. See section 5.9,
Setting Java JVM Options, on page 35. It is recommended that you add -Xms128m -Xmx512m to your JAVA_OPTS
setting, but you may increase that to -Xms512m -Xmx1024m or larger if your server can support higher settings.
This Java option is set within the application server, so you must set it then restart your application server.
122
A.9 Error Running Scheduled Report
If you setup a scheduled report, chose to run it, and chose to save it as HTML or RTF, the report size can potentially get quite
large. If you are running MySQL and you get the following error:
JDBC exception on Hibernate data access
org.hibernate.exception.GenericJDBCException: could not insert
the problem may be the default size of the MySQL blob datatype. You can increase the size of this datatype by updating
your my.ini or my.cnf MySQL configuration file with the following setting:
max_allowed_packet=32M
A.10 Exporting a Repository That Contains UTF-8
The following errors may happen when you have international characters in repository objects, for example, in user IDs.
A.10.1 Error During JasperServer 1.2 Export
Upgrading typically requires doing an export operation on your database. If you get a null pointer exception such as the
following:
java.lang.NullPointerException
ResourceExporter.exportResource(ResourceExporter.java:258)
it may be due to an incorrect character in the file scripts/ji-export-util/jdbc.properties. Check the URL in this file; it should
look like the following:
Note the ampersand & character. It is incorrect if it appears as &. The & is only correct in an HTML or XML context.
It is incorrect in a properties file.
A.10.2 Error During Export from Repository on Oracle
Oracle requires a specific JVM property to handle UTF-8 characters properly. When this error happens, the export is empty
and an error occurs when attempting to compress the result:
ERROR ExporterImpl:129 - java.util.zip.ZipException: ZIP file must have at least one entry
If you have stored you repository database on an Oracle RDBMS, modify the last line of both <js-install>/scripts/js-export.*
files as follows:
From: java -classpath ...
To: java -Doracle.jdbc.defaultNChar=true -classpath ...
A.11 Importing Scheduled Jobs with Update Option
There is a JasperReports Server bug where if you import a set of resources that contain Report Jobs these jobs will not be
loaded into the JasperReports Server repository if you are using the --update option of the import tool.
To workaround this problem, you should make sure to not specify the --update option on your
js-import.bat/.sh command line.
Troubleshooting
123
A.12 JBoss Modifications
A.12.1 JBoss 4.2 XML/A Connection Fix
JBoss 4.2 includes the JBossWS service as a standard, default feature. JasperReports Server has web services support for
XML/A connections.
The web services classes in JasperReports Server and JBoss can conflict and cause the following error when attempting to
utilize a JasperReports Server XML/A connection:
javax.xml.soap.SOAPException: Unable to create message factory for
SOAP: org.jboss.ws.core.soap.MessageFactoryImpl
To prevent the web services class conflict, set the special Java JVM options for JBoss 4.2, as described in section 6.1, Setting
JVM Options for Application Servers, on page 43.
A.12.2 JBoss Large INFO Log Message on Analysis Drill-through
JBoss has an internal mechanism to track and log information on unclosed JDBC connections. JasperServer Analysis leaves a
connection open for performance reasons when doing an analysis drill-through. In this case, JBoss puts a large INFO level
message into the server.log. To silence this INFO message
1. Open the JBoss log4j configuration file for editing:
<jboss>/server/default/conf/jboss-log4j.xml
2. Set the logging level for the CachedConnectionManager class to the following value:
A.12.3 JBoss 4.0 Log4j Error on Startup
An error occasionally seen in JBoss 4.0 (tested on 4.0.5) has the following exception message:
log4j:ERROR "org.jboss.logging.util.OnlyOnceErrorHandler
JBoss is normally distributed with the log4j facility enabled. Log4j is initialized at JBoss startup. JasperReports Server also
includes and uses log4j. When JBoss loads the JasperReports Server WAR file, the OnlyOnceErrorHandler exception can
occur. This error is not fatal, but it can cause confusion when seen in the JBoss server log.
To remove this error, you can delete the JasperReports Server version of the log4j.jar file:
<jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/lib/log4j-1.2.12
A.12.4 JBoss 5.0.1 and 5.1.x Error
With JBoss 5.0.1 and 5.1.x, you may see the following error:
org.jboss.xb.binding.JBossXBRuntimeException: Failed to create a new SAX parser
Caused by: java.lang.ClassCastException
This is a class conflict with the xercesImpl-2.7.1.jar in JasperReports Server. To correct it, delete the following file:
<jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/lib/xercesImpl-*.jar
<category name="org.jboss.resource.connectionmanager.CachedConnectionManager">
<priority value="WARN"/>
</category>
When running the buildomatic scripts to deploy to JBoss, the xercesImpl-3.7.jar file is automatically deleted in order to
fix this problem.
124
A.13 WebSphere: Page Not Found Error on Login
This error is seen during a WebSphere installation when the user attempts to log into JasperReports Server. After typing in a
correct user ID and password, the user sees an error page: Page cannot be found, HTTP 404
Some WebSphere versions or fix packs have modified code that processes web server filters incorrectly. Components with the
/* url pattern get affected by this. JasperReports Server uses the Acegi framework for authentication and it is mapped using a
filter chain with the /* url pattern.
WebSphere provides a special property to solve this problem:
1. Login into WebSphere Administrative Console.
2. Navigate to Application Servers > <server> > Web Container Settings > Web Container > Custom Properties
3. Create a new property with the following attributes:
name: com.ibm.ws.webcontainer.invokefilterscompatibility
value: true
4. Save the master configuration.
5. Restart the WebSphere server.
A.14 PostgreSQL: Job Scheduling Error
If the Quartz settings under the PostgreSQL database have not been updated to specify the driver delegate class specific to
PostgreSQL you will get errors when you try and run a scheduled report. The errors would look similar to the following:
If you see this error you will need to check your Quartz properties file found at the following location:
<tomcat>/webapps/jasperserver-pro/WEB-INF/js.quartz.properties
You should make sure that the following property does not have the standard driver delegate, but instead has the PostgreSQL
specific driver delegate. It should look like the following for PostgreSQL:
org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
A.15 Error Running Buildomatic Scripts
The buildomatic scripts depend on both Java and Apache Ant. There are two common configuration errors when attempting to
do an installation using these scripts (if you are not using the included, bundled Apache Ant).
A.15.1 Missing Java JDK
If you have the Java JRE (Java Runtime Environment) instead of the JDK, you will not have the additional utilities that are
required. In particular, an error referring to the tools.jar might occur, as in the following message:
Error while fetching Quartz runtime information
org.quartz.JobPersistenceException: Couldn't obtain triggers: Bad value for type int
org.postgresql.util.PSQLException: Bad value for type int
Troubleshooting
125
The solution is to download and install the Sun Java JDK, labeled as the Java SE Development Kit on the Sun web site.
If you are upgrading JasperReports Server, you can also use the Java 1.5 JDK bundled in the previously installed version, as
described in 9.9.1, Handling JasperReports Server Customizations, on page 87.
A.15.2 Forgot to Copy the File ant-contrib.jar
If you are using your own version of Ant and your Ant instance does not have the ant-contrib.jar in the lib directory, you will
get an error similar to the following:
BUILD FAILED
c:\js-builds\jasperserver\buildomatic\install.xml:6:
Ant failed to create a task or type. To correct the error, copy <js-install>/buildomatic/extra-jars/ant-contrib.jar to your
<apache-ant>/lib directory.
A.15.3 Older Apache Ant Version
As of the release of JasperReports Server 4.0, Apache Ant version 1.8.1 or higher is required. There are improvements to error
handling routines in the buildomatic auto-install scripts which required the higher level of Ant. So, if you are using your
own version of Ant, be sure that it is at this higher level:
ant -version
A.16 Troubleshooting on Solaris
When running the bundled Apache Ant scrips on the Solaris platform, you may see the following error:
ANT_HOME=../apache-ant: is not an identifier
The bundled Ant scripts are intended for the bash shell and may cause this error when run in the Bourne shell (sh). To avoid
the error, run all js-ant targets in the bash shell explicitly, for example:
bash js-ant create-js-db
A.17 Disabling User Session Persistence in Application Servers
JasperReports Server stores non-serializable data in its user sessions, which can cause errors after restarting your application
server:
Exception loading sessions from persistent storage
Cause: java.io.NotSerializableException ...
The errors appear in the JasperReports Server log when users log in after the application server has been restarted. The errors
do not appear to users, and they have no impact on JasperReports Server operations.
[exec] [ERROR] BUILD FAILURE
[exec] [INFO] ----------------------------------------------------
[exec] [INFO] Compilation failure
[exec] Unable to locate the Javac Compiler in:
[exec] c:\Program Files\Java\jdk1.6.0_10\jre\..\lib\tools.jar
[exec] Please ensure you are using JDK 1.5 or above and
[exec] not a JRE (the com.sun.tools.javac.Main class is required).
[exec] In most cases you can change the location of your Java
[exec] installation by setting the JAVA_HOME environment variable.
126
Because JasperReports Server user sessions are not persistent, you can configure your application server to disable persistence
and avoid the error. For example, in Apache-Tomcat 5.5 and 6.0, edit the file <tomcat>/conf/context.xml and locate the
following lines:
Remove the comment markers from lines 2 and 4 above, then restart Apache-Tomcat for the change to take effect. For other
application servers, refer to the product documentation.
A.18 Linux Installer Issue with Unknown Host Error
If a Linux server does not have proper hostname entries in the /etc/hosts file, it is possible to get installer errors.
The installer carries out an import operation in order to load the core, minimal data into the repository database. This import
operation can fail if the host is not configured.
If the import operation fails during installation, the installation will also fail. However, there should be an installation.log in
the root of the installation folder to help debug the problem. The installation.log is located here:
<js-install>/installation.log
If you look inside of this log, or look at the error messages displayed on the console, and if you see errors such as the ones
listed below, you might have the issue where the hosts file is not properly configured. Here are some errors you might see:
In this case, you should fix the hosts issue and reinstall JasperReports Server.
The /etc/hosts file should normally have entries that look similar to the following:
127.0.0.1 localhost.localdomain localhost
172.17.5.0 myserver.mydomain.com myserver
A.19 Oracle auto-install Script Hangs with Oracle 10g
If you plan to run the auto-install script when installing to an Oracle database instance, you should check for the appropriate
JDBC driver version. The default JDBC driver used for Oracle tends to be specific for newer Oracle versions. If you are
installing to an older version of Oracle then the newer JDBC driver can cause execution to hang.
The default JDBC driver for Oracle can be seen in your buildomatic/default_master.properties file:
<js-install>/buildomatic/default_master.properites (final file name and location)
<js-install>/buildomatic/sample_conf/oracle_master.properties (original file)
these are the settings:
# maven.jdbc.artifactId=ojdbc5
# maven.jdbc.version=11.2.0
The settings above are commented out. Nevertheless, this is the JDBC driver that is used by default. These settings are
appropriate for an Oracle version 11.2 instance.


Caused by: java.net.NoRouteToHostException: No route to host
com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure
ERROR Cache:145 - Unable to set localhost. This prevents creation of a GUID
java.net.UnknownHostException
org.quartz.SchedulerException: Couldn't get host name!
Troubleshooting
127
If you are using Oracle 10.2, you should un-commentout these settings and change them to the following:
The location of the Oracle JDBC drivers is here:
<js-install>/buildomatic/conf_source/db/oracle/jdbc
A.20 Problem Starting JasperReports Server on the Mac
Jaspersoft has seen some issues where the Tomcat included with the JasperReports Server is not shutdown properly. This
could be related to the machine being shutdown while Tomcat is running.
When the Tomcat scripts start Tomcat, they write a "pid" (Process ID) file to the Tomcat folder. Tomcat uses this to determine
whether the Tomcat instance is already running. When Tomcat is shutdown, this pid file is removed.
However, if the pid file is not removed on shutdown, Tomcat will fail to start up.
You may see this when you double-click the jasperServerStart.app startup. It will seem like JasperReports Server is starting up
but it never actually starts up.
In order to recover from this issue, you will need to manually delete the pid file.
Delete catalina.pid using Finder:
1. Navigate to the <js-install>/tomcat/temp folder.
For instance: /Applications/jasperreports-server-<ver>/tomcat/temp
2. Delete catalina.pid.
Delete the catalina.pid file using Terminal shell:
1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon)
2. Navigate to the <js-install>/tomcat/temp folder.
For instance: /Applications/jasperreports-server-<ver>/tomcat/temp.
3. Enter the following command:
rm catalina.pid
To start and stop the MySQL and Tomcat components separately from the command line shell:
1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon).
2. Navigate to the <js-install> folder.
For instance: /Applications/jasperreports-server-<ver>.
3. To Start:
./ctlscript mysql start
./ctlscript tomcat start
4. To shutdown:
./ctlscript stop
or
./ctlscript tomcat stop
./ctlscript mysql stop
128

Jasper Reports Server Install Guide

Uploaded by

Copyright:

Available Formats

Jasper Reports Server Install Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jasper Reports Server Install Guide

Uploaded by

Copyright:

Available Formats

What are the main components of the JasperReports Server installer distribution?

What are the steps involved in installing JasperReports Server?

JASPERREPORTS SERVER

You might also like