You are on page 1of 47

JasperServer Community Edition

Installation Guide

Version 3.1

http://www.jaspersoft.com/
© 2008 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, JasperAnalysis,
JasperServer, JasperETL, JasperReports, iReport, and Jasper4 products 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.
JasperServer Installation Guide

Table of Contents
1 Introduction .................................................................................................................................6
1.1 About JasperServer .............................................................................................................................. 6
1.2 Conventions .......................................................................................................................................... 6
1.3 JasperServer Distributions.................................................................................................................... 6
1.4 Installer Distribution Support................................................................................................................. 7
1.4.1 Operating Systems Supported................................................................................................. 7
1.4.2 Components Included in the Installer ...................................................................................... 7
1.4.3 Applications Supported by the Installer ................................................................................... 7
1.4.4 Application Versions Supported............................................................................................... 7
1.4.5 Java Version Supported........................................................................................................... 7
1.5 War File Binary Distribution Support..................................................................................................... 8
1.6 Release Notes and Application Support ............................................................................................... 8
1.7 Prerequisites for Installation.................................................................................................................. 8
1.7.1 System Requirements.............................................................................................................. 8
1.8 Support for Internationalization ............................................................................................................. 9

2 Installing JasperServer ............................................................................................................10


2.1 Installation Steps................................................................................................................................. 10
2.1.1 Welcome ................................................................................................................................ 10
2.1.2 Accept License Agreement.................................................................................................... 10
2.1.3 Installation Directory Location................................................................................................ 10
2.1.4 Select Tomcat Configuration ................................................................................................. 10
2.1.5 Select MySQL Configuration ................................................................................................. 11
2.1.6 Install Sample Data................................................................................................................ 11
2.1.7 Install iReport ......................................................................................................................... 12
2.1.8 Ready to Install ...................................................................................................................... 12
2.1.9 Installation Complete Screen................................................................................................. 12
2.1.10 Log Into JasperServer............................................................................................................ 13
2.2 Post-Installation Steps ........................................................................................................................ 13
2.2.1 Updates Made During Installation.......................................................................................... 13
2.2.2 Installer Output Log File......................................................................................................... 13
2.2.3 Check your Java JVM Options .............................................................................................. 14

3 Starting and Stopping JasperServer.......................................................................................15


3.1 Using JasperServer Start/Stop Scripts ............................................................................................... 15
3.2 Using Start/Stop Scripts Without Bundled Installation........................................................................ 15
3.3 Logging into JasperServer .................................................................................................................. 15

2 1208.JSO31.10
JasperServer Installation Guide
3.4 Starting the Included iReport .............................................................................................................. 16
3.5 JasperServer Log Files ....................................................................................................................... 16

4 Uninstalling JasperServer........................................................................................................17

5 Install Using the War File Distribution for Tomcat or JBoss ................................................18
5.1 Introduction ......................................................................................................................................... 18
5.1.1 Applications Supported by the War File Distribution ............................................................. 18
5.1.2 Application Versions Supported............................................................................................. 18
5.2 Obtain the War File Distribution .......................................................................................................... 18
5.3 Unpack the War File Distribution Zip .................................................................................................. 18
5.4 Setup the JasperServer Database...................................................................................................... 18
5.4.1 MySQL Database Setup Steps.............................................................................................. 19
5.5 Deploy JasperServer War to the Application Server .......................................................................... 19
5.6 Prepare for Database Configuration ................................................................................................... 19
5.6.1 Default Database Configuration Values ................................................................................ 19
5.6.2 Expand the Archived War File ............................................................................................... 20
5.7 Configure Hibernate Properties File ................................................................................................... 20
5.8 Deploy JDBC Database Driver ........................................................................................................... 21
5.9 Database Connection Steps for Tomcat............................................................................................. 21
5.9.1 MySQL context.xml for Tomcat.............................................................................................. 21
5.10 Database Connection Steps for JBoss ............................................................................................... 21
5.10.1 MySQL Datasource for JBoss ............................................................................................... 22
5.11 Extra Configuration Step for JBoss..................................................................................................... 22
5.12 Set Java JVM Options ........................................................................................................................ 22
5.12.1 JVM Options for JBoss .......................................................................................................... 23
5.13 Start JasperServer .............................................................................................................................. 23
5.14 Login to JasperServer......................................................................................................................... 23
5.14.1 JasperServer Heartbeat......................................................................................................... 24
5.15 Setup and Load Sample Data............................................................................................................. 24
5.15.1 MySQL Sample Database Create and Populate ................................................................... 24
5.15.2 Check Context.xml or JBoss Datasource for Sample Data Config ....................................... 24
5.16 Import the JasperServer Sample Metadata ........................................................................................ 25
5.16.1 Prepare for Running the Import Utility ................................................................................... 25
5.16.2 Run the Import Utility ............................................................................................................. 25
5.17 Report Scheduling Configuration........................................................................................................ 25
5.17.1 js.quartz.properties ................................................................................................................ 25
5.17.2 js.mail.properties.................................................................................................................... 26
5.17.3 js.schedular.properties........................................................................................................... 26
5.18 Restart JasperServer .......................................................................................................................... 26
5.19 Update XMLA Connection Definitions (Optional) ............................................................................... 26
5.20 Troubleshooting your JasperServer Configuration ............................................................................. 27

3
JasperServer Installation Guide
6 Upgrade from JasperServer 3.0 to JasperServer 3.1 ............................................................28
6.1 Backup JasperServer War File and JasperServer Database............................................................. 28
6.1.1 Stop Your Application Server................................................................................................. 28
6.1.2 Backup the JasperServer War Archive.................................................................................. 28
6.1.3 Backup the JasperServer Database ...................................................................................... 28
6.2 Unpack JasperServer 3.1 War File Distribution.................................................................................. 28
6.3 Upgrade the JasperServer War .......................................................................................................... 29
6.3.1 Deploy the JasperServer WAR file ........................................................................................ 29
6.3.2 Expand the Archived War File ............................................................................................... 29
6.3.3 Check for Local Configurations.............................................................................................. 29
6.4 Upgrade the JasperServer Database ................................................................................................. 29
6.5 Start JasperServer 3.1 ........................................................................................................................ 29
6.6 Login to JasperServer 3.1................................................................................................................... 30
6.7 Sample Data Upgrade (Optional) ....................................................................................................... 30
6.7.1 Upgrade Sample Databases (if necessary)........................................................................... 30
6.7.2 Configure and Run Import of Sample Data ........................................................................... 30
6.8 Additional Notes on JasperServer Upgrade ....................................................................................... 31
6.8.1 Using mysqldump for Database Backup ............................................................................... 31
6.8.2 Additional Configuration Files ................................................................................................ 31
6.8.3 Clear the Tomcat Work Directory .......................................................................................... 31
6.8.4 Clear the Repository Cache Table......................................................................................... 31
6.8.5 Update XMLA Connections (Optional)................................................................................... 32
6.8.6 Upgrade Using Export and Import Operations ...................................................................... 32

7 Upgrade Notes for JasperServer 2.1.......................................................................................33


7.1 Upgrading a MySQL Database from 2.1 to 3.0 .................................................................................. 33
7.2 Upgrading from Earlier Versions......................................................................................................... 33

8 Adding Password Encryption to JasperServer......................................................................34


8.1 Introduction ......................................................................................................................................... 34
8.2 General Notes ..................................................................................................................................... 34
8.3 Backup your JasperServer Database ................................................................................................. 34
8.4 Stop Application Server ...................................................................................................................... 34
8.5 Run Repository Export Utility .............................................................................................................. 34
8.6 Specify Encryption Settings in JasperServer War .............................................................................. 35
8.7 Specify Encryption Settings for Import Utility...................................................................................... 36
8.8 Drop and Recreate the JasperServer Database ................................................................................ 36
8.9 Run Repository Import Utility .............................................................................................................. 36
8.10 Start Application Server ...................................................................................................................... 36
8.11 Login to JasperServer......................................................................................................................... 37

4 1208.JSO31.10
JasperServer Installation Guide
Appendix A: Configuring the Import-Export Utility .....................................................................38

Appendix B: Troubleshooting .......................................................................................................40

Appendix C: Java 1.6 JVM Settings ..............................................................................................46

Appendix D: Configuring and Using Ant ......................................................................................47

5
JasperServer Installation Guide

1 Introduction

1.1 About JasperServer


JasperServer builds on JasperReports as a comprehensive family of Business Intelligence products, providing robust static
and interactive reporting, report scheduling, and data analysis capabilities within an easy to use server environment.

1.2 Conventions
For clarity, this document uses the following conventions when referring to file locations, user names, passwords, and other
values that are specific to your environment:
Convention Meaning
Paths and File <js-install> The root directory where JasperServer will be installed.
Locations
<apache-tomcat> The directory where Tomcat is installed. If you plan to use the
instance of Tomcat that is included in the installer, Tomcat is installed
under the <js-install> directory.
<jboss> The directory where JBoss is installed.
<mysql> The directory where MySQL is installed. If you plan to use the
instance of MySQL that is included in the installer, MySQL is
installed under the <js-install> directory.
<java> The directory where java is installed
Additional <unpacked-war-dir> The directory where user unpacks the WAR file distribution ZIP.
Locations
jasperadmin/ The user name and password of the default JasperServer login
jasperadmin administrative user.
jasperdb/password The user name and password for the default database user.

1.3 JasperServer Distributions


There are two main distribution packages for JasperServer. The first distribution set is the installers for the Windows and
Linux platforms. The second distribution is the War File binary package.
The installers have the capability of installing JasperServer, automatically configuring the JasperServer database, and
optionally installing sample data that highlight JasperServer features.
The WAR file binary distribution contains the JasperServer web archive file as well as database create and load scripts. The
WAR file distribution supports additional applications that are not supported by the installers.
Distribution Package Notes
Installers Runs on Windows and Linux
War File Binary Distribution Zip Used for manual installation

6
JasperServer Installation Guide

1.4 Installer Distribution Support

1.4.1 Operating Systems Supported


The installers support the following operating systems:
Windows Linux
Windows 2003 Red Hat Enterprise Linux
Windows XP SUSE
Windows Vista Ubuntu

1.4.2 Components Included in the Installer


The installer is designed so that it is easy to get JasperServer up and running quickly. The installer comes with bundled
versions of an application server, a database, and a Java runtime. This bundled software can optionally be used if you do
not already have these components on your target computer. If, on the other hand, you have existing components, the
installer can install to these components.
Here are the components included with the installer:
Component Notes
JasperServer Application War file and configuration support scripts
iReport Report Designer iReport Netbeans version (optional)
Java 1.5 Runtime Runs web application container (optional)
MySQL Database Database Server (optional)
Apache Tomcat Web application container (optional)
JasperServer Documentation Found in the <js-install>/docs directory

1.4.3 Applications Supported by the Installer


When you start the JasperServer installer, you are prompted to choose the components to use. 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 bundled Tomcat.
When you run the installer, you can choose between the following configurations:
Application Server Database
Apache Tomcat bundled MySQL bundled
Apache Tomcat bundled MySQL existing
Apache Tomcat existing MySQL bundled
Apache Tomcat existing MySQL existing

1.4.4 Application Versions Supported


For information on the specific versions of third party applications that are supported by the installer refer to the release
notes for the distribution you are using. The Release Notes are found in the root of the installation directory.

1.4.5 Java Version Supported


JasperServer supports both Java 1.5 and Java 1.6. Java versions earlier than Java 1.5 are not supported.
7
JasperServer Installation Guide

1.5 War File Binary Distribution Support


The WAR file distribution is the package you would use to do a manual installation of the JasperServer application.
The WAR file supports many more applications than are supported by the installers.
Contents of the WAR file binary distribution:
Content Item Notes
JasperServer WAR file archive This contains all of the JasperServer class files
and dependent jars.
JasperServer Database Scripts SQL scripts for each supported database.
JasperServer Standard Sample Data Sample data that highlights JasperServer features.
JasperServer Extra Samples Web Service example applications, sample
reports, custom data source examples, and other
sample files.
JasperServer Documentation Guides for end users and administrators.

Note: 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 file set.

1.6 Release Notes and Application Support


Release notes are included with each distribution and with each new update to a distribution.
Not all applications are immediately supported when a new JasperServer 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.

1.7 Prerequisites for Installation


JasperServer relies on third-party products, such as application servers and relational databases. Unless you use the ones
included with the JasperServer installer, these third party products must be installed and configured before beginning a
JasperServer installation. Refer to the sections below that relate to your preferred application server and database.

1.7.1 System Requirements


The requirements in this table are deliberately loosely defined. The table contains recommendations for minimum and
recommended configurations for a full installation, including MySQL and an application server. The values are based on
our own testing. You may find that JasperServer can run on systems with fewer resources or slower systems than stated in
the Recommended Minimum 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 JasperServer.
The values in the table below are guidelines to help with your deployment:
Category Installed Footprint Recommended Recommended
Minimum
Windows
Disk ~600MB 10 GB free 40 GB +

8
JasperServer Installation Guide
RAM 512 MB 1 GB +

CPU (class) 1 GHz (single Pentium) 1.5 GHz + (multi-core


Pentium)

MAC OSX OSX

Disk ~600MB 10 GB free 40 GB +


RAM 512 MB 1 GB +
CPU (class) 1 GHz (single Pentium) 1.5 GHz + (multi-core
Pentium)

Linux
Disk ~600MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class) 1 GHz (single Pentium) 1.5 GHz + (multi-core
Pentium)

Solaris
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class) UltraSparc II

AIX
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class)

HP-UX
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class)

1.8 Support for Internationalization


JasperServer supports the full Unicode character set using UTF-8 encoding. JasperServer also depends on the underlying
database and application server to complete 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 JasperServer
Administrator Guide for instructions on how to configure software to support UTF-8.

9
JasperServer Installation Guide

2 Installing JasperServer
When you run the installation executable, you are prompted to specify information about the third party applications that
JasperServer relies on. These third party applications are Apache Tomcat and the MySQL database.
This section sets forth all the steps you might encounter when installing JasperServer.
Note: When you run the installer against an existing database instance, the database must be running at install time.

2.1 Installation Steps


To begin, run the installer on the application server host.
In Windows, the installer is an executable file that you can double-click to run. For example, double-click the following:
jasperserver-<ver>-windows-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, login with an account that has administrative privileges and open a bash shell. At the
command line, enter the name of the installer file. For example:
./jasperserver-<ver>-linux-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.

2.1.1 Welcome
The first step introduces the installer and allows you to continue or exit. Click Next.

2.1.2 Accept 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.
Command Line Note: 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 Installation Directory Location


You are prompted for the directory where JasperServer is installed (that is, the <js-install> directory). Accept the default or
click Browse and select a different location, and click Next.
The default <js-install> directory varies with your operating system:
• In Windows, the default is C:\Program Files\jasperserver-<ver>
• In Linux, the default is <USER_HOME>/jasperserver-<ver>
Command Line Note: Press the Enter key to accept the default. To choose a different directory location, enter that
location at the prompt.

2.1.4 Select Tomcat Configuration


JapserServer requires a web application server in order to run. The JasperServer installer is pre-configured to run with the
Apache Tomcat server. There are two options available for your Tomcat configuration.

10
JasperServer Installation Guide
The first option is to choose a "bundled Tomcat". If you choose this option, the installer puts an instance of Tomcat 5 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 and 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 and then click Next.

2.1.5 Select MySQL Configuration


JasperServer requires a database in order to run. The JasperServer installer is pre-configured to run with the MySQL
database. There are two options available for you 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:
Port 3306 (default value, user chooses alternate port if 3306 is in use).
Database User Name jasperdb. The installer creates this user which is used to connect to the
jasperserver database
Database User Password password. The installer uses this default password for the jasperdb account.
Security Note: Jaspersoft recommends that you change your database user password from the default value to a new,
secure value.
The second option is to choose an "existing MySQL". If you already have an instance of MySQL running on your 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 (ie. localhost or 172.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 user name and password of the MySQL administrative user. Enter this user name and password information and
click Enter.
Values to be entered or set to defaults if installing to an existing installation of MySQL:
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 172.0.0.1. Note that your existing MySQL instance
must reside on the local machine.
MySQL Root User Name User name of the database administrative user.
MySQL Root Password Password of the database administrative user.
Database User Name jasperdb. The installer creates this user which is used to connect to the
jasperserver database.
Database User Password password. The installer uses this default password for the jasperdb account.
Security Note: Jaspersoft recommends that you change your database user password from the default value to a new,
secure value.

2.1.6 Install Sample Data


JasperServer can be installed with sample data that can help you evaluate its features. Sample data and resources included
are the following:

11
JasperServer Installation Guide
• 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.
• JasperServer repository resources such as Reports, Analysis 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 Install iReport


iReport is the leading GUI-based JasperReports creation tool. It has the capability of communicating directly with a
JasperServer instance and can thus retrieve existing JasperReports from a JasperServer instance for editing, uploading or
execution.
In the installer, iReport comes pre-configured with a plugin that allows it to communicate with JasperServer 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.

2.1.9 Installation Complete Screen


After the JasperServer files have been installed, you will see the final installation screen. There are additional Post-
Installation options that you can choose from. Each of these options has an associated checkbox that will enable or disable
the option. Simply click to make your choices and then click Finish.
View Release Notes - Checkbox
If you choose to view the Release Notes, they are displayed in an additional window.
Command Line Note: If you are running from the command line, you can page throught the Release Notes by pressing the
Enter key.
Launch JasperServer Now - Checkbox
If you choose to launch JasperServer from the installer, the installer exits and the application server starts. It takes a few
moments for the server to start up. When this is complete, the JasperServer login page appears in your system default
Browser. For more information on logging in, see section 3.3, "Logging into JasperServer".
Note: Starting JasperServer from the installer is dependent on your Tomcat and MySQL configuration choices. The
JasperServer start/stop scripts only control the "bundled" applications that you chose to be installed. For more information,
see section 3, "Starting and Stopping JasperServer".
Note: If you chose to view the Release Notes, JasperServer will not startup until you close the Release Notes.
Opt-in for JasperServer Heartbeat - Checkbox
The JasperServer heartbeat will help Jaspersoft create better products by improving our understanding of customer
installation environments. If you choose to enable the heartbeat, at server startup time the following information 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
• JasperServer - type and version
• Unique, anonymous identifier value

12
JasperServer Installation Guide
If you take the Checkbox default, the heartbeat is enabled. If you deselect the Checkbox, the heartbeat component is
disabled. You can later enable or disable the heartbeat by modifying the jasperserver/WEB-INF/applicationContext-
logging.xml file.
For additional information on enabling and disabling the heartbeat component refer to the JasperServerAdministrator
Guide.

2.1.10 Log Into JasperServer


You should now be ready to login to JasperServer. You can move forward to section 3.3, "Logging Into JasperServer", for
information on default login credentials.

2.2 Post-Installation Steps

2.2.1 Updates Made During Installation


This first sub-section is informational. It lists the standard updates that are made by the installer to your local environment
if you install to already existing applications.
Updates to the application server:
If you installed to an existing Tomcat updates were attempted to the Tomcat environment.
Here is a list of the updates:
Application File or Directory Notes
Tomcat bin/setenv.bat, bin/setevn.sh Added this file. Sets increased Java memory
allocation values to JAVA_OPTS.
Note: refer to section 5.12, "Set Java JVM
Options" for additional settings.
Tomcat 5 common/lib Add MySQL JDBC driver.
Tomcat 6 lib Add MySQL JDBC driver.

Updates to the MySQL database:


If you installed to an existing MySQL database, new schemas and users are created in your database instance:
MySQL Updates Notes
Database "jasperserver" created This holds the JasperServer Application metadata and
customer business data such as Reports, Analysis Views, Data
Sources, Permissions, Roles, and Users.
Database user "jasperdb" created JasperServer connects to the database using this user.
Sample database "foodmart" created Database created if install sample data option was chosen.
Sample database "sugarcrm" created Database created if install sample data option was chosen.

2.2.2 Installer Output Log File


The installer creates a log during installation that records information as the installation progresses. If you encounter any
problems when you install JasperServer, it can be helpful to look at the installer log for any potential errors. You can find
the installer log in the following locations:
Windows:

13
JasperServer Installation Guide
C:\Documents and Settings\<username>\Local Settings\Temp\bitrock_installer_<number>.log
Linux:
/tmp/bitrock_installer_<number>.log

2.2.3 Check your Java JVM Options


For both the bundled Tomat 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.12, "Set Java JVM Options". If you are running Java 1.6, there are
pointers to additional information in this section.

14
JasperServer Installation Guide

3 Starting and Stopping JasperServer


Before JasperServer is started, the database it depends on must be running. Then, JasperServer is started by starting the
application server that JasperServer is deployed to.

3.1 Using JasperServer Start/Stop Scripts


If you chose to install a bundled Tomcat and a bundled MySQL, then the JasperServer start/stop scripts will allow you to
start both applications with a single script.
To Start and Stop JasperSErver, do the following:
From Windows Start Menu:
Click Start> All Programs> JasperServer> JasperServer Management> Start JasperServer.
Click Start> All Programs> JasperServer> JasperServer management> Stop JasperServer.
From Command Line:
cd <js-install>/bin (Windows)
./allclt.bat start [stop]
cd <js-install> (Linux)
./jasperctl.sh start [stop]

3.2 Using Start/Stop Scripts Without Bundled Installation


If you used your own existing installation for one of either Tomcat or MySQL you can still use the start/stop scripts
mentioned in the previous section. The scripts would only start the bundled application that you chose to have the installer
install.
So, for instance, if you have an existing Tomcat and a bundled MySQL, the scripts and menus specified in the previous
section would only start and stop the MySQL application.
If you used your existing versions of Tomcat and MySQL then you should use the start and stop scripts provided by those
applications.

3.3 Logging into JasperServer


This section assumes that JasperServer is running. If it isn’t, start it as described in the section above.
Log into JasperServer by entering the correct URL in your browser’s address field and supplying the correct user name and
password. JasperServer supports Mozilla Firefox and Internet Explorer. The URL varies with your application server:
Application Server URL
Tomcat http://<hostname>:8080/jasperserver
where:
• <hostname> is the name of the computer hosting JasperServer.
• <ip_address> is the IP address of the computer hosting JasperServer (if not using hostname).
• 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 JasperServer.
In Windows, you can also launch the JasperServer login page from the desktop of its host by clicking Start> All
Programs> JasperServer> JasperServer.

15
JasperServer Installation Guide
If the login page appears, JasperServer has started properly. You may now login with the following username and
password:
Username: jasperadmin (default administrative user)
Password: jasperadmin
If you installed the sample data then additional sample end-users are created. These end users are non-administrative users
who have less system privileges than an administrative user. End-users:
Username: joeuser (sample standard end-user)
Password: joeuser
Username: demo (special SuperMart Dashboard demonstration end-user)
Password: demo
Security Note: Once you have completed the evaluation or testing of your JasperServer instance, you should change your
administrative password and change the passwords for the sample end-users (or remove the sample end-users).

3.4 Starting the Included iReport


If you chose to install iReport as part of the JasperServer installation, you may start iReport from the Windows Start menu.
To do this, click Start> All Programs> JasperServer> Start iReport.

3.5 JasperServer Log Files


Log files contain important information about how JasperServer is running.
The JasperServer log file location is:
<application-server-path>/jasperserver/WEB-INF/logs/jasperserver.log
The log4j.properties file location is:
<application-server-path>/jasperserver/WEB-INF/log4j.properties
Note: By default, JasperServer only logs errors and warnings.
In addition to the JasperServer log, your application server and database server also log information about JasperServer.
For information about the logs written by your application server and your database server, refer the associated
documentation.

16
JasperServer Installation Guide

4 Uninstalling JasperServer
In Windows, click Start > All Programs > JasperServer> Uninstall to uninstall JasperServer.
In addition, in Windows, you can open the Control Panel and double-click the Add or Remove Software option. Locate
JasperServer in the list of installed software and click Change/Remove. You are prompted to remove the software. Indicate
Yes and follow the on-screen instructions.
Under Linux, the <js-install> directory includes an executable that removes JasperServer 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 JasperServer. Press Y and then press Enter to remove JasperServer from this
computer.

17
JasperServer Installation Guide

5 Install Using the War File Distribution for Tomcat or JBoss

5.1 Introduction
In addition to the installer binaries, the JasperServer application is distributed as a stand-alone WAR file distribution. This
distribution is packaged as a ZIP file.
Customers who do not wish to use the installer or who have target configurations other than those supported by the installer
should use the WAR file distribution.

5.1.1 Applications Supported by the War File Distribution


The instructions in this section and the following sections support this configuration:
Target Configuration Instructions Location
Tomcat or JBoss with MySQL This section

5.1.2 Application Versions Supported


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 Obtain the War File Distribution


The WAR file distribution comes in a ZIP file format. To download the WAR file distribution, contact Technical Support
or your sales representative.

5.3 Unpack the War File Distribution Zip


Once you have downloaded the WAR file distribution, you need to unpack it in order to access the contained files.
Choose a top level directory location to unpack the ZIP file to. The ZIP file creates a directory with the following naming
structure:
jasperserver-<ver>-bin
Unpack to a directory location such as:
C:\jasperserver-<ver>-bin (Windows)
/home/<user>/jasperserver-<ver>-bin (Linux)

5.4 Setup the JasperServer Database


• To begin the database setup for JasperServer, your database must be installed and running.
• The steps below describe setting up JasperServer with the minimal database setup. Later sections describe the
steps used for adding the JasperServer sample data to your new JasperServer instance.
• This document gives example database setup commands that have been tested at Jaspersoft. The precise
commands to be used with your database instance may be different.
• The database setup commands should be run from the Windows or Linux command line.
18
JasperServer Installation Guide
5.4.1 MySQL Database Setup Steps
The MySQL client software, mysql.exe or mysql, is used to create and populate the database.
This document gives example database setup commands that have been tested at Jaspersoft. The precise commands to be
used on your MySQL instance may be different.
These commands should be run from the Windows or Linux command line.
Create and Populate the Database
Please check your database user documentation for how to set up a database and how to create a database user. Create the
following database instance, database user and password.
First move to the scripts directory:
cd <unpacked-war-dir>/scripts/mysql
Enter the following commands:
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 jasperserverCreate-mysql.ddl (create schema)
mysql>source jasperserverCreateDefaultSecurity-mysql.sql (populate minimal data)
mysql>exit
Note: If you are going to access MySQL on a remote server you should run and additional grant statement:
mysql>grant all on *.* to jasperdb@'%' identified by 'password';
The database is now setup for use with JasperServer.

5.5 Deploy JasperServer War to the Application Server


The process for deploying JasperServer into the application server involves “dropping” the War file into the proper
directory.
Copy the WAR file:
<unpacked-war-dir>/jasperserver.war
To the following directory:
<apache-tomcat>/webapps (Tomcat)
<jboss>/server/default/deploy (JBoss)

5.6 Prepare for Database Configuration

5.6.1 Default Database Configuration Values


By default, the database configuration files included with the JasperServer War file distribution are set to connect to a
database with the following settings:
Setting Default Config for MySQL

19
JasperServer Installation Guide
Database Host localhost
Database Name jasperserver
Database User jasperdb
Database Password password
Database Port 3306
Database SID N/A
Hibernate Dialect MySQLDialect
Quartz Driver Delegate StdJDBCDelegate
Your instance of JasperServer should be modified to support the values in your own database environment.

5.6.2 Expand the Archived War File


The jasperserver WAR file is “archived" so you cannot directly edit files inside of it. The JasperServer database
configuration file is inside the WAR file, so we must "un-archive" the WAR file first. JasperServer runs using this
"unarchived" WAR file.
Un-archive the War File Using the Java “jar” Command
You can use the following steps to un-archive the WAR file:
Tomcat and JBoss
cd <apache-tomcat>/webapps (Tomcat)
cd <jboss>/server/default/deploy (JBoss)

mkdir jasperserver
cd jasperserver
jar xvf ../jasperserver.war (x - extract, v - verbose, f - is filename)
cd ..
rm –r jasperserver.war or del jasperserver.war (remove the original WAR file)
JBoss
mv jasperserver jasperserver.war (add .war to end of dir name)
copy jasperserver jasperserver.war (same in Windows)

5.7 Configure Hibernate Properties File


By default, the hibernate properties are set to run with the MySQL database. If you are running another database then you
must update your hibernate configuration properties file.
The properties file is found at the following location:
<apache-tomcat>/webapps/jasperserver/WEB-INF/hibernate.properties
<jboss>/server/default/deploy/jasperserver/WEB-INF/hibernate.properties
Edit this file and set the dialect property to the appropriate value.
MySQL

20
JasperServer Installation Guide
metadata.hibernate.dialect=org.hibernate.dialect.MySQLDialect

5.8 Deploy JDBC Database Driver


The application server needs the appropriate JDBC driver in order for JasperServer to connect to the database. A set of
drivers are included with the JasperServer distribution for your convenience. You may want to check with your database
vendor for a more up to date version of the JDBC driver.
Copy one of these JDBC drivers:
<unpacked-war-dir>/scripts/drivers/mysql-connector-java-<ver>-bin.jar (MySQL)
To your application server lib location:
<apache-tomcat>/common/lib (Tomcat 5)
<apache-tomcat>/lib (Tomcat 6)
<jboss>/server/default/lib (JBoss)

5.9 Database Connection Steps for Tomcat


By default, the jasperserver WAR file is pre-configured to run with Tomcat.
You must edit this file to specify your database configuration settings. Modify the following file:
<apache-tomcat>/webapps/jasperserver/META-INF/context.xml

5.9.1 MySQL context.xml for Tomcat


Edit the items in bold and supply settings for your installation:
<Context path="/jasperserver"
debug="5" reloadable="true" crossContext="true">

<Resource name="jdbc/jasperserver" auth="Container" type="javax.sql.DataSource"


maxActive="100" maxIdle="30" maxWait="10000"
username="jasperdb" password="password" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/jasperserver ?useUnicode=true&amp;characterEncoding=UTF-8"/>

<!—Configs below are for Sample Data -->


<Resource name="jdbc/sugarcrm" auth="Container" type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="10000"
username="jasperdb" password="password" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/sugarcrm"/>

<Resource name="jdbc/foodmart" auth="Container" type="javax.sql.DataSource"


maxActive="100" maxIdle="30" maxWait="10000"
username="jasperdb" password="password" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/foodmart"/>
</Context>

5.10 Database Connection Steps for JBoss


JBoss uses a data source definition file to setup the database connections for JasperServer.
Example data source definition files are found in the <unpacked-war-dir>/scripts/jboss directory for each of the supported
database servers.

21
JasperServer Installation Guide
5.10.1 MySQL Datasource for JBoss
The <unpacked-war-dir>/scripts/jboss directory contains a sample js-mysql-ds.xml file.
This data source definition file should be copied to the following location:
….<jboss>/server/default/deploy
You should edit this file and make sure that it has the proper settings for your database configuration.
Check that the following lines have the appropriate values:

<connection-url>jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&amp;characterEncoding=UTF-8</connection-url>
<connection-url>jdbc:mysql://localhost:3306/sugarcrm?useUnicode=true&amp;characterEncoding=UTF-8</connection-url>
<connection-url>jdbc:mysql://localhost:3306/foodmart?useUnicode=true&amp;characterEncoding=UTF-8</connection-url>
<user-name>jasperdb</user-name>
<password>password</password>

5.11 Extra Configuration Step for JBoss


Note: When JasperServer is running under JBoss, there are a couple of INFO log messages and an XMLA connection error
that might occur depending on the version of JBoss you are running with.
Refer to section B.9 "JBoss Modifications" in the Troubleshooting Appendix B for more information.

5.12 Set Java JVM Options


When working with some of the new JasperServer features such as Domains, it is easy to take up a large amount of java
memory. Additionally, if your application uses large datasets, as is typical of many customers, it is important to increase the
java JVM memory allocation settings.
The following table laysout recommended settings for Java 1.5.
General Java 1.5 JVM Settings
The following are a number of recommended settings for Java 1.5. These settings can be increased or decreased for your
particular requirements.
General Recommended Java JVM Settings:
Tomcat file <tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh)

JBoss file <jboss>/bin/run.bat or run.sh

JAVA_OPTS setting set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m

(Windows) set JAVA_OPTS=%JAVA_OPTS% -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -


XX:+CMSPermGenSweepingEnabled

JAVA_OPTS setting JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m "

(Linux) JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled "

Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.
Settings for Java 1.6
If you are using Java 1.6, the recommended settings are slighly different than those for Java 1.5. Also, there are specific
settings needed to avoid class conflicts between java 1.6 and JasperServer web services.
For Java 1.6 JVM settings, refer to Appendix C "Java 1.6 JVM Settings".
General Note on Java Settings
The settings specified in this section apply specifically to the Sun JVM. Other JVM implementations may or may not have
equivalent settings.

22
JasperServer Installation Guide
5.12.1 JVM Options for JBoss
JBoss 4.2 includes an implemetation of web services. These web services classes can conflict with the web services classes
included with JasperServer. If you are using Java 1.6, the instructions in the section above walk through the steps to resovle
these conflicts.
However, if you are running JBoss 4.2 under Java 1.5, you will still need to set some specific JVM options so that the web
services analysis XMLA feature of JasperServer works.
For information on this, refer to section B.9.2, "JBoss 4.2 XMLA Connection Fix", in TroubleShooting Appendix B.

5.13 Start JasperServer


To run JasperServer start your application server.
Start the JasperServer application:
<apache-tomcat>/bin/startup.bat or startup.sh (Tomcat)
<jboss>/bin/run.bat or run.sh (JBoss)
The JasperServer log output goes to the following location:
<apache-tomcat>/webapps/jasperserver/WEB-INF/logs/jasperserver.log (Tomcat)
<jboss>/server/default/deploy/jasperserver/WEB-INF/logs/jasperserver.log (JBoss)
You can change the log4j logging level for the overall application or for particular classes by modifying the following
property:
<apache-tomcat>/webapps/jasperserver/WEB-INF/ log4j.properties (Tomcat)
<jboss>/server/default/deploy/jasperserver/WEB-INF/ log4j.properties (JBoss)
The application server console log should also be checked for errors.

5.14 Login to JasperServer


If JasperServer started up cleanly you should be able to login.
Login by going to the following URL:
http://<hostname>:8080/jasperserver
Example:
http://localhost:8080/jasperserver
http://my.server.com:8080/jasperserver
The login page should appear after some time to compile the necessary .jsp file.
Use the following credentials to login to the system:
Username: jasperadmin (Administrative user)
Password: jasperadmin
If you logged in successfully, your JasperServer home page appears.
Refer to the JasperServer User Guide to begin adding reports and other objects to JasperServer.
Security Note: Jaspersoft recommends that you change your jasperadmin login password from the default value to a new,
secure value.

23
JasperServer Installation Guide
5.14.1 JasperServer Heartbeat
Upon first login to a newly installed JasperServer, you will be asked whether to opt-in to the JasperServer Heartbeat or not.
To opt-in, click OK. To opt-out, click the check box to remove the check and click OK.
The JasperServer heartbeat will help Jaspersoft create better products by improving our understanding of customer
installation environments. If you choose to enable the heartbeat, at server startup time the following information 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
• JasperServer - type and version
• Unique, anonymous identifier value
You can also manually enable or disable the heartbeat by modifying the jasperserver/WEB-INF/applicationContext-
logging.xml file.
For additional information on enabling and disabling the heartbeat component refer to the JasperServer Administrator
Guide.

5.15 Setup and Load Sample Data


The WAR file distribution ZIP file comes with a set of scripts and a utility that allow for the setup of a full set of sample
data. This includes sample Reports, Analysis Views, Ad Hoc Topics, Domains, Data Sources, Users, and Roles.
To create the sample data, you should have already run the steps described above and you should be able to start and login
to JasperServer.
The commands that follow are intended to be run at the Windows or Linux command line.

5.15.1 MySQL Sample Database Create and Populate


cd <unpacked-war-dir>/scripts/mysql
mysql -u root -p (login to mysql client)
mysql>create database sugarcrm;
mysql>create database foodmart;
mysql>use sugarcrm;
mysql>source sugarcrm-mysql.sql;
mysql>use foodmart;
mysql>source foodmart-mysql.sql;
mysql>exit

5.15.2 Check Context.xml or JBoss Datasource for Sample Data Config


You already configured and tested the Tomcat context.xml or the JBoss datasource file for connecting to the jasperserver
database.
This would be a good time to check that you have the settings correct for the two databases you created above: foodmart
and sugarcrm. These files were configured in section 5.9, "Database Connection Steps for Tomcat", or section 5.10
"Database Connection Steps for JBoss", above.

24
JasperServer Installation Guide

5.16 Import the JasperServer Sample Metadata

5.16.1 Prepare for Running the Import Utility


The JasperServer import utility is used to load metadata into the JasperServer repository. This metadata fully describes
objects such as reports, report schedules, permissions, and data sources. The database that is updated is the jasperserver
repository database.
The import utility reads a “repository catalog” file that is a set of XML and binary files organized in a directory style
structure.
The shell script that runs the import operation is found in the scripts directory. First, make sure that the import-export utility
is properly configured for execution. You must edit the following file to specify your database settings:
<unpacked-war-dir>/scripts/config/js.jdbc.properties
You should use the same settings that you did in earlier database configuration sections.
MySQL Settings
Refer to Appendix A, "Configuring the Import-Export Utility", section A.3, "Sample Settings for MySQL".

5.16.2 Run the Import Utility


To run the import utility, enter the following command:
cd <unpacked-war-dir>/scripts
js-import.bat --input-dir js-catalog (Windows)
js-import.sh --input-dir js-catalog (Linux)
Notes:
• The import command depends on the JAVA_HOME variable being set in your environment.
• There are two dashes (--) in front of the command option.

5.17 Report Scheduling Configuration


The scheduled reporting feature of JasperServer 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.
Here is the configuration file for Report Scheduling:
• js.quartz.properties

5.17.1 js.quartz.properties
Note: For release 3.1, the contents of the older js.mail.properties and js.scheduler.properties have been merged into the
single file js.quartz.properties.
The quartz properties file is found at the following location:
<apache-tomcat>/webapps/jasperserver/WEB-INF/js.quartz.properties
<jboss>/server/default/deploy/jasperserver/WEB-INF/js.quartz.properties
In this file you will find the configuration settings for you mail server, for additional scheduling email settings, and for the
underlying Quartz Framework used to enable the scheduling feature.
Quartz Driver Delegate Setting
MySQL

25
JasperServer Installation Guide
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
PostgreSQL
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
Note: For more information on the Quartz Framework, see the quartz website:
http://www.opensymphony.com/quartz

5.17.2 js.mail.properties
For the 3.1 release the contents of this file have been merged into the js.quartz.properties file.

5.17.3 js.schedular.properties
For the 3.1 release the contents of this file have been merged into the js.quartz.properties file.

5.18 Restart JasperServer


If you have made configuration changes to your JasperServer instance, you should restart JasperServer

5.19 Update XMLA Connection Definitions (Optional)


JasperServer is able to make XMLA connections over the Web Services interface. These http-based connections use a
JasperServer login 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 hostnames and port values might be different
than the default values.
If you would like to run the samples that use this XMLA interface, you should update your XMLA connection definitions.
For instance, an analysis view that uses this connection is:
SugarCRM Sample XMLA Analysis View
The XMLA connection definitions to update with your local configuration values the following:
/Analysis Components/ Analysis Connections/ Foodmart XMLA Connection
/Analysis Components/ Analysis Connections/ SugarCRM XMLA Connection
The updates are made by editing repository objects in your running instance of JasperServer via the UI.
To make these updates, take these steps:
• Login to JasperServer as an Administrative user (such as jasperadmin).
• Navigate to the Repository Management page via the View> Repository menu item.
• Click to expand the Analysis Components folder, then the Analysis Connections folder. Click to highlight the
Foodmart XMLA Connection resource, and then click the Edit icon.
• Edit the information on this page for:
o URI (hostname and port)
o Login Username
o Login Password
• Click Next, then Save.
• Make the same updates for the SugarCRM XMLA Connection resource.

26
JasperServer Installation Guide

5.20 Troubleshooting your JasperServer Configuration


Startup Problems
When trying to run a newly setup JasperServer instance, the most typical problems that users encounter are problems with
database configuration.
These problems are typically related to having incorrect configurations within the JasperServer database configuration files
or in the application server configuration files.
For more information on resolving these types of errors, refer to section B.2, "Database Connectivity Errors", in the
Troubleshooting Appendix B.
Error Running Report
If you have trouble running reports in your new JasperServer Instance, refer to section B3, "Error Running a Report" in the
Troubleshooting Appendix B.

27
JasperServer Installation Guide

6 Upgrade from JasperServer 3.0 to JasperServer 3.1


This is the section to use if you have an existing JasperServer 3.0 application and you want to upgrade to JasperServer 3.1.
This procedure describes the exact steps to carry out this upgrade under a Tomcat application server and a MySQL database
configuration. The intention is that the same steps can be applied to other combinations of application servers and
databases.

6.1 Backup JasperServer War File and JasperServer Database


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. This work is done from a command shell under Windows or Linux.

6.1.1 Stop Your Application Server


Tomcat and other application servers may behave unpredictably if they are running while you upgrade the JasperServer
web application, so you should stop the application server until the upgrade is finished.

6.1.2 Backup the JasperServer War Archive


Backup the jasperserver directory in Tomcat to a backup directory:
cd <apache-tomcat>
mkdir js-3.0-war-backup
copy <apache-tomcat>/webapps/ jasperserver to <apache-tomcat>/js-3.0-war-backup
delete directory <apache-tomcat>/webapps/jasperserver

6.1.3 Backup the JasperServer Database


Note: The database tables and columns have not changed between 3.0 and 3.1. No database upgrade is required. However,
it is still a recommended practice to do a database backup before upgrading.
cd <unpacked-war-dir-3.0> (i.e., the location of your original unpacked 3.0 WAR file distribution)
Windows
mysqldump --user=jasperdb --password=<your-password> jasperserver > js-db-3.0-dump.sql
Linux
mysqldump --user=jasperdb --password=< your-password > --host=127.0.0.1 jasperserver > js-db-3.0-dump.sql
You can use the jasperdb user or the root user to carry out this operation. Refer to section 6.8.1, "Using mysqldump for
Database Backup", for more information on running the mysqldump command.
Note: The default MySQL database username in 3.0 and 3.1 is "jasperdb". In 2.1, the default database username is
"jasperadmin". In both cases, the default password is "password".

6.2 Unpack JasperServer 3.1 War File Distribution


It is assumed that you have already obtained the jasperserver-3.1-bin.zip distribution.
Unpack the distribution to a directory on disk. This creates the location:
<unpacked-war-dir-3.1>

28
JasperServer Installation Guide

6.3 Upgrade the JasperServer War


You have already backed up and removed your 3.0 WAR file. Now you can deploy the 3.1 WAR file into Tomcat:

6.3.1 Deploy the JasperServer WAR file


Deploy the WAR file:
copy <unpacked-war-dir-3.1>/jasperserver.war to <apache-tomcat>/webapps

6.3.2 Expand the Archived War File


The jasperserver.war file is “archived" so you cannot directly edit files inside of it. You must update the database
configurations and other configurations inside the WAR, so you must "un-archive" the WAR file first.
Follow the steps in section 5.6.2 "Expand the Archived War File" to un-archive the jasperserver.war.

6.3.3 Check for Local Configurations


In order to preserve your application server configurations for the database and for other local settings, you should copy
over the following configuration files from your 3.0 war to your 3.1 war.
Copy from <apache-tomcat>/js-3.0-war-backup>/jasperserver to <apache-tomcat>/webapps/jasperserver:
META-INF/context.xml
WEB-INF/hibernate.properties
Additional Properties
The following files have been consolidated into a single property file:
WEB-INF/js.quartz.properties
WEB-INF/js.mail.properties
WEB-INF/js.scheduler.properties
The above are consolidated into: WEB-INF/js.quartz.properties.
Manually update the properties found in js.quartz.properties.
Also, copy or integrate any other custom modifications you have made to your JasperServer 3.0 instance.
Note: Refer to section 5.5 “Deploy JasperServer War to the Application Server”, and section 5.6.2 “Expand the Archived
War File”, for general information and troubleshooting when deploying a WAR to Tomcat.

6.4 Upgrade the JasperServer Database


The database tables and columns have not changed between 3.0 and 3.1. No database upgrade is required.
Note: If you are upgrading from release 2.1 (or earlier), before proceeding see chapter 7, “Upgrade Notes for JasperServer
2.1”.

6.5 Start JasperServer 3.1


Before you actually start Tomcat with the new 3.1 WAR file, it is a good idea to clear out the Tomcat work directory. The
work directory is where compiled JSPs and other temporary files are stored.
Clear Tomcat work directory:

29
JasperServer Installation Guide
cd <apache-tomcat>/work
Remove all files below "work" directory
Now you may start Tomcat. The MySQL database should already be running.

6.6 Login to JasperServer 3.1


If Tomcat and JasperServer 3.1 were started correctly, you should be able to login.
Login using the following URL, username and password:
http://localhost:8080/jasperserver
username: jasperadmin
password: <your-password>
Your JasperServer instance has now been upgraded to 3.1.
If there are problems on startup refer to section B.2, "Database Connectivity Errors" in the Troubleshooting Appendix B.
Note: The first time you login to JasperServer 3.1, you will be prompted to opt-in or opt-out to the JasperServer Heartbeat.
Refer to Section 5.14.1, "JasperServer Heartbeat", for more information.

6.7 Sample Data Upgrade (Optional)


JasperServer comes with a set of sample data that highlight JasperServer features. This sample data is updated for each new
release to help show the newest features. Updating the sample data is not necessary unless you want to evaluate the new
JasperServer features.

6.7.1 Upgrade Sample Databases (if necessary)


The sample databases for MySQL, sugarcrm and foodmart, are unchanged between 3.0 and 3.1.

6.7.2 Configure and Run Import of Sample Data


All database applications must be specifically configured for the import operation by making the appropriate modifications
to the files in the scripts/config directory:
<unpacked-war-dir>/scripts/config
For information on configuration setup, refer to section 5.16.1, "Prepare for Running the Import Utility".
Run the Sample Data Import Command
Once your configuration is complete, you can run the commands below:
cd <unpacked-war-dir-3.1>/scripts
js-import.bat --input-dir js-catalog --update (Windows)
js-import.sh --input-dir js-catalog --update (Linux)
Additionally, refer to Appendix A, "Configuring the Import-Export Utility", for information on running the import utility.

30
JasperServer Installation Guide

6.8 Additional Notes on JasperServer Upgrade

6.8.1 Using mysqldump for Database Backup


Using the MySQL database, 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.
The following command is an example of using mysqldump to back up the JasperServer database on a Windows system:
mysqldump --user=jasperdb --password=<your-password> jasperserver > js-db-3.1-dump.sql
The following command performs the same task on a Linux system:
mysqldump --user=jasperdb --password=<your-password> --host=127.0.0.1 jasperserver > js-db-3.1-dump.sql
Notes:
• All the options in the commands above begin with two dashes (--).
• If the repository contains file resources larger than one megabyte, you may encounter the following message when
restoring the database: “ERROR 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes”. This error
requires adjustment of your MySQL server configuration. See the following URL for more information:
http://dev.mysql.com/doc/refman/5.0/en/packet-too-large.html

Note: The default MySQL database username in 3.0 is "jasperdb". In 2.1, the default database username is "jasperadmin".
In both cases, the default password is "password".

6.8.2 Additional Configuration Files


If you made modifications or customizations to your JasperServer 3.0 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.0 environment and re-integrated into the new 3.1 environment.

6.8.3 Clear the Tomcat Work Directory


This directory path is where .jsp files are compiled and other objects are stored. These can potentially cause errors when
updating to a new WAR file. It is a good practice to clear the work directory when doing an upgrade.
Change directory:
cd <tomcat-install>/work
Delete all files under the work directory.

6.8.4 Clear the Repository Cache Table


The JasperServer upgrade scripts automatically clear the repository cache table to remove old, compiled versions of your
JasperReports.
However, here is some background in case you encounter errors running reports after an upgrade. Compiled JasperReports
are cached in the JIRepositoryCache table for increased efficiency at runtime. Because the the JasperReports jar is typically
updated with each new JasperServer release, these old cached items will be out of date and cause errors at runtime. So, if
you encounter errors that mention a JasperReports "local class incompatible" error you may want to check your repository
cache table.
The steps to manually clear this table would be similar to the following:
update JIRepositoryCache set item_reference = null;
delete from JIRepositoryCache;

31
JasperServer Installation Guide
6.8.5 Update XMLA Connections (Optional)
When you upgrade your sample data to 3.1, you will normally get updated versions of your XMLA connection sample data.
XMLA connections use JasperServer login accounts for authentication. The default password used for the jasperserver
login user is now "jasperadmin". Because of this (and because you would normally update your jasperadmin password to a
new value as a standard security procedure), your XMLA connection may have an incorrect password.
If you would like to update your XMLA connections, refer to section 5.19, "Update XMLA ConnectionDefinitions".

6.8.6 Upgrade Using Export and Import Operations


Note: The database tables and columns have not changed between 3.0 and 3.1. So, the steps described below are not
necessary for a 3.0 to 3.1 upgrade. This section is being left unchanged for reference.
An alternate way to handle an upgrade is to utilize the Export and Import capability of JasperServer.
The basic scenario is that you have a 2.1 system that contains your business data (in the jasperserver repository database),
and you have a 3.0 system that you have freshly installed.
The basic scenario is that you have two independent systems. One is your existing JasperServer 2.1 system that contains
your business data resources such as Reports, Scheduled Reports, Data Sources, Users, Roles and Permissions.
The second system is a JasperServer 3.0 system that has been freshly installed either by using the JasperServer installers or
via the manual steps that are specified when using the War File Distribution zip file.
The challenge is to move your business data from your 2.1 system to your 3.0 system. You can do this using the
JasperServer import-export capability.
However, before you run the export command and the import command, you should make sure that the import-export
operations are configured correctly for your particular database environment. Check the <js-install-
2.1>/scripts/conf/js.jdbc.properites file and the <js-install-3.0>/scripts/js.jdbc.properites file.
To carry out these operations, you should follow the general steps listed below.
Export Your Business Data from 2.1
cd <js-install-2.1>/scripts
js-export.bat --everything --output-dir my-2.1-resources (Windows)
js-export.sh --everything --output-dir my-2.1-resources (Linux)
Import Your Business Data into 3.0
Copy the "my-2.1-resources" directory to <install-3.0>/scripts
cd <js-install-3.0>/scripts
js-import.bat --input-dir my-2.1-resources (Windows)
js-import.sh --input-dir my-2.1-resources (Linux)
If you have business data in your 3.0 instance, it will not be overwritten with the imported data unless you specify the
additional import option: "--update".
Now, your JasperServer 3.0 instance should be updated with your current business data.
If you encounter any errors or have any trouble with the configuration of import-export, refer to Appendix A: "Configuring
the Import-Export Utility".

32
JasperServer Installation Guide

7 Upgrade Notes for JasperServer 2.1


If you are upgrading from an older JasperServer version such as 2.1 then you must run additional database upgrade scripts.
In the upgrade steps specified in the previous section, before you run the steps in section 6.4 "Upgrade the JasperServer
Database", you should first run the steps below:

7.1 Upgrading a MySQL Database from 2.1 to 3.0


Jasperserver Database
cd <unpacked-war-dir-3.0>/scripts/upgrade
mysql> use jasperserver;
mysql> source upgrade-mysql-2.1.0-3.0.0.sql;

7.2 Upgrading from Earlier Versions


The same script upgrade principle described above should be applied to JasperServer instances older than 2.1.

33
JasperServer Installation Guide

8 Adding Password Encryption to JasperServer

8.1 Introduction
JasperServer is capable of running with encrypted passwords in the database. When this feature is enabled, passwords in
the database are stored as cipher text. Customers can choose the algorithm that JasperServer will use, as well as specify the
salt key used to initiate the encryption algorithm.
By default password encryption turned off.
This section describes the procedure to enable password encryption. For more information on JasperServer encryption
options refer to the JasperServer Administrator Guide.

8.2 General Notes


By default, JasperServer is released with encryption turned off. The steps described in this section are meant to be applied
after you have installed JasperServer.

8.3 Backup your JasperServer Database


As a precaution, you must backup your jasperserver database in case there is any problem with the encryption enabling
process.
MySQL
Under Windows or Linux enter the following commands:
cd <js-install>
Windows
mysqldump --user=jasperdb --password=<your-password> jasperserver > js-db-dump.sql
Linux
mysqldump --user=jasperdb --password=< your-password > --host=127.0.0.1 jasperserver > js-db-dump.sql

You can use the jasperadmin user or the root user to carry out this operation. Refer to section 6.8.1, "Using mysqldump for
Database Backup", for more information on running the mysqldump command.

8.4 Stop Application Server


You can now stop your application server. You should leave your database running.

8.5 Run Repository Export Utility


The Repository Export utility writes out all of the JasperServer 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, enter these commands:
cd <js-install>/scripts
js-export.bat --everything --output-dir js-backup-catalog (windows)

34
JasperServer Installation Guide
js-export.sh --everything --output-dir js-backup-catalog (Linux)
Note: There are two dashes (--) in front of the command options.
Refer to Appendix A, "Configuring the Import-Export Utility", for information on running the export utility.

8.6 Specify Encryption Settings in JasperServer War


JasperServer uses Spring configuration and acegi security to enable the encryption configuration. There is more specific
information in the JasperServer Administrator Guide about the security algorithms and settings. These options can allow
you to have a strong encryption setup. This section is focused on the minimal configuration necessary for enabling
encryption.
The file to be edited is the following:
<apache-tomcat>/jasperserver/WEB-INF/ApplicationContext-security.xml
Uncomment Reference to passwordEncoder Bean
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>
Enable Encryption in the “passwordEncoder” Bean
The property allowEncoding should be changed from false to true so that it looks like the following:
<property name="allowEncoding"><value>true</value></property>
SecretKey Definition Properties
The next two properties work with their default values. However, for better security, we recommend that they be changed.
If the default DESede algorithm is used, the secretKey (salt key) is expected to be 24 characters. The key can be in plain
text to make it easier to enter. To hold the key as plain text, you must also set the keyInPlainText property to true.
Here is an example:
<property name="keyInPlainText"><value>true</value></property>
<property name="secretKey"><value> jaspersoftInSanFrancisco</value></property>
Note: The text “jaspersoftInSanFrancisco” is 24 characters long.

Remaining Properties
The last two properties can be left unchanged. They are set to DESede by default. The default settings are the following:
<property name="secretKeyAlgorithm"><value>DESede</value></property>
<property name="cipherTransformation"><value>DESede/CBC/PKCS5Padding</value></property>

Note: As described in the JasperServer Administrator Guide, the secretKey, secretKeyAlgorithm, and
cipherTransformation property settings must be consistent with each other. For instance, different algorithms expect
different key lengths.
Encryption Now Enabled
Once the changes described above are made, encryption is enabled for the JasperServer application upon the next restart.

35
JasperServer Installation Guide

8.7 Specify Encryption Settings for Import Utility


Before starting JasperServer, you must convert the plain text passwords that are currently stored in the repository export
catalog that you created in steps above (that is, in scripts/js-backup-catalog). These plain-text passwords need to be
converted to cipher text and updated to the database in order to successfully login after server restart.
To do this, you must add the same encryption settings to the configuration file that are used by the import-export utility.
The configuration file is located here:
<js-install>/scripts/config/applicationContext-security.xml
In this file, which contains just the passwordEncoder bean definition, set the same configuration options that you set in the
previous section.

8.8 Drop and Recreate the JasperServer Database


Next, drop your existing jasperserver database and recreate an empty jasperserver database.
MySQL
Change directory to:
….cd <js-install>/scripts/mysql
Login to your MySQL client:
….mysql -u root -p
Drop the jasperserver database, create a new one and load the jasperserver schema:
….mysql>drop database jasperserver;
….mysql>create database jasperserver character set utf8;
….mysql>use jasperserver;
….mysql>source jasperserverCreate-mysql.ddl;

8.9 Run Repository Import Utility


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, change directory to:
cd <js-install>/scripts
Enter these commands:
js-import.bat --input-dir js-backup-catalog (windows)
js-import.sh --input-dir js-backup-catalog (Linux)
Note: There are two dashes (--) in front of the command options.
Refer to Appendix A, "Configuring the Import-Export Utility", for information on running the import utility.

8.10 Start Application Server


You can now start your application server. Your database should already be running.

36
JasperServer Installation Guide

8.11 Login to JasperServer


You can now login to JasperServer.
Enter your username 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.

37
JasperServer Installation Guide

Appendix A: Configuring the Import-Export Utility

A.1 Introduction
The import and export utilities let you extract resources from or add resources to a JasperServer repository. The import
utility is typically used at installation time in order to load the JasperServer sample data into the repository.
You may refer to the JasperServer Administrator Guide for more information on command options for the import and
export utility.

A.2 Import-Export Configuration Files


In the scripts directory in your installation directory, you will find the following files that make up the main parts of the
import-export utility. These are the files to use or modify to make configuration changes.

scripts/js-import.bat Import batch script for Windows.


scripts/js-import.sh Import shell script for Linux
scripts/config/js.jdbc.properties Database and hibernate dialect settings file
scripts/config/applicationContext-*.xml Spring configuration files
scripts/lib All of the JasperServer jar files and JDBC drivers

A.3 Change your Configuration Settings


When you install JasperServer from the installer binary, the import-export utility is automatically configured. However, if
you are doing a manual installation from the WAR File Distribution you must modify the import-export configuration files
for your database settings.
The file to be modified is the following:
<unpacked-war-dir>/scripts/config/js.jdbc.properties
Sample Settings for MySQL
Modify the items in bold to match your own environment setup:
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=jasperdb
metadata.jdbc.password=password

A 4 Deploy Database Driver


In order for the import-export utility to run, it will need the proper JDBC driver. This allows a connection to be made to the
JasperServer database.
If JDBC driver jar files are put in the following directory, they are automatically included on the classpath when the import
or export command is run using the shell scripts:
<unpacked-war-dir>/scripts/lib
Drivers can be found here:
<unpacked-war-dir>/scripts/drivers

A.5 Running Import or Export

38
JasperServer Installation Guide
To see that the import-export utility is properly configured, you can run the batch/shell scripts using the --help option which
displays the command options:
js-import.bat --help (Windows)
js-export.bat --help
js-import.sh --help (Linux)
js-export.sh --help
Note: There are two dashes (--) in front of the command option.

A.6 Home Directory Evaluation under Linux


In a Linux shell, you can use the ~/ syntax to refer to the home directory. However, because the import-export utility is a
Java application, which does not necessarily handle shell specific syntax, this specific syntax is not correctly evaluated.
Therefore, if you would like to refer to the home directory when running the import-export command under Linux, you will
have to give the absolute path to the home directory.
For instance:
./js-export.sh --uris /reports --output-dir /home/user/my-reports (instead of ~/my-reports)

39
JasperServer Installation Guide

Appendix B: Troubleshooting
B.1 Installer Freezes
If you run the JasperServer installer on any platform and the installer “freezes” or “hangs”, it is helpful to look at the log
file created by the installer. This log file outputs status regarding the 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.
You can find the installer log in the following locations:
Windows:
C:\Documents and Settings\<username>\Local Settings\Temp\bitrock_installer_<number>.log
Linux:
/tmp/bitrock_installer.log or bitrock_installer_<number>.log
If you have tried multiple installs, make sure you view the most recent install log file.

B.2 Database Connectivity Errors


The most common problems encountered with a new JasperServer instance are database configuration problems. This
section contains information that may help resolve such issues.
B.2.1 Login to Database to Test 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 JasperServer. This validates
the database hostname, port, username, and password that are being used.
If you are having trouble logging into JasperServer on the login page, you can check the users and passwords that exist by
viewing the contents of the jasperserver.JIUser table.
MySQL
Start MySQL and try to log into MySQL directly using the jasperdb user.
Log into MySQL from the command line. 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 JasperServer sample configuration scripts is "password".
Note: In JasperServer 2.1 and earlier the suggested default DB user name was "jasperadmin".
B.2.2 Check Configuration File Locations
Tomcat File Locations
When using Tomcat, JasperServer configuration properties are found in the following files:
• <apache-tomcat>/webapps/jasperserver/META-INF/context.xml
• <apache-tomcat>/webapps/jasperserver/WEB-INF/hibernate.properties
• <apache-tomcat>/apache-tomcat/webapps/jasperserver/WEB-INF/web.xml
JBoss File Locations
When using JBoss, some of the JasperServer configuration properties are found in the following files:
• <jboss>/server/default/deploy/js-mysql-ds.xml
• <jboss>/server/default/deploy/jasperserver.war/WEB-INF/hibernate.properties
• <jboss>/server/default/deploy/ jasperserver.war/WEB-INF/web.xml
40
JasperServer Installation Guide
• <jboss>/server/default/deploy/ jasperserver.war/WEB-INF/jboss-web.xml
B.2.3 Special Configuration Case under Tomcat
If you installed JasperServer using the WAR File Distribution file and the manual installation procedures, Tomcat can have
a special database configuration.
The special case occurs when you have deployed the jasperserver.war file into the Tomcat webapps directory. Valid
JasperServer WAR deployments can be based on a single file (jasperserver.war) or an “unpacked” WAR file directory
(jasperserver directory).
If you use a single WAR file for deployment under Tomcat, Tomcat takes the following steps:
• Unpack the jasperserver.war file into a new directory named jasperserver.
• Take the jasperserver/META-INF/context.xml file and copy it to a new file:
o <tomcat>/conf/Catalina/Localhost/jasperserver.xml
This database configuration in <tomcat>/conf tree overrides the context.xml found in your jasperserver directory.
If you are having database trouble in this scenario, it is recommended that you keep things simple by:
• Deleting your <tomcat>/webapps/jasperserver.war file
o This causes the jasperserver directory to be used
• Deleting your <tomcat>/Catalina/Localhost/jasperserver.xml
o This causes the META-INF/context.xml from your jasperserver directory.
B.2.4 Connect to Installed/Bundled Version of MySQL
These steps are for connecting under Linux.
If you have installed JasperServer using the "bundled" version of MySQL, you may want to connect to MySQL from the
mysql client software to examine the database. In order to connect, you will need to specify the socket that MySQL is using
(as specified in <install-dir>/jasperctl.sh).
First, get the socket file location by using the linux ps (process status) command:
ps -ef | grep mysql
This displays lots of information. Look for the --socket value:
... /home/devuser/jasperserver-3.0/mysql/bin/mysqld_safe --port=3306
--socket=/home/devuser/jasperserver-3.0/mysql/tmp/mysql.sock etc...
Then run a command similar to the following:
/home/devuser/jasperserver-3.0/mysql/bin/mysql -u jasperdb -p
--socket=/home/devuser/jasperserver-3.0/mysql/tmp/mysql.sock
Note: In JasperServer 2.1 and earlier the suggested default DB user name was "jasperadmin".

B.3 Error Running a Report


If you can log into JasperServer but encounter an error when running a report within JasperServer, you can browse the
JasperServer repository to identify and resolve the problem.
Validate the Data Source Connection
One common problem with individual reports is the data sources defined in JasperServer. You can troubleshoot these
problems in the repository:
• Log into JasperServer as a user with administrative permissions and locate the report unit that returns errors.
• Click to edit the report. The data source name is found on the fourth page.
• Locate this data source in the repository and click edit.
• Review the information specified for this data source. And then click the Test Connection button to validate.

41
JasperServer Installation Guide
• Click Save or Cancel when you are done.
• 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.

B.4 Database Error after Changing MySQL Port Number


MySQL’s default port is 3306. If you entered a different port when you installed MySQL, the JasperServer 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. See the section above
“Configuration File Locations” for more information.

B.5 Case Sensitivity for Table and Column Names


A database is case-sensitive with respect to table names if it considers “customer” and “Customer” to be two different
tables. If JasperServer is using a case-sensitive database, it’s important that the table names specified in query strings in the
JRXML files match the actual table names found in the database. This type of problem may occur if you are transferring
data from one database to another, which may result in the case of table names changing.
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 configure to be non-case-sensitive
by setting the configuration parameter lower_case_table_names to 1 in the my.ini or my.cnf file. In the MySQL
documentation see the section “Identifier Case Sensitivity” for more information.
Table and column names in Oracle and PostgreSQL are case-sensitive.

B.6 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.
This Java option is set within the application server, so you must set it and then restart your application server.
For Tomcat:
<apache-tomcat>/bin/setclasspath.bat or setenv.bat
<apache-tomcat>/bin/setclasspath.sh or setenv.sh
For JBoss:
<jboss>/bin/run.bat
<jboss>/bin/run.sh
Add to your JAVA_OPTS setting:
-Xms128m -Xmx512m or
-Xms512m -Xmx1024m or
Another memory resource related error is running out of PermGen space. If you encounter an error relating to PermGen
space you can make the following updates to your JAVA_OPTS:
-XX:PermSize=32m -XX:MaxPermSize=128m
So, here would be sample settings:
set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m (Windows)
JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m" (Linux)

Note: Refer to section 5.12, "Set Java JVM Options", for more information on Java JVM settings.

B.7 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:

42
JasperServer Installation Guide
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
you’re my.ini or my.cnf MySQL configuration file.
Add the following setting:
max_allowed_packet=32M

B.8 Upgrade: Error During JasperServer 1.2 Export


Upgrading from 1.2 to 2.0 typically requires doing an export operation on your 1.2 database. If you get a null pointer
exception like the following:
java.lang.NullPointerException
ResourceExporter.exportResource(ResourceExporter.java:258)
it may be due to an incorrect character in the following file:
scripts/ji-export-util/jdbc.properties.
The URL in this file should be checked. It should look like the following:
jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&characterEncoding=UTF-8
Note the ampersand "&" character. It is incorrect if it looks like the following: "&amp;".
The "&amp;" is only correct in HTML or XML context. It is incorrect in a properties file.
The error described in this section is known to happen if the user has i18n characters in their repository objects.

B.9 JBoss Modifications


B.9.1 JBoss with PostgreSQL Modifications
When JBoss is running with the PostgreSQL JDBC database driver there is an issue where autocommit is not effectively set
to false via the datasource definition. PostgreSQL needs autocommit set to false in order to handle the Large Object
datatype (ie blobs). There is a special configuration in order to force autocommit to false for PostgreSQL.
Edit:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF/applicationContext.xml
Uncomment the following line:
<value>/WEB-INF/js.jdbc-postgresql.properties</value>
Edit:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF/applicationContext-datasource.xml
Comment out the first datasource definition and uncomment the section that follows:
<!--
<bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName" value="java:comp/env/${metadata.hibernate.dataSource.jndiName}"/>
</bean>
-->

<bean id="dsAdapter" destroy-method="destroy"


class="org.postgresql.ds.PGConnectionPoolDataSource">
<property name="serverName" value="${metadata.jdbc.serverName}"/>
<property name="databaseName" value="${metadata.jdbc.databaseName}"/>
<property name="portNumber" value="${metadata.jdbc.port}"/>
<property name="user" value="${metadata.jdbc.username}"/>
<property name="password" value="${metadata.jdbc.password}"/>
</bean>

43
JasperServer Installation Guide
<bean id="dataSource"
class="org.apache.commons.dbcp.datasources.SharedPoolDataSource">
<property name="connectionPoolDataSource">
<ref local="dsAdapter"></ref>
</property>
<property name="defaultAutoCommit" value="false"/>
<property name="maxActive" value="5"/>
<property name="maxIdle" value="4"/>
<property name="maxWait" value="10000"/>
</bean>

Copy js.jdbc-postgresql.properties:
<unpacked-war-dir>/scripts/postgresql/js.jdbc-postgresql.properties
To:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF
Edit properties file to match your PostgreSQL settings:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF/js.jdbc-postgresql.properties
The operations above will fix the JBoss with PostgreSQL error that has the following error message:
org.hibernate.exception.GenericJDBCException: could not execute query
org.postgresql.util.PSQLException: Large Objects may not be used in auto-commit mode
Reference Link: http://forums.java.net/jive/thread.jspa?messageID=228420
B.9.2 JBoss 4.2 XMLA Connection Fix
JBoss 4.2 includes the JBossWS service as a standard, default feature. JasperServer has web services support for XMLA
connections. The web services classes in JasperServer and JBoss can conflict and cause the following error when
attempting to utilize a JasperServer XMLA connection:
javax.xml.soap.SOAPException: Unable to create message factory for
SOAP: org.jboss.ws.core.soap.MessageFactoryImpl
There are two workarounds for this problem. One would be to remove the JBoss web services service archive. The other is
to set special Java JVM options.
Remove JBoss Web Services
If you are not using JBoss web services, you can simply remove the JBoss web service archive to remove the possibility of
any conflicts. To do this, remove the following service archive:
<jboss>/server/defalut/deploy/jbossws.sar
Set Java JVM Options
If you are using Java 1.5 or Java 1.6, you can prevent the web services class conflict by setting the following special Java
JVM Options:
Option Target Value
Windows set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl

set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl

set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl

set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl

Linux JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl "

JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl "

JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl "

JAVA_OPTS="$JAVA_OPTS -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl "

44
JasperServer Installation Guide
Note: Refer to Appendix C: "Java 1.6 JVM Options" for more specific configuration information.

B.9.3 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. If you would like to silence this INFO message you can make an update to the JBoss
log4j configuration file found at the following location:
<jboss>/server/default/conf/jboss-log4j.xml
You can set the logging level for the CachedConnectionManager class to the following value:
<category name="org.jboss.resource.connectionmanager.CachedConnectionManager">
<priority value="WARN"/>
</category>
B.9.4 JBoss 4.0 Log4j Error on Startup
This error is seen in JBoss 4.0 (tested on 4.0.5).
Typical exception message:
log4j:ERROR "org.jboss.logging.util.OnlyOnceErrorHandler
JBoss is normally distributed with the log4j facility enabled. Log4j is initialized at JBoss startup. JasperServer also includes
and uses log4j. When JBoss loads the JasperServer war file, an exception OnlyOnceErrorHandler Exception can occur.
This error is not fatal to JasperServer, but can cause confusion when seen in the JBoss server log.
To remove this error, you can delete the JasperServer version of the log4j.jar file.
You can delete the following file:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF/lib/log4j-<ver>.jar

B.10 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:
Error while fetching Quartz runtime information
org.quartz.JobPersistenceException: Couldn't obtain triggers for job: Bad value for type int
org.postgresql.util.PSQLException: Bad value for type int
If you see this error you will need to check your Quartz properties file found at the following location:
<apache-tomcat>/webapps/jasperserver/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

45
JasperServer Installation Guide

Appendix C: Java 1.6 JVM Settings


If you are using Java 1.6 there are some additional JVM settings that will enable all JasperServer features. Java 1.6 includes
a web services implementation that can conflict with JasperServer's AXIS based web services classes. These conflicts could
cause JasperServer web services and the resources which rely on them to fail (such as analysis XMLA connections).
Note: The settings described apply specifically to the Sun JVM. Other JVM implementations may or may not have
equivalent settings.
General Java 1.6 JVM Settings
The following are a number of recommended settings for Java 1.6. These settings can be increased or decreased for your
particular requirements.
General Recommended Java 1.6 JVM Settings:
Tomcat file <tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh)

JBoss file <jboss>/bin/run.bat or run.sh

JAVA_OPTS setting set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m


(Windows) set JAVA_OPTS=%JAVA_OPTS% -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled

JAVA_OPTS setting JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m "


(Linux) JAVA_OPTS="$JAVA_OPTS -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled "

Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.

Additional Java 1.6 Web Services Settings


Java 1.6 includes a web services implementation that can conflict with JasperServer's AXIS based web services classes. In
order to prevent these conflicts we will add the special JVM settings specified below.
Java JVM Settings for Java 1.6 Only:
Tomcat file <tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh)

JBoss file <jboss>/bin/run.bat or run.sh

JAVA_OPTS set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl


setting set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl
(Windows)
set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl
set JAVA_OPTS=%JAVA_OPTS%-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl

JAVA_OPTS JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl "


setting (Linux) JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl "
JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl "
JAVA_OPTS="$JAVA_OPTS -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl "

Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.
Note: If you do not utilize JasperServer web services or resources that use them, you will not need the settings in the table
above.

46
JasperServer Installation Guide

Appendix D: Configuring and Using Ant


D.1 Downloading and installing Ant
Ant can be downloaded from http://ant.apache.org. The version of Ant used for the build script is 1.6.5, but later versions
should work. Follow the installation instructions in the download package.
Before Ant is run, you need to have the JAVA_HOME environment variable set to your Java installation directory, and the
ANT_HOME environment variable set to the directory where you installed Ant.
The commands to perform these steps in Windows are as follows:
set ANT_HOME=<ant-installation-directory>
set JAVA_HOME=<java-installation-directory>
If you are running under Linux or Unix, perform these steps:
export ANT_HOME=<ant-installation-directory>
export JAVA_HOME=<java-installation-directory>

D.2 Running Ant


Ant is run using the ant executable under the bin directory of the Ant installation. By default, it expects to have a
configuration file called build.xml in the current directory, which describes lists of tasks (called targets) that can be
performed. To run a target, include its name as an argument when running Ant. Other sections of this guide have
descriptions of specific Ant targets used for installation tasks.
To run an Ant target in Windows:
%ANT_HOME%\bin\ant <target-name>
To run an Ant target in Linux or Unix:
$ANT_HOME/bin/ant <target-name>

47

You might also like