Jasper Server Pro Install Guide

JasperServer Professional Installation Guide
Version 3.0
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.
Table of Contents
1 Introduction .................................................................................................................................7
1.1 About JasperServer Professional ......................................................................................................... 7 1.2 Conventions .......................................................................................................................................... 7 1.3 JasperServer Distributions.................................................................................................................... 7 1.4 Installer Distribution Support................................................................................................................. 8 1.4.1 Operating Systems Supported................................................................................................. 8 1.4.2 Components Included in the Installer ...................................................................................... 8 1.4.3 Applications Supported by the Installer ................................................................................... 8 1.4.4 Application Versions Supported............................................................................................... 8 1.4.5 Java Version Supported........................................................................................................... 8 1.5 War File Binary Distribution Support..................................................................................................... 9 1.6 Release Notes and Application Support ............................................................................................... 9 1.7 Prerequisites for Installation.................................................................................................................. 9 1.7.1 System Requirements.............................................................................................................. 9 1.8 Support for Internationalization ........................................................................................................... 10
Installing JasperServer ............................................................................................................11

2.1 Installation Steps................................................................................................................................. 11 2.1.1 Welcome ................................................................................................................................ 11 2.1.2 Accept License Agreement.................................................................................................... 11 2.1.3 Installation Directory Location................................................................................................ 11 2.1.4 Select Tomcat Configuration ................................................................................................. 11 2.1.5 Select MySQL Configuration ................................................................................................. 12 2.1.6 Install Sample Data................................................................................................................ 12 2.1.7 Install iReport ......................................................................................................................... 13 2.1.8 Ready to Install ...................................................................................................................... 13 2.1.9 Installation Complete Screen................................................................................................. 13 2.1.10 Log Into JasperServer............................................................................................................ 14 2.2 Post-Installation Steps ........................................................................................................................ 14 2.2.1 Updates Made During Installation.......................................................................................... 14 2.2.2 Installer Output Log File......................................................................................................... 14 2.2.3 Installing a New License File ................................................................................................. 15 2.2.4 License File for Tomcat as Windows Service........................................................................ 15 2.2.5 Check your Java JVM Options .............................................................................................. 15
Starting and Stopping JasperServer.......................................................................................16

3.1 Using JasperServer Start/Stop Scripts ............................................................................................... 16
0708.JSP30.21
JasperServer Professional Installation Guide 3.2 Using Start/Stop Scripts Without Bundled Installation........................................................................ 16 3.3 Logging into JasperServer .................................................................................................................. 16 3.4 Starting the Included iReport .............................................................................................................. 17 3.5 JasperServer Log Files ....................................................................................................................... 17
4 5
Uninstalling JasperServer........................................................................................................18 Install Using the War File Distribution for Tomcat or JBoss ................................................19
5.1 Introduction ......................................................................................................................................... 19 5.1.1 Applications Supported by the War File Distribution ............................................................. 19 5.1.2 Application Versions Supported............................................................................................. 19 5.2 Obtain the War File Distribution .......................................................................................................... 19 5.3 Unpack the War File Distribution Zip .................................................................................................. 19 5.4 Setup the JasperServer Database...................................................................................................... 20 5.4.1 MySQL Database Setup Steps.............................................................................................. 20 5.4.2 Oracle Database Setup Steps ............................................................................................... 20 5.4.3 DB2 Database Setup Steps ................................................................................................... 21 5.4.4 Microsoft SQL Server Database Setup Steps ....................................................................... 21 5.4.5 PostgreSQL Database Setups Steps .................................................................................... 23 5.5 Deploy JasperServer War to the Application Server .......................................................................... 23 5.5.1 Most Database Servers ......................................................................................................... 23 5.5.2 Microsoft SQL Server............................................................................................................. 23 5.6 Prepare for Database Configuration ................................................................................................... 24 5.6.1 Default Database Configuration Values ................................................................................ 24 5.6.2 Expand the Archived War File ............................................................................................... 24 5.7 Configure Hibernate Properties File ................................................................................................... 25 5.8 Deploy JDBC Database Driver ........................................................................................................... 25 5.9 Database Connection Steps for Tomcat............................................................................................. 26 5.9.1 MySQL context.xml for Tomcat.............................................................................................. 26 5.9.2 Oracle context.xml for Tomcat............................................................................................... 26 5.9.3 DB2 Conext.xml for Tomcat................................................................................................... 27 5.9.4 Microsoft SQL Server context.xml for Tomcat ....................................................................... 27 5.9.5 PostgreSQL context.xml for Tomcat...................................................................................... 27 5.10 Database Connection Steps for JBoss ............................................................................................... 28 5.10.1 MySQL Datasource for JBoss ............................................................................................... 28 5.10.2 Oracle Datasource for JBoss................................................................................................. 28 5.10.3 DB2 Datasource for JBoss .................................................................................................... 28 5.10.4 Microsoft SQL Server Datasource for JBoss......................................................................... 29 5.10.5 PostgreSQL Datasource for JBoss........................................................................................ 29 5.11 Extra Configuration Step for JBoss..................................................................................................... 29 5.12 Setup JasperServer License............................................................................................................... 29 5.13 Set Java JVM Options ........................................................................................................................ 31 5.13.1 JVM Options for JBoss .......................................................................................................... 31 3
JasperServer Professional Installation Guide 5.14 Start JasperServer .............................................................................................................................. 32 5.15 Login to JasperServer......................................................................................................................... 32 5.15.1 JasperServer Heartbeat......................................................................................................... 32 5.16 Setup and Load Sample Data............................................................................................................. 33 5.16.1 MySQL Sample Database Create and Populate ................................................................... 33 5.16.2 Oracle Sample Database Create and Populate .................................................................... 33 5.16.3 DB2 Sample Database Create and Populate ........................................................................ 34 5.16.4 Microsoft SQL Server Sample Database Create and Populate ............................................ 34 5.16.5 PostgreSQL Sample Database Create and Populate ........................................................... 34 5.16.6 Check Context.xml or JBoss Datasource for Sample Data Config ....................................... 34 5.17 Import the JasperServer Sample Metadata ........................................................................................ 35 5.17.1 Prepare for Running the Import Utility ................................................................................... 35 5.17.2 Run the Import Utility ............................................................................................................. 35 5.17.3 Microsoft SQL Server Run Import Utility................................................................................ 36 5.18 Report Scheduling Configuration........................................................................................................ 36 5.18.1 js.quartz.properties ................................................................................................................ 36 5.18.2 js.mail.properties.................................................................................................................... 37 5.18.3 js.schedular.properties........................................................................................................... 37 5.18.4 More Information on Report Scheduling Configuration ......................................................... 37 5.19 Restart JasperServer .......................................................................................................................... 37 5.20 Update XMLA Connection Definitions (Optional) ............................................................................... 37 5.21 Troubleshooting your JasperServer Configuration ............................................................................. 38
Install Using War File Distribution for WebSphere Application Server ...............................39
6.1 Introduction ......................................................................................................................................... 39 6.2 Obtain the War File Distribution .......................................................................................................... 39 6.3 Unpack the War File Distribution ........................................................................................................ 39 6.4 Setup the JasperServer Database...................................................................................................... 39 6.5 Configure Database Connections....................................................................................................... 39 6.5.1 Default Database Configuration Values ................................................................................ 39 6.5.2 Configuring JDBC Provider.................................................................................................... 40 6.5.3 Configuring Database User ................................................................................................... 40 6.5.4 Configuring JDBC Data Sources ........................................................................................... 40 6.5.5 Check the Hibernate Properties Configuration ...................................................................... 41 6.6 Setup JasperServer License............................................................................................................... 41 6.7 Deploy the JasperServer War to the Application Server .................................................................... 41 6.8 Set Java JVM Options ........................................................................................................................ 41 6.9 Start JasperServer .............................................................................................................................. 42 6.10 Login to JasperServer......................................................................................................................... 42 6.11 Setup Sample Data............................................................................................................................. 42 6.12 Report Scheduling Configuration (Optional)....................................................................................... 42 6.13 Restart JasperServer .......................................................................................................................... 43
0708.JSP30.21
JasperServer Professional Installation Guide 6.14 Update XMLA Connection Definitions (Optional) ............................................................................... 43 6.15 Troubleshooting your JasperServer Configuration ............................................................................. 43
Install Using War File Distribution for WebLogic Application Server..................................44

7.1 Introduction ......................................................................................................................................... 44 7.2 Obtain the War File Distribution .......................................................................................................... 44 7.3 Unpack the War File Distribution ........................................................................................................ 44 7.4 Setup the JasperServer Database...................................................................................................... 44 7.5 Configure Database Connections....................................................................................................... 44 7.5.1 Default Database Configuration Values ................................................................................ 44 7.5.2 Configuring Data Sources...................................................................................................... 45 7.5.3 Connection Properties ........................................................................................................... 46 7.5.4 Test Database Connection .................................................................................................... 46 7.5.5 Select Targets........................................................................................................................ 47 7.5.6 Check the Hibernate Properties Configuration ...................................................................... 47 7.6 Prepare WebLogic Environment......................................................................................................... 47 7.7 Prepare Domain Library...................................................................................................................... 48 7.8 Deploy JasperServer to the Application Server.................................................................................. 48 7.9 Start JasperServer .............................................................................................................................. 48 7.10 Login to JasperServer......................................................................................................................... 48 7.11 Setup Sample Data............................................................................................................................. 49 7.12 Report Scheduling Configuration (Optional)....................................................................................... 49 7.13 Restart JasperServer .......................................................................................................................... 49 7.14 Update XMLA Connection Definitions (Optional) ............................................................................... 49 7.15 Troubleshooting your JasperServer Configuration ............................................................................. 49
Upgrade from JasperServer 2.1 to JasperServer 3.0 ............................................................50

8.1 Backup JasperServer War File and JasperServer Database............................................................. 50 8.1.1 Backup the JasperServer War Archive.................................................................................. 50 8.1.2 Backup the JasperServer Database ...................................................................................... 50 8.2 Unpack JasperServer 3.0 War File Distribution.................................................................................. 50 8.3 Upgrade the JasperServer War .......................................................................................................... 51 8.3.1 Deploy the JasperServer WAR file ........................................................................................ 51 8.3.2 Expand the Archived War File ............................................................................................... 51 8.3.3 Check for Local Configurations.............................................................................................. 51 8.4 Upgrade the JasperServer Database ................................................................................................. 51 8.4.1 MySQL ................................................................................................................................... 51 8.4.2 Oracle..................................................................................................................................... 51 8.4.3 SQL Server ............................................................................................................................ 52 8.5 Start JasperServer 3.0 ........................................................................................................................ 52 8.6 Login to JasperServer 3.0................................................................................................................... 52 8.7 Sample Data Upgrade (Optional) ....................................................................................................... 52 5
JasperServer Professional Installation Guide 8.7.1 8.7.2 Upgrade Sample Databases (if necessary)........................................................................... 53 Configure and Run Import of Sample Data ........................................................................... 53
8.8 Additional Notes on JasperServer Upgrade ....................................................................................... 54 8.8.1 Using mysqldump for Database Backup ............................................................................... 54 8.8.2 Additional Configuration Files ................................................................................................ 54 8.8.3 Clear the Tomcat Work Directory .......................................................................................... 54 8.8.4 Clear the Repository Cache Table......................................................................................... 55 8.8.5 Update XMLA Connections (Optional)................................................................................... 55 8.8.6 Upgrade the Liferay Portal ..................................................................................................... 55 8.8.7 Upgrade Using Export and Import Operations ...................................................................... 55
Upgrade Notes for JasperServer 2.0.......................................................................................57

9.1 MySQL ................................................................................................................................................ 57 9.2 Oracle.................................................................................................................................................. 57 9.3 Export and Import Operation from 2.0 to 3.0 Error ............................................................................. 57
10 Adding Password Encryption to JasperServer......................................................................59

10.1 Introduction ......................................................................................................................................... 59 10.2 General Notes ..................................................................................................................................... 59 10.3 Backup your JasperServer Database ................................................................................................. 59 10.4 Stop Application Server ...................................................................................................................... 59 10.5 Run Repository Export Utility .............................................................................................................. 60 10.6 Specify Encryption Settings in JasperServer War .............................................................................. 60 10.7 Specify Encryption Settings for Import Utility...................................................................................... 61 10.8 Drop and Recreate the JasperServer Database ................................................................................ 61 10.9 Run Repository Import Utility .............................................................................................................. 62 10.10 10.11 Start Application Server ......................................................................................................... 62 Login to JasperServer............................................................................................................ 63
Appendix A: Configuring the Import-Export Utility .....................................................................64 Appendix B: Troubleshooting .......................................................................................................67 Appendix C: Java 1.6 JVM Settings ..............................................................................................74 Appendix D: Configuring and Using Ant ......................................................................................75
0708.JSP30.21
1 Introduction
1.1 About JasperServer Professional
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 Paths and File Locations <js-install> <apache-tomcat> Meaning The root directory where JasperServer will be installed. 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. The directory where JBoss is installed. 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. The directory where java is installed The directory where user unpacks the WAR file distribution ZIP. The user name and password of the default JasperServer login administrative user. The user name and password for the default database user.
<jboss> <mysql>
<java> Additional Locations <unpacked-war-dir> jasperadmin/ jasperadmin jasperdb/password
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 Installers War File Binary Distribution Zip Notes Runs on Windows and Linux Used for manual installation
1.4 Installer Distribution Support

1.4.1 Operating Systems Supported
The installers support the following operating systems: Windows Windows 2003 Windows XP Windows Vista Linux Red Hat Enterprise Linux SUSE 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 JasperServer Application Java 1.5 Runtime MySQL Database Apache Tomcat JasperServer Documentation Notes War file and configuration support scripts Runs web application container (optional) Database Server (optional) Web application container (optional) 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 Apache Tomcat bundled Apache Tomcat bundled Apache Tomcat existing Apache Tomcat existing Database MySQL bundled MySQL existing MySQL bundled 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.
1.5 War File Binary Distribution Support

The WAR file distribution is the distribution 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 JasperServer WAR file archive JasperServer Database Scripts JasperServer Standard Sample Data JasperServer Extra Samples Notes This contains all of the JasperServer class files and dependent jars. SQL scripts for each supported database. Sample data that highlights JasperServer features. Web Service example applications, sample reports, custom data source examples, and other sample files. Guides for end users and administrators.
JasperServer Documentation
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 Professional 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
Windows
Disk
Installed Footprint
Recommended Minimum
10 GB free
Recommended
~600MB
40 GB +

RAM CPU (class) 512 MB 1 GHz (single Pentium) OSX ~600MB 10 GB free 512 MB 1 GHz (single Pentium) 1 GB + 1.5 GHz + (multi-core Pentium) OSX 40 GB + 1 GB + 1.5 GHz + (multi-core Pentium)
MAC
Disk RAM CPU (class)
Linux
Disk RAM CPU (class) ~600MB 10 GB free 512 MB 1 GHz (single Pentium) 40 GB + 1 GB + 1.5 GHz + (multi-core Pentium)
Solaris
Disk RAM CPU (class) ~600 MB 10 GB free 512 MB UltraSparc II 40 GB + 1 GB +
AIX
Disk RAM CPU (class) ~600 MB 10 GB free 512 MB 40 GB + 1 GB +
HP-UX
Disk RAM CPU (class) ~600 MB 10 GB free 512 MB 40 GB + 1 GB +
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 Professional Administrator Guide for instructions on how to configure software to support UTF-8.
10
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-pro-<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-pro-<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-pro-<ver> In Linux, the default is <USER_HOME>/jasperserver-pro-<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.
11
JasperServer Professional 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 Database User Name Database User Password 3306 (default value, user chooses alternate port if 3306 is in use). jasperdb. The installer creates this user which is used to connect to the jasperserver database 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 Port IP or Host Name MySQL Root User Name MySQL Root Password Database User Name Database User Password The directory where the mysql and mysqladmin binaries are located. The port number that MySQL uses (default is 3306). The value is hard coded to 172.0.0.1. Note that your existing MySQL instance must reside on the local machine. User name of the database administrative user. Password of the database administrative user. jasperdb. The installer creates this user which is used to connect to the jasperserver database. 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:
12

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 PostInstallation 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
13
JasperServer Professional 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-pro/WEB-INF/applicationContextlogging.xml file. For additional information on enabling and disabling the heartbeat component refer to the JasperServer Professional Administrator 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 Tomcat Tomcat File or Directory bin/setclasspath.bat, bin/setclasspath.sh bin/setenv.bat, bin/setevn.sh Notes Modify JAVA_OPTS to add -Djs.license.directory Added this file. Sets increased Java memory allocation values to JAVA_OPTS. Note: refer to section 5.13, "Set Java JVM Options" for additional settings. Tomcat 5 Tomcat 6 common/lib lib Add MySQL JDBC driver. 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 Database "jasperserver" created Notes This holds the JasperServer Application metadata and customer business data such as Reports, Analysis Views, Data Sources, Permissions, Roles, and Users. JasperServer connects to the database using this user. Database created if install sample data option was chosen. Database created if install sample data option was chosen.
Database user "jasperdb" created Sample database "foodmart" created Sample database "sugarcrm" created
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:
14
JasperServer Professional Installation Guide Windows: C:\Documents and Settings\<username>\Local Settings\Temp\bitrock_installer_<number>.log Linux: /tmp/bitrock_installer_<number>.log
2.2.3 Installing a New License File

By default, JasperServer is installed with an evaluation license that expires a number of days after the software is installed. Once the license expires, you can start JasperServer, but you cannot log in. To obtain a commercial license, contact Technical Support or your sales representative. To upgrade the evaluation license to a commercial one, copy the commercial license file over the evaluation license file. By default, the license is found in the <js-install> directory. However, it can be located anywhere, so long as the Djs.license.directory Java Environment Variable points to its location (defined in the Tomcat startup scripts). Note that the name of the file should be jasperserver.license. Also, note that you may need to rename the new license file you receive. Restart JasperServer and login to test whether the license is granting access properly. For information about license errors, see section B.3, "License Not Found Error ", in the Troubleshooting Appendix B. For additional license configuration options, refer to section 5.12, "Setup JasperServer License".
2.2.4 License File for Tomcat as Windows Service

If you are installing JasperServer into an existing Tomcat installation on a Windows system that is running as a Windows Service, you may have to manually configure a Java option. If you are unable to login to JasperServer due to a missing license error, you should follow the steps below to examine and/or update the JasperServer license setting: 1. Open the Tomcat configuration tool by right-clicking the Tomcat icon in your quick-launch bar (usually in the lower-right corner of your desktop) or from the Windows menu at Start> All Programs> Apache Tomcat> Tomcat Configuration Click Configure and select the Java tab. At the bottom of the Java Options field, enter the following: -Djs.license.directory=<js-install> For example: -Djs.license.directory=C:\Program Files\jasperserver-pro-3.0 4. Stop and restart the application server.
2. 3.
You should now be able to run JasperServer.
2.2.5 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.13, "Set Java JVM Options". If you are running Java 1.6, there are pointers to additional information in this section.
15
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 Pro> JasperServer Management> Start JasperServer. Click Start> All Programs> JasperServer Pro > JasperServer management> Stop JasperServer. From Command Line: cd <js-install>/bin ./allclt.bat start [stop] cd <js-install> ./jasperctl.sh start [stop] (Linux) (Windows)
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 isnt, start it as described in the section above. Log into JasperServer by entering the correct URL in your browsers 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 Tomcat where:

URL http://<hostname>:8080/jasperserver-pro
<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 Pro> JasperServer.
16
JasperServer Professional Installation Guide If the login page appears, JasperServer has started properly. You may now login with the following username and password: Username: jasperadmin 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 Password: joeuser Username: demo 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). (special SuperMart Dashboard demonstration end-user) (sample standard end-user) (default administrative user)
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 Pro> 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-pro/WEB-INF/logs/jasperserver.log The log4j.properties file location is: <application-server-path>/jasperserver-pro/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.
17
4 Uninstalling JasperServer
In Windows, click Start > All Programs > JasperServer Pro > 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.
18
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 these configurations: Target Configuration Tomcat or JBoss with MySQL Tomcat or JBoss with Oracle Tomcat or JBoss with DB2 Tomcat or JBoss with Microsoft SQL Server Tomcat or JBoss with PostgreSQL WebSphere Application Server WebLogic Application Server Instructions Location This section This section This section This section This section Additional Section Additional 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-pro-<ver>-bin Unpack to a directory location such as: C:\jasperserver-pro-<ver>-bin /home/<user>/jasperserver-pro-<ver>-bin (Windows) (Linux)
19
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.
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; mysql>use jasperserver; mysql>source jasperserverCreate-mysql.ddl mysql>source jasperserverCreateDefaultSecurity-mysql.sql 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 MySQL database is now setup for use with JasperServer. (create schema) (populate minimal data) (reload privilege tables)
5.4.2 Oracle Database Setup Steps

The Oracle client software, sqlplus.exe or sqlplus, 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 Oracle instance may be different. These commands should be run from the Windows or Linux command line. Create and Populate the User/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 user and password.
20
JasperServer Professional Installation Guide In your Windows or Linux environment you should set the following variable so that it is used during the Oracle database create steps. This allows i18n internationalization to work properly: set NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1 export NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1 First move to the scripts/oracle directory: cd <unpacked-war-dir>/scripts/oracle Enter the following commands: sqlplus /nolog SQL> connect SYS/password@ORCL as SYSDBA SQL> create user jasperadmin identified by password; SQL> grant connect, resource, dba to jasperadmin; SQL>connect jasperadmin/password@ORCL SQL> @jasperserverCreate-oracle.ddl (use your password, your SID) (create schema) (start sqlplus client) (use your SYS password, your SID) - Windows - Linux
SQL> @jasperserverCreateDefaultSecurity-oracle.sql (populate minimal data) SQL>exit The Oracle database is now setup for use with JasperServer.
5.4.3 DB2 Database Setup Steps

The Db2 client software, db2.exe, 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 DB2 instance may be different. These commands should be run from the Windows or Linux command line. Create and Populate the User/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 user and password. First move to the scripts/db2 directory: cd <unpacked-war-dir>/scripts/db2 Enter the following commands in the DB2 Command Window: db2 create database jsprsrvr db2 -tf jasperserverCreate-db2.ddl db2 -tf jasperserverCreateDefaultSecurity-db2.sql The DB2 repository database is now setup for use with JasperServer. The repository will be in the jsprsrvr database in the jsprsrvr schema.
5.4.4 Microsoft SQL Server Database Setup Steps

The database setup steps for SQL Server are a bit different than for the other supported databases. In this procedure, there is a single, unified ant script that handles all aspects of the database setup and sample data load for installation with SQL Server. Set up Ant The SQL Server installation procedure uses the Ant utility to run the installation tasks; see Appendix C for details on how to set up Ant.
21
JasperServer Professional Installation Guide Set up base.properties file for SQL Server The database configuration parameters for SQL Server are found in the base.properties file. These properties are used for setting up the jasperserver database, for deploying the jasperserver war file to your application server, and for loading the the JasperServer sample data. In this section of the installation we will setup the jasperserver database, however, we will check and set all of the properties so that they can be used in later sections of the install process. The base.properties file is found at the following location: <unpacked-war-dir>/scripts/config/base.properties The properties that should match your SQL Server database instance (and application server instance) are the following:
dbServerType=sqlserver dbServerHost=localhost dbServerPort=1433 username=jasperadmin password=password jasperserverDbName=jasperserver sugarcrmDbName=sugarcrm foodmartDbName=foodmart (type of database) (host running the database) (port that database listens on) (username for jasperserver databases) (password for jasperserver databases) (name of db for Jasperserver metadata) (name of db for sugarcrm sample data) (name of db for foodmart/SuperMart sample data) (path for import sample data) (webapp path)
importCatalog=sqlserver/js-catalog-sqlserver
webappPath=C:/apache-tomcat/webapps/jasperserver-pro
Create and Populate JasperServer Database for SQL Server Use SQL Server Management Studio or another tool to create a SQL Server login to be used as the owner for the JasperServer databases, which matches the username value in your base.properties file. Create a database owned by this login, with a name matching the jasperserverDbName value. If you will be installing sample data, you should also create databases with names matching the foodmartDbName and sugarcrmDbName values (these will be used in a later section). To create the jasperserver database, do the following: In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant init-jasperserver-db In Linux or Unix: cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant init-jasperserver-db If the scripts succeed, the SQL Server database is now setup for use with JasperServer and you can move to the JasperServer war deployment section. If there is a failure, look at the error message and check for one of the following problems: The database hostname is incorrect, or the database is down or unreachable The database is not listening on the specified port, possibly because it is using dynamic ports The username and password in the configuration do not match a valid SQL Server username and password SQL Server is only set up for Windows authentication (It needs to have mixed-mode authentication enabled) The jasperserverDbName is not a valid database
22
JasperServer Professional Installation Guide The login specified by username doesnt own the jasperserverDbName database, or doesnt have sufficient permissions to run the scripts.
5.4.5 PostgreSQL Database Setups Steps

The PostgreSQL client software psql 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 PostgreSQL instance may be different. These commands should be run from the Windows or Linux command line. Create and Populate the Database First move to the scripts/postgresql directory: cd <unpacked-war-dir>/scripts/postgresql Start psql using an admin account (such as "postgres"): psql -U postgres Enter the following commands: create database jasperserver encoding='utf8'; \c jasperserver \i jasperserverCreate-postgresql.ddl; \i jasperserverCreateDefaultSecurity-postgresql.sql; \q The PostgreSQL database is now setup for use with JasperServer.
5.5 Deploy JasperServer War to the Application Server

5.5.1 Most Database Servers
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-pro.war To the following directory: <apache-tomcat>/webapps <jboss>/server/default/deploy (Tomcat) (JBoss)
5.5.2 Microsoft SQL Server

For a SQL Server installation, you will use Ant to run the deploy-webapp target, which uses the values you configured in the base.properties file in the previous section. First, verify in your <unpacked-war-dir>/scripts/config/base.properties that the value for the webappPath property is correct for your application server. In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant deploy-webapp In Linux or Unix:
23
JasperServer Professional Installation Guide cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant deploy-webapp This target automates the following configuration steps: Copying and unpacking the WAR to the application server directory Configuring the hibernate.properties file Configuring the Tomcat context.xml file
The following steps still have to be done manually (see following sections for information on these steps): Copying the JDBC driver to the application server directory Configuring the JBoss datasource file Set up JasperServer license
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 localhost jasperserver jasperdb password 3306 N/A
MySQLDialect
Default Config for Oracle localhost N/A jasperadmin password 1521 Orcl
OracleUnicodeDialect
Default Config for DB2 localhost jsprsrvr db2admin password 50000
Default Config for MS SQL Server localhost jasperserver jasperadmin password 1433 N/A
Default Config for PostgreSQL localhost jasperserver postgres postgres 5432 N/A
PostgreSQLDialect PostgreSQLDelegate
Database Host Database Name Database User Database Password Database Port Database SID Hibernate Dialect Quartz Driver Delegate
DB2SQLDialect
SQLServerDialect
StdJDBCDelegat e
StdJDBCDelegate
DB2v8Delegate
StdJDBCDelegat e
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-pro 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 cd <jboss>/server/default/deploy
24
(Tomcat) (JBoss)
JasperServer Professional Installation Guide mkdir jasperserver-pro cd jasperserver-pro jar xvf ../jasperserver-pro.war cd .. rm r jasperserver-pro.war or del jasperserver-pro.war JBoss mv jasperserver-pro jasperserver-pro.war copy jasperserver-pro jasperserver-pro.war (add .war to end of dir name) (same in Windows) (remove the original WAR file) (x - extract, v - verbose, f - is filename)
Note: For SQL Server the above setup should already be automatically handled by the deploy-webapp Ant target.
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-pro/WEB-INF/hibernate.properties <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/hibernate.properties Edit this file and set the dialect property to the appropriate value. MySQL metadata.hibernate.dialect=org.hibernate.dialect.MySQLDialect Oracle metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.OracleUnicodeDialect DB2 metadata.hibernate.dialect=org.hibernate.dialect.DB2Dialect Microsoft SQL Server This should already be automatically configured by the deploy-webapp Ant target. metadata.hibernate.dialect=org.hibernate.dialect.SQLServerDialect PostgreSQL metadata.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
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 <unpacked-war-dir>/scripts/drivers/ojdbc14.jar <unpacked-war-dir>/scripts/drivers/db2jcc.jar (MySQL) (Oracle) (DB2)
25
JasperServer Professional Installation Guide <unpacked-war-dir>/scripts/drivers/sqljdbc.jar <unpacked-war-dir>/scripts/drivers/postgresql-8.2-504.jdbc3.jar To your application server lib location: <apache-tomcat>/common/lib <apache-tomcat>/lib <jboss>/server/default/lib (Tomcat 5) (Tomcat 6) (JBoss) (SQL Server) (PostgreSQL)
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-pro/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-pro" 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&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.9.2 Oracle context.xml for Tomcat

You must update your Tomcat context.xml to configure it properly for Oracle. The <unpacked-war-dir>/scripts/oracle directory contains a file named context-oracle.xml that you can use. Rename "context-oracle.xml" to "context.xml" and copy it on top of the existing file in the JasperServer WAR file: Copy (and rename): <unpacked-war-dir>/scripts/oracle/context-oracle.xml To: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml Edit the context.xml, changing items in bold to match your settings:
password="password" url="jdbc:oracle:thin:@localhost:1521:orcl"
26
5.9.3 DB2 Conext.xml for Tomcat

You must update your Tomcat context.xml to configure it properly for DB2. The <unpacked-war-dir>/scripts/db2 directory contains a file named context-db2.xml that you can use. Rename "context-db2.xml" to "context.xml" and copy it on top of the existing file in the JasperServer WAR file: Copy (and rename): <unpacked-war-dir>/scripts/oracle/context-db2.xml To: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml Edit the context.xml, changing items in bold to match your settings:
password="password" url=" jdbc:db2://localhost:50000/jsprsrvr:driverType=4;fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;progressiveStreaming=2;progresssive Locators=2;currentSchema=JSPRSRVR;"
5.9.4 Microsoft SQL Server context.xml for Tomcat

The context.xml should already be automatically configured by the deploy-webapp Ant target run in an earlier section. You can validate your SQL Server settings by checking the following file: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml If there were any problems with your settings, you can manually update using the following steps. The <unpacked-war-dir>/scripts/sqlserver directory contains a file named context-sqlserver.xml. Rename "contextsqlserver.xml" to "context.xml" and copy it on top of the existing file in the JasperServer WAR file: Copy (and rename): <unpacked-war-dir>/scripts/sqlserver/context-sqlserver.xml To: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml Edit the context.xml, changing items in bold to match your settings:
password="password" url=" jdbc:sqlserver://localhost:1433;databaseName=jasperserver;SelectMethod=cursor " url=" jdbc:sqlserver://localhost:1433;databaseName=sugarcrm;SelectMethod=cursor " url=" jdbc:sqlserver://localhost:1433;databaseName=foodmart;SelectMethod=cursor "
5.9.5 PostgreSQL context.xml for Tomcat

You must update your Tomcat context.xml to configure it properly for PostgreSQL. The <unpacked-war-dir>/scripts/postgresql directory contains a file named context- postgresql.xml that you can use. Rename "context- postgresql.xml" to "context.xml" and copy it on top of the existing file in the JasperServer WAR file: Copy (and rename): <unpacked-war-dir>/scripts/ postgresql /context- postgresql.xml To: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml Edit the context.xml, changing items in bold to match your settings:
.username="postgres" password="postgres"
27

url="jdbc:postgresql://localhost:5432/jasperserver" url="jdbc:postgresql://localhost:5432/foodmart" url="jdbc:postgresql://localhost:5432/sugarcrm"
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.
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&characterEncoding=UTF-8</connection-url> <connection-url>jdbc:mysql://localhost:3306/sugarcrm?useUnicode=true&characterEncoding=UTF-8</connection-url> <connection-url>jdbc:mysql://localhost:3306/foodmart?useUnicode=true&characterEncoding=UTF-8</connection-url> <user-name>jasperdb</user-name> <password>password</password>
5.10.2 Oracle Datasource for JBoss

The <unpacked-war-dir>/scripts/jboss directory contains a sample js-oracle-ds.xml file. This datasource 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 correct values:
.<connection-url>jdbc:oracle:thin:@localhost:1521:orcl</connection-url> .<user-name>jasperadmin</user-name> .<password>password</password> .<user-name>sugarcrm</user-name> .<password>password</password> .<user-name>foodmart</user-name> .<password>password</password>
5.10.3 DB2 Datasource for JBoss

The <unpacked-war-dir>/scripts/jboss directory contains a sample js-db2-ds.xml file. This datasource 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 correct values:
28

<user-name>db2admin</user-name> <password>password</password> <connection-url> jdbc:db2://localhost:50000/jsprsrvr:driverType=4;fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;progressiveStreami ng=2;progresssiveLocators=2;currentSchema=JSPRSRVR;</connection-url>
In the same file, check the settings for the SugarCRM and Foodmart databases.
5.10.4 Microsoft SQL Server Datasource for JBoss

The <unpacked-war-dir>/scripts/jboss directory contains a sample js-sqlserver-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 correct values:
<connection-url>jdbc:sqlserver://localhost:1433;databaseName=jasperserver;SelectMethod=cursor</connection-url> <connection-url>jdbc:sqlserver://localhost:1433;databaseName=sugarcrm;SelectMethod=cursor</connection-url> <connection-url>jdbc:sqlserver://localhost:1433;databaseName=foodmart;SelectMethod=cursor</connection-url> <password>password</password>
5.10.5 PostgreSQL Datasource for JBoss

The <unpacked-war-dir>/scripts/jboss directory contains a sample js-postgresql-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:postgresql://localhost:5432/jasperserver</connection-url> <connection-url>jdbc:postgresql://localhost:5432/sugarcrm</connection-url> <connection-url>jdbc:postgresql://localhost:5432/foodmart</connection-url> <user-name>postgres</user-name> <password>postgres</password>
Note: The PostgreSQL driver needs a special configuration when running under JBoss. Refer to section B.11, "JBoss Modifications", in the Troubleshooting Appendix B for more information.
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.11 "JBoss Modifications" in the Troubleshooting Appendix B for more information.
5.12 Setup JasperServer License

JasperServer Professional needs a license to run. The JasperServer War Distribution comes with an evaluation license that is valid for a number of days after JasperServer is first started. Contact Technical Support or your sales representative to get your commercial license.
29
JasperServer Professional Installation Guide You must modify your application server java startup options to point to your license file. The JasperServer license file is in the following location: <unpacked-war-dir>/jasperserver.license
Setup JasperServer License for Tomcat: Tomcat file Locate this line Add this line below (Windows) Example (Windows) Add this line below (Linux) Example (Linux) <tomcat>/bin/setclasspath.bat or setclasspath.sh
JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed (Windows) (Linux)
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="<unpacked-war-dir>"
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-pro-bin" JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=<unpacked-war-dir>" JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-pro-bin"
Alternate Configuration for Tomcat: Create file Add JAVA_OPTS setting example (Windows) Add JAVA_OPTS setting example (Linux)
<tomcat>/bin/setenv.bat or setenv.sh set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-pro-bin"
JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-pro-bin"
Setup JasperServer License for JBoss: JBoss file Locate this line Add this line below (Windows) Example (Windows) Add this line below (Linux) Example (Linux) <jboss>/bin/run.bat or run.sh
set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME" set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="<unpacked-war-dir>" (Windows) (Linux)
set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-pro-bin" JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=<unpacked-war-dir>" JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-pro-bin"
Alternate License Configuration All Application Servers: Copy the file <unpacked-war-dir>/jasperserver.license to the home directory of the user that runs your application server. Copy license file from Copy license file to (Windows) Copy license file to (Linux) <unpacked-war-dir>/jasperserver.license C:\Documents and Settings\<user>\jasperserver.license /home/<user>/jasperserver.license
30
5.13 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 tables layout recommended settings for Java 1.5, and a localization setting that applies to Oracle only. 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 JBoss file JAVA_OPTS setting (Windows) JAVA_OPTS setting (Linux)
<tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh) <jboss>/bin/run.bat or run.sh
set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m set JAVA_OPTS=%JAVA_OPTS% -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled XX:+CMSPermGenSweepingEnabled JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m " 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. Additional Settings for Oracle Localization In order to support Localization when running JasperServer with an Oracle database there is an additional java option that should be set. Additional Java Setting for Localization of Oracle Only: Tomcat file JBoss file JAVA_OPTS setting (Windows) JAVA_OPTS setting (Linux)
<tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh) <jboss>/bin/run.bat or run.sh set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true JAVA_OPTS="$JAVA_OPTS -Doracle.jdbc.defaultNChar=true "
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.
5.13.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.11.2, "JBoss 4.2 XMLA Connection Fix", in TroubleShooting Appendix B.
31
5.14 Start JasperServer

To run JasperServer start your application server. Start the JasperServer application: <apache-tomcat>/bin/startup.bat <jboss>/bin/run.bat or run.sh or startup.sh (Tomcat) (JBoss)
The JasperServer log output goes to the following location: <apache-tomcat>/webapps/jasperserver-pro/WEB-INF/logs/jasperserver.log <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/logs/jasperserver.log (Tomcat) (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-pro/WEB-INF/ log4j.properties <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/ log4j.properties The application server console log should also be checked for errors. (Tomcat) (JBoss)
5.15 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-pro Example: http://localhost:8080/jasperserver-pro http://my.server.com:8080/jasperserver-pro 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 Professional 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.
5.15.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:
32
Operating System - type and version JVM - type and version Application Server - type and version Database - type and version JasperServer - type and version
JasperServer Professional Installation Guide Unique, anonymous identifier value You can also manually enable or disable the heartbeat by modifying the jasperserver-pro/WEB-INF/applicationContextlogging.xml file. For additional information on enabling and disabling the heartbeat component refer to the JasperServer Professional Administrator Guide.
5.16 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.16.1 MySQL Sample Database Create and Populate

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

First set the NLS_LANG variable that Oracle should use: set NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1 export NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1 Then run the following commands: cd <unpacked-war-dir>/scripts/oracle sqlplus /nolog SQL> connect SYS/password@ORCL as SYSDBA SQL> create user sugarcrm identified by password; SQL> create user foodmart identified by password; SQL> grant connect, resource, dba to sugarcrm; SQL> grant connect, resource, dba to foodmart; SQL>connect sugarcrm/password@ ORCL SQL>@sugarcrm-oracle.sql SQL>connect foodmart/password@ ORCL SQL>@foodmart-oracle.sql SQL>exit (start sqlplus client) (use your SYS password, your SID) (Windows) (Linux)
(use your password, your SID) (this runs for 5 minutes or so) (use your password, your SID) (this runs for 15 minutes or so)
33
5.16.3 DB2 Sample Database Create and Populate

cd <unpacked-war-dir>/scripts/db2 Unzip the sugarcrm-db2 and the foodmart-db2.zip archives. Use the DB2 Command Line Processor: db2 create database sugarcrm db2 < sugarcrm-db2.sql db2 create database foodmart db2 < foodmart-db2.sql
5.16.4 Microsoft SQL Server Sample Database Create and Populate

If you haven't already, use SQL Server Management Studio or another tool to create the foodmart and sugarcrm databases. The database names should match the settings for foodmartDbName and sugarcrmDbName found in the <unpacked-wardir>/scripts/config/base.properties file. To populate the foodmart and sugarcrm sample databases, run the following Ant targets: In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant load-foodmart %ANT_HOME%\bin\ant load-sugarcrm In Linux or Unix: cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant load-foodmart $ANT_HOME/bin/ant load-sugarcrm
5.16.5 PostgreSQL Sample Database Create and Populate

cd <unpacked-war-dir>/scripts/postgresql First unzip the two database creation scripts for foodmart and sugarcrm: Unzip sugarcrm-postgresql.zip Unzip foodmart-postgresql.zip Create the databases: psql U postgres create database sugarcrm; create database foodmart; \c sugarcrm \i sugarcrm-postgresql.sql \c foodmart \i foodmart-postgresql.sql \q (login to PostgreSQL client)
5.16.6 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.
34
JasperServer Professional Installation Guide 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.
5.17 Import the JasperServer Sample Metadata

5.17.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 datasources. The database that is updated is the jasperserver 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. For a SQL Server installation, this configuration is done automatically from the scripts/config/base.properties file. For other databases, 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". Oracle Settings Refer to Appendix A, "Configuring the Import-Export Utility", section A.3, "Sample Settings for Oracle". DB2 Settings Refer to Appendix A, "Configuring the Import-Export Utility", section A.3, "Sample Settings for DB2". Microsoft SQL Server Settings For SQL Server the import is handled with an Ant task. See section 5.16.3 "Microsoft SQL Server Run Import Utility". PostgreSQL Settings Refer to Appendix A, "Configuring the Import-Export Utility", section A.3, "Sample Settings for PostgreSQL".
5.17.2 Run the Import Utility

To run the import utility, enter the following command: MySQL cd <unpacked-war-dir>/scripts js-import.bat --input-dir js-catalog js-import.sh --input-dir js-catalog Oracle cd <unpacked-war-dir>/scripts js-import.bat --input-dir oracle/js-catalog-oracle js-import.sh --input-dir oracle/js-catalog-oracle DB2 cd <unpacked-war-dir>/scripts
35
(Windows) (Linux)
(Windows) (Linux)
JasperServer Professional Installation Guide js-import.bat --input-dir db2/js-catalog-db2 js-import.sh --input-dir db2/js-catalog-db2 Microsoft SQL Server For SQL Server the import is handled with an Ant task. See section 5.17.3 "Microsoft SQL Server Run Import Utility". (Windows) (Linux)
PostgreSQL cd <unpacked-war-dir>/scripts js-import.bat --input-dir postgresql/js-catalog-postgresql js-import.sh --input-dir postgresql/js-catalog-postgresql 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. (Windows) (Linux)
5.17.3 Microsoft SQL Server Run Import Utility

To populate the JasperServer sample metadata into the jasperserver database, you will run the Ant target run-import. In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant run-import In Linux or Unix: cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant run-import
5.18 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 are the configuration files used for Report Scheduling: js.quartz.properties js.mail.properties js.scheduler.properties
5.18.1 js.quartz.properties
The Quartz properties file is found at the following location: <apache-tomcat>/webapps/jasperserver-pro/WEB-INF/js.quartz.properties <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/js.quartz.properties PostgreSQL (Non-Optional) PostgreSQL has a non-default setting for the Quartz driver delegate class. It be set to the following: org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate A sample Quartz properties file can be copied to your deployed JasperServer from the following location: <unpacked-war-dir>/scripts/postgresql/js.quartz-postgresql.properties
36
JasperServer Professional Installation Guide Be sure to change the name of this file to js.quartz.properties. DB2 (Non-Optional) DB2 has a non-default setting for the Quartz driver delegate class: org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.DB2v8Delegate If you have installed the JasperServer repository into a non-standard schema, you will need to set the additional property (ie if not the default schema): org.quartz.jobStore.tablePrefix=<your schema>.QRTZ_ A sample Quartz properties file can be copied to your deployed JasperServer from the following location: <unpacked-war-dir>/scripts/db2/js.quartz-db2.properties Be sure to change the name of this file to js.quartz.properties. All Other Databases The default Quartz driver delegate setting found in the JasperServer war file is appropriate for all other certified (nonPostgreSQL) databases. It will look like the following: org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate Note: For more information on the Quartz Framework, see the quartz website: http://www.opensymphony.com/quartz
5.18.2 js.mail.properties
The mail server configuration file is found at the following location: <apache-tomcat>/webapps/jasperserver-pro/WEB-INF/js.mail.properties <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/js.mail.properties
5.18.3 js.schedular.properties
The web link URL configuration file is found at the following location: <apache-tomcat>/webapps/jasperserver-pro/WEB-INF/js.scheduling.properties <jboss>/server/default/deploy/jasperserver-pro/WEB-INF/js.scheduling.properties
5.18.4 More Information on Report Scheduling Configuration

Refer to the Mail Server Configuration section of the JasperServer Professional Administrator Guide for complete information on report scheduling configuration options.
5.19 Restart JasperServer

If you have made configuration changes to your JasperServer instance, you should restart JasperServer
5.20 Update XMLA Connection Definitions (Optional)

If you have JasperAnalysis enabled (via your license), 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.
37
JasperServer Professional Installation Guide If you would like to run the samples that uses 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 o o URI (hostname and port) Login Username Login Password
Click Next, then Save. Make the same updates for the SugarCRM XMLA Connection resource.
5.21 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 B5, "Error Running a Report" in the Troubleshooting Appendix B.
38
6 Install Using War File Distribution for WebSphere Application Server

6.1 Introduction
JasperServer supports deployment on the IBM WebSphere Application Server. Deployment is performed by the WebSphere administrator using the WebSphere Administrative Console. The deployment process contains the following steps: Obtain the War File Distribution Zip Unpack the War File Distribution Zip Setup the JasperServer Database Configure Database connections Setup JasperServer License Deploy the WAR to the WebSphere Application Server

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

Once you have downloaded the WAR file distribution, you must 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-pro-<ver>-bin Unpack to a directory location such as: C:\jasperserver-pro-<ver>-bin /home/<user>/jasperserver-pro-<ver>-bin (Windows) (Linux)

To setup the JasperServer database, refer to section 5.4, "Setup the JasperServer Database". Look for the steps that describe the setup for your specific database.
6.5 Configure Database Connections

By default, the database configuration files included with the JasperServer War file distribution are set to connect to a database with the following settings:
39
JasperServer Professional Installation Guide Setting Database Host Database Name Database User Database Password Database Port Database SID Hibernate Dialect Default Config for MySQL localhost jasperserver jasperdb password 3306 N/A MySQLDialect Default Config for Oracle localhost N/A jasperadmin password 1521 Orcl OracleDialect Default Config for MS SQL Server localhost jasperserver jasperadmin password 1433 N/A SQLServerDialect Default Config for PostgreSQL localhost jasperserver postgres postgres 5432 N/A PostgreSQLDialect
You must configure JDBC Provider and Database Connections for your WebSphere Application Server.
6.5.2 Configuring JDBC Provider

In Administrative Console window, navigate to Resources JDBC JDBC Providers. Click New button to create a new JDBC Provider. You must enter the following parameter values: Parameter Name Database Type Implementation class name Name Connector jar file path Example Value User-defined com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource MySQL JDBC Provider C:\jdbc\mysql-connector-java-<ver>-bin.jar (3.1.14 or greater)
Save Master Configuration. Note: The MySQL JDBC driver must be version number 3.1.14 (or greater).
6.5.3 Configuring Database User

In the Administrative Console window, navigate to Security Secure administration, application and infrastructure. Click J2C authentication data link. Create new user and enter user alias, connection user name and password. Save Master Configuration.
6.5.4 Configuring JDBC Data Sources

In the Administrative Console, navigate to Resources JDBC Data Sources. Click New button to create a new JDBC Data Source. You must enter the following parameter values:
Parameter Name Data source name JNDI name Component-managed authentication alias Existing JDBC Provider
Example Value jasperserver jdbc/jasperserver <database user alias> MySQL JDBC Provider
40
JasperServer Professional Installation Guide Go back to the JDBC Data Sources list and click jasperserver link. Find Additional Properties section and click Custom Properties link. Click New button and filter properties by Name=url. Click url property and enter the connection url (example: jdbc:mysql://localhost/jasperserver?useUnicode=true&characterEncoding=UTF-8). Go back to the JDBC Data Sources list and test the connection using Test button. Create sugarcrm and foodmart database connections if you are planning to run JasperServer Sample Reports. Save Master Configuration.
6.5.5 Check the Hibernate Properties Configuration

To check the hibernate properties configuration refer to section 5.7, "Configure Hibernate Properties File".
6.6 Setup JasperServer License

JasperServer Professional needs a license to run. The JasperServer War Distribution comes with an evaluation license that is valid for a number of days. Contact Technical Support or your sales representative to get your commercial license. You must put your license file into a home folder of a user account being used to start WebSphere Application Server. Note: this account may differ from the logged user account. For example, if WebSphere is running on Windows Server as a service, system account is used to start the WebSphere, and home folder would be: %SystemRoot%\system32\config\systemprofile The JasperServer license file is in the following location: <unpacked-war-dir>/jasperserver.license
6.7 Deploy the JasperServer War to the Application Server

In the Administrative Console, navigate to Applications Install New Application. Enter the following parameter values: Parameter Name Path to the new application Full path Context root Example Value Local File System <full path to the .WAR file> jasperserver-pro
Map all resource references to the target JNDI names. After the application is successfully installed, save master configuration.
6.8 Set Java JVM Options

In order for the JasperServer analysis XMLA functionality to work, special Java JVM options need to be set. This is because both WebSphere and JasperServer provide a full web services implementation and there are class conflicts between the two. To configure your Java JVM options, navigate to Servers - Application Servers - Java Virtual Machine. Move down to the text box named Generic JVM Options. In this text box, you should paste in the following JVM options that will explicitly specify JasperServer classes for AXIS and Xalan:
Option Target
Value
41
JasperServer Professional Installation Guide 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 "
Note: You can cut and paste these settings from the java-settings-websphere.txt in the <unpacked-war-dir>/scripts/javasettings directory.

In the Administrative Console, navigate to Applications Enterprise Applications. Mark jasperserver-pro application with a checkmark, and click Start button to start the application.

If JasperServer started up cleanly you should be able to login. Login by going to the following URL: http://<hostname>:9080/jasperserver-pro Example: http://localhost:9080/jasperserver-pro The login page should appear (after some time to compile the necessary .jsp files). Use the following ID to login to the system: Username: jasperadmin (Administrative user) Password: jasperadmin If you logged in successfully, the JasperServer home page appears. Refer to the JasperServer Professional User Guide to begin adding reports and other objects to JasperServer. Note: The first time you login to JasperServer 3.0, you will be prompted to opt-in or opt-out to the JasperServer Heartbeat. Refer to Section 5.15.1, "JasperServer Heartbeat", for more information. Note: If you have trouble logging in and get a "Page cannot be found, HTTP 404" error, you may be running at a WebSphere patch level that needs a further configuration. Refer to section B.12, "WebSphere: "Page Not Found" Error on Login", in the Troubleshooting Appendix B.
6.11 Setup Sample Data

To setup the JasperServer sample data refer to section 5.16, "Setup and Load Sample Data". Follow the steps described in sub-sections for your database product.
6.12 Report Scheduling Configuration (Optional)

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.
42
JasperServer Professional Installation Guide Refer to Section 5.18, "Report Scheduling Configuration", for more information report scheduling setup. Note: for the PostgreSQL database, there is a non-optional configuration step.


If you have loaded the JasperServer sample data, and you would like to run the Analysis XMLA examples, you will need to update the XMLA connection resources to use the correct web port. The typical port used by Websphere is: 8090. To make this update refer to section 5.20, "Update XMLA Connection Definitions", above.

Startup Problems When trying to run a newly setup JasperServer instance, the most typical problems encounted are errors in the 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 B5, "Error Running a Report" in the Troubleshooting Appendix B. Filter Error If you encounter the following error: Error 500: Filter [characterEncodingProxyFilter]: cold not be initialized it could be caused by an incorrect ampersand setting on your data source configuration. The data source line needs to have & and not & in order to be evaluated correctly. The line from section 6.5.4, "Configuring JDBC Data Sources", should look like the following: jdbc:mysql://localhost/jasperserver?useUnicode=true&characterEncoding=UTF-8 Note the ampersand string is "&" and not "&".
43
7 Install Using War File Distribution for WebLogic Application Server

7.1 Introduction
JasperServer supports deployment on the WebLogic Application Server. Deployment is performed by the WebLogic administrator using the WebLogic Administrative Console or domain config.xml.

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

Once you have downloaded the WAR file distribution, you must unpack it in order to access the contained files. Unpack to a directory location such as: C:\jasperserver-pro /home/<user>/jasperserver-pro (Windows) (Linux)

To setup the JasperServer database, refer to section 5.4, "Setup the JasperServer Database". Look for the steps that describe the setup for your specific database.
7.5 Configure Database Connections

By default, the database configuration files included with the JasperServer War file distribution are set to connect to a database with the following settings:
44
Setting Database Host Database Name Database User Database Password Database Port Database SID Hibernate Dialect
Default Config for MySQL localhost jasperserver jasperdb password 3306 N/A MySQLDialect
Default Config for Oracle localhost N/A jasperadmin password 1521 Orcl OracleDialect
Default Config for MS SQL Server localhost jasperserver jasperadmin password 1433 N/A SQLServerDialect
Default Config for PostgreSQL localhost jasperserver postgres postgres 5432 N/A PostgreSQLDialect
You must configure JDBC Provider and Database Connections for your WebLogic Application Server.
7.5.2 Configuring Data Sources

In Administrative Console window, navigate to JDBC Data Sources. Click New button to create a new Data Sources. You must enter the following parameter values:
Parameter Name Name JNDI Name Database Type Database Driver Supports Global Transactions One-Phase Commit
Example Value JasperServerDataBase JasperServerDataBase MySQL MySQLs Driver (Type 4) Versions:using com.mysql.jdbc.Driver Checked Checked
Parameter Name Name JNDI Name Database Type Database Driver Supports Global Transactions One-Phase Commit
Example Value FoodmartDataBase FoodmartDataBase MySQL MySQLs Driver (Type 4) Versions:using com.mysql.jdbc.Driver Checked Checked
Parameter Name Name JNDI Name
Example Value SugarcrmDataBase SugarcrmDataBase

45
JasperServer Professional Installation Guide Database Type Database Driver Supports Global Transactions One-Phase Commit MySQL MySQLs Driver (Type 4) Versions:using com.mysql.jdbc.Driver Checked Checked
7.5.3 Connection Properties

Parameter Name Database Name Host Name Port Database User Name Password Confirm Password Example Value jasperserver localhost 3306 jasperdb password password
Parameter Name Database Name Host Name Port Database User Name Password Confirm Password
Example Value foodmart Localhost 3306 jasperdb password password
Parameter Name Database Name Host Name Port Database User Name Password Confirm Password
Example Value sugarcrm localhost 3306 jasperdb password password
7.5.4 Test Database Connection

In the Test Database Connection page, you should check the Data Base URL. For SugarCRM and Foodmart it should be correct by default:
46
JasperServer Professional Installation Guide jdbc:mysql://localhost:3306/sugarcrm jdbc:mysql://localhost:3306/foodmart. The URL for JasperServer Data Base should be change to jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&characterEncoding=UTF-8
7.5.5 Select Targets

All data sources should be checked AdminServer.
7.5.6 Check the Hibernate Properties Configuration

To check the hibernate properties configuration refer to section 5.7, "Configure Hibernate Properties File".
7.6 Prepare WebLogic Environment

Modify startWebLogic Script The following lines should be added to your startWebLogic script file: Add to startWebLogic.bat (Windows)
set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0 set JAVA_OPTIONS=%JAVA_OPTIONS% -Djs.license.directory=C:\Jasrepserver-pro\ set JAVA_OPTIONS=%JAVA_OPTIONS% -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl set JAVA_OPTIONS=%JAVA_OPTIONS% -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl set JAVA_OPTIONS=%JAVA_OPTIONS% -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl set JAVA_OPTIONS=%JAVA_OPTIONS% -Dfile.encoding=UTF-8
Add to startWebLogic.sh (Linux)

JAVA_OPTIONS="${JAVA_OPTIONS} -Dfile.encoding=UTF-8" JAVA_OPTIONS="${JAVA_OPTIONS} -Djs.license.directory=/home/qauser/for_test_weblogic/jasperlicense/" JAVA_OPTIONS="${JAVA_OPTIONS} -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0" JAVA_OPTIONS="${JAVA_OPTIONS} -Djavax.xml.soap.SOAPConnectionFactory=weblogic.wsee.saaj.SOAPConnectionFactoryImpl" JAVA_OPTIONS="${JAVA_OPTIONS} -Djavax.xml.soap.MessageFactory=weblogic.xml.saaj.MessageFactoryImpl" JAVA_OPTIONS="${JAVA_OPTIONS} -Djavax.xml.soap.SOAPFactory=weblogic.xml.saaj.SOAPFactoryImpl"
Modify setDomainEnv Script The following line should be added to your setDomainEnv file: Add to setDomainEnv.bat (Windows)
set PRE_CLASSPATH=%DOMAIN_HOME%/lib/js-1.6R5.jar;%DOMAIN_HOME%/lib/xalan-2.4.1.jar;%DOMAIN_HOME%/lib/xercesImpl-2.6.2.jar; %DOMAIN_HOME%/lib/dom4j-1.6.1.jar;%DOMAIN_HOME%/lib/jdom-1.0.jar;%DOMAIN_HOME%/lib/xom-1.0.jar;
Add to setDomainEnv.sh (Linux)

PRE_CLASSPATH=${DOMAIN_HOME}/lib/js-1.6R5.jar:${DOMAIN_HOME}/lib/xalan-2.4.1.jar:${DOMAIN_HOME}/lib/xercesImpl2.6.2.jar:${DOMAIN_HOME}/lib/jstl-1.1.2.jar
47
7.7 Prepare Domain Library

The following files should be copied from jasperserver-pro/web-inf/lib to the WebLogic domain lib folder.
Copy from: jasperserver-pro/WEB-INF/lib To: the WebLogic domain lib folder dom4j-1.6.1.jar jaxen-1.1.1.jar jdom-1.0.jar js-1.6R5.jar mysql-connector-java-<ver>-bin.jar xalan-2.4.1.jar xercesImpl-2.6.2.jar xom-1.0.jar
7.8 Deploy JasperServer to the Application Server

In the Administrative Console, click the Lock & Edit button and navigate to Deployments. On this page click the Install button. Select path to the project unpacked files.
Parameter Name Name Security Source accessibility
Example Value jasperserver-pro Custom Roles and Policies Use the defaults defined by the deployment's targets

In the Administrative Console, navigate to Deployments. Mark the jasperserver-pro application with a checkmark, and click Start button to start the application. In the Start Application Assistant page, click Yes.

If JasperServer started up cleanly you should be able to login. Login by going to the following URL: http://<hostname>:7001/jasperserver-pro Example: http://localhost:7001/jasperserver-pro The login page should appear (after some time to compile the necessary .jsp files). Use the following ID to login to the system: Username: jasperadmin
48
(Administrative user)
JasperServer Professional Installation Guide Password: jasperadmin If you logged in successfully, the JasperServer home page appears. Refer to the JasperServer User Guide to begin adding reports and other objects to JasperServer. Note: The first time you login to JasperServer 3.0, you will be prompted to opt-in or opt-out to the JasperServer Heartbeat. Refer to Section 5.15.1, "JasperServer Heartbeat", for more information.
7.11 Setup Sample Data

To setup the JasperServer sample data refer to section 5.16, "Setup and Load Sample Data". Follow the steps described in sub-sections for your database product.
7.12 Report Scheduling Configuration (Optional)

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. Refer to Section 5.18, "Report Scheduling Configuration", for more information report scheduling setup. Note: for the PostgreSQL database, there is a non-optional configuration step.


If you have loaded the JasperServer sample data, and you would like to run the Analysis XMLA examples, you will need to update the XMLA connection resources to use the correct web port. The typical port used by WebLogic is: 7001 To make this update refer to section 5.20, "Update XMLA Connection Definitions", above.

Startup Problems When trying to run a newly setup JasperServer instance, the most typical problems encounted are errors in the 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 B5, "Error Running a Report" in the Troubleshooting Appendix B.
49
8 Upgrade from JasperServer 2.1 to JasperServer 3.0

This is the section to use if you have an existing JasperServer 2.1 application and you want to upgrade to JasperServer 3.0. This procedure describes the exact steps to carry out this upgrade under a Tomcat application server and a MySQL database configuration. There are additional steps described for the Oracle and SQL Server databases. The intention is that the same steps can be applied to other combinations of application servers and databases - the upgrade script names vary slightly depending on the database.
8.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.
8.1.1 Backup the JasperServer War Archive

Backup the jasperserver-pro directory in Tomcat to a backup directory: cd <apache-tomcat> mkdir js-2.1-war-backup copy <apache-tomcat>/webapps/ jasperserver-pro to <apache-tomcat>/js-2.1-war-backup delete directory <apache-tomcat>/webapps/jasperserver-pro
8.1.2 Backup the JasperServer Database

MySQL cd <unpacked-war-dir-2.1> Windows mysqldump --user=jasperadmin --password=<your-password> jasperserver > js-db-2.1-dump.sql Linux mysqldump --user=jasperadmin --password=< your-password > --host=127.0.0.1 jasperserver > js-db-2.1-dump.sql You can use the jasperadmin user or the root user to carry out this operation. Refer to section 8.8.1, "Using mysqldump for Database Backup", for more information on running the mysqldump command. 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". Oracle For Oracle, you should consult your Oracle Administrator documentation for backing up a database. (i.e., the location of your original unpacked 2.1 WAR file distribution)
8.2 Unpack JasperServer 3.0 War File Distribution

It is assumed that you have already obtained the jasperserver-pro-3.0-bin.zip distribution. Unpack the distribution to a directory on disk. This creates the location: <unpacked-war-dir-3.0>
50
8.3 Upgrade the JasperServer War

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

Deploy the WAR file: copy <unpacked-war-dir-3.0>/jasperserver-pro.war to <apache-tomcat>/webapps
8.3.2 Expand the Archived War File

The jasperserver-pro.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-pro.war.
8.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 2.1 war to your 3.0 war. Copy from <apache-tomcat>/js-2.1-war-backup>/jasperserver-pro to <apache-tomcat>/webapps/jasperserver-pro: META-INF/context.xml WEB-INF/hibernate.properties WEB-INF/js.mail.properties WEB-INF/js.scheduler.properties Also, copy or integrate any other custom modifications you have made to your JasperServer 2.1 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.
8.4 Upgrade the JasperServer Database

The jasperserver database is upgraded in place by running a SQL script.
8.4.1 MySQL
cd <unpacked-war-dir-3.0>/scripts/upgrade Login to your mysql client: mysql -u root -p Run the upgrade scripts: mysql>use jasperserver; mysql>source upgrade-mysql-2.1.0-3.0.0.sql;
8.4.2 Oracle
cd <unpacked-war-dir-3.0>/scripts/upgrade Login to you sqlplus client then do the following:
51
JasperServer Professional Installation Guide SQL>connect jasperadmin/password@ORCL SQL>@upgrade-oracle-2.1.0-3.0.0.sql SQL>@upgrade-oracle-3.0.0-3.0.1.sql (if you have the 3.0.1 War File Dist)
8.4.3 SQL Server

Use the Ant target update-jasperserver-db-3.0 to run the update script. In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant update-jasperserver-db-3.0 In Linux or Unix: cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant update-jasperserver-db-3.0
8.5 Start JasperServer 3.0

Before you actually start Tomcat with the new 3.0 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: cd <apache-tomcat>/work Remove all files below "work" directory Now you may start Tomcat. The MySQL database should already be running.
8.6 Login to JasperServer 3.0

If Tomcat and JasperServer Pro 3.0 were started correctly, you should be able to login. Login using the following URL, username and password: http://localhost:8080/jasperserver-pro username: password: jasperadmin <your-password>
Your JasperServer instance has now been upgraded to 3.0. 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.0, you will be prompted to opt-in or opt-out to the JasperServer Heartbeat. Refer to Section 5.15.1, "JasperServer Heartbeat", for more information. Note: If you update your sample data in the sections below, your jasperadmin password might be updated to "jasperadmin".
8.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.
52
8.7.1 Upgrade Sample Databases (if necessary)

MySQL The sample databases for MySQL, sugarcrm and foodmart, are unchanged between 2.1 and 3.0. Oracle For Oracle, there have been significant changes to the sample databases: sugarcrm and foodmart. These databases have been changed from explicit lowercase to default uppercase. Therefore, these two databases should be dropped and recreated. cd <unpacked-war-dir-3.0>/scripts/oracle Login to you sqlplus client then do the following: SQL> drop user sugarcrm cascade; SQL> create user sugarcrm identified by password; SQL> grant connect, resource, dba to sugarcrm; SQL> connect sugarcrm/password@ORCL SQL> @sugarcrm-oracle.sql; (this runs for 5 minutes or so)
SQL> drop user foodmart cascade; SQL> create user foodmart identified by password; SQL> grant connect, resource, dba to foodmart; SQL> connect foodmart/password@ORCL SQL> @foodmart-oracle.sql; SQL Server Use the Ant target update-foodmart to run the update script. In Windows: cd <unpacked-war-dir>\scripts %ANT_HOME%\bin\ant update-foodmart In Linux or Unix: cd <unpacked-war-dir>/scripts $ANT_HOME/bin/ant update-foodmart (this runs for 15 minutes or so)
8.7.2 Configure and Run Import of Sample Data

In JasperServer 3.0, the import operation has a new "update" capability. This update capability will be used when the sample data is updated for 3.0. All Database Applications 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 your particular database configuration, refer to section 5.17.1, "Prepare for Running the Import Utility". Once your configuration is complete, you can run the commands below. MySQL
53
JasperServer Professional Installation Guide cd <unpacked-war-dir-3.0>/scripts js-import.bat --input-dir js-catalog --update js-import.sh --input-dir js-catalog --update Oracle cd <unpacked-war-dir-3.0>/scripts js-import.bat --input-dir oracle/js-catalog-oracle --update js-import.sh --input-dir oracle/js-catalog-oracle --update (Windows) (Linux) (Windows) (Linux)
Additionally, refer to Appendix A, "Configuring the Import-Export Utility", for information on running the import utility.
8.8 Additional Notes on JasperServer Upgrade

8.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=jasperadmin --password=<your-password> jasperserver > js-db-3.0-dump.sql The following command performs the same task on a Linux system: mysqldump --user=jasperadmin --password=<your-password> --host=127.0.0.1 jasperserver > js-db-3.0-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
1
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".
8.8.2 Additional Configuration Files

If you made modifications or customizations to your JasperServer Pro 2.1 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 2.1 environment and re-integrated into the new 3.0 environment.
8.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.
54
8.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;
8.8.5 Update XMLA Connections (Optional)

When you upgrade your sample data to 3.0, 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.20, "Update XMLA ConnectionDefinitions".
8.8.6 Upgrade the Liferay Portal

JasperServer can be configured to run with the Liferay Portal. If your JasperServer is set up to run with Liferay you must do the following steps as part of the upgrade process. You will need to delete the webapps/JasperSoft folder of the application server hosting Liferay. This deletes libraries used in older versions that conflict with libraries in the latest version. Once this folder is deleted, you can deploy the new portlet WAR. For more information, refer to the JasperServer Professional Administrator Guide.
8.8.7 Upgrade Using Export and Import Operations

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-install2.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)
55
JasperServer Professional Installation Guide js-export.sh --everything --output-dir my-2.1-resources 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 js-import.sh --input-dir my-2.1-resources (Windows) (Linux) (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".
56
9 Upgrade Notes for JasperServer 2.0

If you are upgrading from an older JasperServer version such as 2.0 then you must run additional database upgrade scripts. In the upgrade steps specified in the previous section, before you run the steps in section 8.4 "Upgrade the JasperServer Database", you should first run the steps below:
9.1 MySQL
Jasperserver Database cd <unpacked-war-dir-2.1>/scripts/upgrade mysql> use jasperserver; mysql> source upgrade-mysql-2.0.0-2.1.0.sql; Sample Database cd <unpacked-war-dir-2.1>/scripts/upgrade/sample mysql> use foodmart; mysql> source upgrade-mysql-sample-foodmart-2.1.0.sql;
9.2 Oracle
SQL> connect jasperadmin/password@ORCL SQL> @upgrade-oracle-2.1.0-3.0.0.sql The same script upgrade principle should be applied to JasperServer instances older than 2.0.
9.3 Export and Import Operation from 2.0 to 3.0 Error

Section 8.8.7, "Upgrade Using Export and Import Operations", describes upgrading using the export and import operations. However, if you start with JasperServer 2.0 and go directly to 3.0 (or 2.1), there is a bug regarding SecureMondrianConnections when you run the import operation. The underlying problem is that Analysis data security was added to the 2.1 release and a new resource object SecureMondrianConnect was created to handle this functionality. When the old, non-secure MondrianConnection object is attempted to be upgraded to the 2.1 SecureMondrianConnection object the operation fails. For the 3.0 release, a work around has been added to help with this problem. There are two ways to work around this problem. Delete any 2.0 MondrianConnection Objects You can delete any MondrianConnections that are in your 2.0 system. If you are not using MondrianConnections as part of your business data, you may still have these resources as part of the JasperServer sample data. These are typically found in the repository under the /analysis/connections folder. Then, you can continue your upgrade procedures as normal. Run Special Convert XML Operation You will follow the steps similar to the steps described in section 8.8.7, "Upgrade Using Export and Import Operations". You will first export your 2.0 repository data following the steps similar to what is described in section 8.8.7.
57
JasperServer Professional Installation Guide Next, you will move to your already installed JaspeServer 3.0 location: cd <js-install-3.0>/scripts Make sure your 3.0 import-export is configured for you database settings as described in section 8.8.7. Edit the ant file: build-convert-export.xml. Look for the <import-dir> property and set it to the full path of the 2.0 export directory that you just created. For example: <property name="import-dir" value="C:\Program Files\jasperserver-pro-2.0\my-2.0-resources"/> Then, run the ant script that will convert your 2.0 export file so that the SecureMondrianConnection issue is fixed, and will import the contents of the converted export file into your 3.0 system: ant -f build-convert-export.xml convert-repository-to-3.0-from-export
58
10 Adding Password Encryption to JasperServer

10.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 Professional Administrator Guide.
10.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.
10.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 jasperdb user or the root user to carry out this operation. Refer to section 8.8.1, "Using mysqldump for Database Backup", for more information on running the mysqldump command. Oracle Refer to your Oracle documentation for details. Microsoft SQL Server Refer to your SQL Server documentation for details. PostgreSQL Refer to your PosrgreSQL documentation for details.
10.4 Stop Application Server

You can now stop your application server. You should leave your database running.
59
10.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 js-export.sh --everything --output-dir js-backup-catalog 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. (windows) (Linux)
10.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 Professional 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-pro/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>
60
JasperServer Professional Installation Guide Note: As described in the JasperServer Professional 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.
10.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.
10.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; .mysql>source jasperserverCreateDefaultSecurity-mysql.sql;
Oracle Change directory to: .cd <js-install>/scripts/oracle Login to your SQLPlus client: .sqlplus jasperadmin/password@MY_SID Drop the jasperserver database, create a new one and load the jasperserver schema: .SQL> drop tablespace jasperserver including contents and datafiles; .SQL> create tablespace jasperserver datafile 'jasperserver.dbf' size 100m reuse autoextend on next 50m maxsize 1000m extent management local autoallocate segment space management auto;
61
JasperServer Professional Installation Guide .SQL> connect jasperadmin/password@MY_SID .SQL> @jasperserverCreate-oracle.ddl .SQL> @jasperserverCreateDefaultSecurity-oracle.sql Microsoft SQL Server Change directory to: .cd <js-install>/scripts/sqlserver Drop the jasperserver database, create a new one and load the jasperserver schema: .sqlcmd -S localhost\jasperserver -Q "DROP DATABASE jasperserver" .sqlcmd -S localhost\jasperserver -Q "CREATE DATABASE jasperserver" .sqlcmd -S localhost\jasperserver -d jasperserver -i jasperserverCreate-sqlserver.ddl .sqlcmd -S localhost\jasperserver -d jasperserver -i jasperserverCreateDefaultSecurity-sqlserver.sql PostgreSQL Change directory to: .cd <js-install>/scripts/postgresql Drop the jasperserver database, create a new one and load the jasperserver schema: Start psql using an admin account (such as "postgres"): psql -U postgres Enter the following commands: drop database jasperserver; create database jasperserver encoding='utf8'; \c jasperserver \i jasperserverCreate-postgresql.ddl \i jasperserverCreateDefaultSecurity-postgresql.sql
10.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 js-import.sh --input-dir js-backup-catalog 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. (windows) (Linux)
10.10
Start Application Server
You can now start your application server. Your database should already be running.
62
10.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.
63
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 Professional 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 scripts/js-import.sh scripts/config/js.jdbc.properties scripts/config/applicationContext-*.xml scripts/lib
Import batch script for Windows. Import shell script for Linux Database and hibernate dialect settings file Spring configuration files 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 Sample Settings for Oracle Modify the items in bold to match your own environment setup: metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.OracleUnicodeDialect metadata.jdbc.driverClassName=oracle.jdbc.OracleDriver metadata.jdbc.url=jdbc:oracle:thin:@localhost:1521:orcl metadata.jdbc.username=jasperadmin metadata.jdbc.password =password Sample Settings for DB2 metadata.hibernate.default_schema=JSPRSRVR
metadata.jdbc.driverClassName=com.ibm.db2.jcc.DB2Driver
64
JasperServer Professional Installation Guide metadata.jdbc.url=jdbc:db2://localhost:50000/jsprsrvr:driverType=4;fullyMaterializeLobData=true;fullyMaterializeInputStr eams=true;progressiveStreaming=2;progresssiveLocators=2;currentSchema=JSPRSRVR; metadata.jdbc.username=db2admin metadata.jdbc.password=password metadata.jndi=jdbc/jasperserver metadata.upperCaseNames=true Sample Settings for SQL Server Modify the items in bold to match your own environment setup: metadata.hibernate.dialect=org.hibernate.dialect.SQLServerDialect metadata.jdbc.driverClassName= com.microsoft.sqlserver.jdbc.SQLServerDriver metadata.jdbc.url= jdbc:sqlserver://localhost:1433;databaseName=jasperserver;SelectMethod=cursor metadata.jdbc.username=jasperadmin metadata.jdbc.password =password Sample Settings for PostgreSQL Modify the items in bold to match your own environment setup: metadata.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect metadata.jdbc.driverClassName= org.postgresql.Driver metadata.jdbc.url=jdbc:postgresql://localhost:5432/jasperserver metadata.jdbc.username=postgres metadata.jdbc.password=postgres
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

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:
65
JasperServer Professional Installation Guide ./js-export.sh --uris /reports --output-dir /home/user/my-reports (instead of ~/my-reports)
66
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". Oracle Start SQL*Plus and try to log into Oracle directly. Three users are created during installation: jasperadmin schema user for the JasperServer metadata. sugarcrm schema user for the SugarCRM sample data. foodmart schema user for the foodmart sample data. To log in as each of these users, supply the password specified during installation. Microsoft SQL Server Start SQLCmd and try to log into MSSQL Server directly. For example: sqlcmd -S localhost\jasperserver -d jasperserver -U jasperadmin -P password
B.2.2 Check Configuration File Locations

Tomcat File Locations
67
JasperServer Professional Installation Guide When using Tomcat, JasperServer configuration properties are found in the following files: <apache-tomcat>/webapps/jasperserver-pro/META-INF/context.xml <apache-tomcat>/webapps/jasperserver-pro/WEB-INF/hibernate.properties <apache-tomcat>/apache-tomcat/webapps/jasperserver-pro/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 or <jboss>/server/default/deploy/js-oracle-ds.xml <jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF/hibernate.properties <jboss>/server/default/deploy/ jasperserver-pro.war/WEB-INF/web.xml <jboss>/server/default/deploy/ jasperserver-pro.war/WEB-INF/jboss-web.xml
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.
Note: For the JasperServer Pro product the filename and directory names are jasperserver-pro
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-pro-3.0/mysql/bin/mysqld_safe --port=3306 --socket=/home/devuser/jasperserver-pro-3.0/mysql/tmp/mysql.sock etc... Then run a command similar to the following: /home/devuser/jasperserver-pro-3.0/mysql/bin/mysql -u jasperdb -p --socket=/home/devuser/jasperserver-pro-3.0/mysql/tmp/mysql.sock
68
JasperServer Professional Installation Guide Note: In JasperServer 2.1 and earlier the suggested default DB user name was "jasperadmin".
B.3 License Not Found Error

JasperServer Professional needs a valid license. Normally, the installer includes an evaluation license file that you replace with a commercial license file as described in section 2.2.3, "Installing a New License File". If JasperServer still returns an error, make sure that the following Java option is set in your application server startup environment: -Djs.license.directory="<js-install>" This option must point to the location of your license file, which is typically in the <js-install> directory. For example, in Linux: -Djs.license.directory="/opt/jasperserver-pro-<ver>" The specified directory must contain the license file, which should be named jasperserver.license. This Java option is typically set for your application server in the environment startup script. Typical locations would be: <apache-tomcat>/bin/setclasspath.bat or .sh <jboss>/bin/run.bat or .sh (Tomcat) (JBoss)
Section 5.12, "Setup JasperServer License", has additional information on configuring the JasperServer license.
B.4 License Not Found Error with Tomcat as a Service

If you have Tomcat running as a service under Windows, the installer attempts to make the proper updates so that the JasperServer license file is found at application server startup time. However, if these updates are not successful take the additional steps described in section 2.2.4 "License File for Tomcat as Windows Service".
B.5 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 an individual report is the data source being used. You can troubleshoot this in the repository: Log into JasperServer as a user with administrative permissions and locate the report unit that returns errors. Highlight the report and click the edit button in the toolbar to identify the data source the report uses. The data source name is found on the fourth edit page. Locate this data source in the repository and click the edit button in the toolbar. Review the information specified for this data source. Click the Test Connection button in order to validate the connection. 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.6 Database Error after Changing MySQL Port Number

MySQLs 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.7 Case Sensitivity for Table and Column Names

69
JasperServer Professional Installation Guide 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, its 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.8 Java Out of Memory Error

If you encounter a Java out of memory error, it is suggested that you increase your Java heap size setting. 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.13, "Set Java JVM Options", for more information on Java JVM settings.
B.9 Error Running Scheduled Report

If you setup a scheduled report, chose to run it, and chose to save it as HTML or RTF, the report size can potentially get quite large. If you are running MySQL and you get the following error: JDBC exception on Hibernate data access org.hibernate.exception.GenericJDBCException: could not insert the problem may be the default size of the MySQL blob datatype. You can increase the size of this datatype by updating youre my.ini or my.cnf MySQL configuration file. Add the following setting: max_allowed_packet=32M
B 10 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)
70
JasperServer Professional Installation Guide 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: "&". The "&" 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.11 JBoss Modifications

B.11.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-pro.war/WEB-INF/applicationContext.xml Uncomment the following line: <value>/WEB-INF/js.jdbc-postgresql.properties</value> Edit: <jboss>/server/default/deploy/jasperserver-pro.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> <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:
71
JasperServer Professional Installation Guide <jboss>/server/default/deploy/jasperserver-pro.war/WEB-INF Edit properties file to match your PostgreSQL settings: <jboss>/server/default/deploy/jasperserver-pro.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.11.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 Windows Value
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
Note: Refer to Appendix C: "Java 1.6 JVM Options" for more specific configuration information.
B.11.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 in order to silence the INFO log message: <category name="org.jboss.resource.connectionmanager.CachedConnectionManager">
72
JasperServer Professional Installation Guide <priority value="WARN"/> </category>
B.11.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-pro.war/WEB-INF/lib/log4j-<ver>.jar
B.12 WebSphere: "Page Not Found" Error on Login

This error is seen during a WebSphere installation when the user attempts to login to JasperServer. After typing in a correct username/password pair, the user sees an error page: "Page cannot be found, HTTP 404". Some WebSphere versions (and/or fix packs) have modified code that processes web server filters incorrectly. Parts with the "/*" url pattern get affected by this. JasperServer uses the Acegi framework for authentication and it is mapped using a filter chain with the "/*" url pattern. WebSphere provides a special property to solve this problem: 1) Login into WebSphere Administrative Console 2) Navigate to Application Servers > <server> > Web Container Settings > Web Container > Custom Properties 3) Create a new property with the following attributes: a. b. name: com.ibm.ws.webcontainer.invokefilterscompatibility value: true
4) Save the master configuration 5) Restart the WebSphere server
B.13 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-pro/WEB-INF/js.quartz.properties You should make sure that the following property does not have the "standard" driver delegate, but instead has the PostgreSQL specific driver delegate. It should look like the following for PostgreSQL: org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
73
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 Web Services and 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 JBoss file JAVA_OPTS setting (Windows) JAVA_OPTS setting (Linux)
<tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh) <jboss>/bin/run.bat or run.sh set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m set JAVA_OPTS=%JAVA_OPTS% -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m -XX:PermSize=32m -XX:MaxPermSize=128m " 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 JBoss file JAVA_OPTS setting (Windows)
<tomcat>/bin/setclasspath.bat or setclasspath.sh (or setenv.bat, setenv.sh) <jboss>/bin/run.bat or run.sh 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
JAVA_OPTS setting (Linux)
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.
74
Appendix D: Configuring and Using Ant

If you are installing JasperServer Pro with a SQL Server database, some steps run scripts using Ant, which is a Java-based open-source utility for scripting tasks such as building and installing software.
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>
75

Jasper Server Pro Install Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jasper Server Pro Install Guide

Uploaded by

Copyright:

Available Formats

JasperServer Professional Installation Guide

JasperServer Professional Installation Guide

Installing JasperServer ............................................................................................................11

Starting and Stopping JasperServer.......................................................................................16

Install Using War File Distribution for WebLogic Application Server..................................44

Upgrade from JasperServer 2.1 to JasperServer 3.0 ............................................................50

Upgrade Notes for JasperServer 2.0.......................................................................................57

10 Adding Password Encryption to JasperServer......................................................................59

JasperServer Professional Installation Guide

<java> Additional Locations <unpacked-war-dir> jasperadmin/ jasperadmin jasperdb/password

1.3 JasperServer Distributions

JasperServer Professional Installation Guide

1.4 Installer Distribution Support

1.4.2 Components Included in the Installer

1.4.3 Applications Supported by the Installer

1.4.4 Application Versions Supported

1.4.5 Java Version Supported

JasperServer Professional Installation Guide

1.5 War File Binary Distribution Support

1.6 Release Notes and Application Support

1.7 Prerequisites for Installation

1.7.1 System Requirements

JasperServer Professional Installation Guide

1.8 Support for Internationalization

JasperServer Professional Installation Guide

2.1 Installation Steps

2.1.2 Accept License Agreement

2.1.3 Installation Directory Location

2.1.4 Select Tomcat Configuration

2.1.5 Select MySQL Configuration

2.1.6 Install Sample Data

JasperServer Professional Installation Guide

2.1.7 Install iReport

2.1.8 Ready to Install

2.1.9 Installation Complete Screen

2.1.10 Log Into JasperServer

2.2 Post-Installation Steps

2.2.2 Installer Output Log File

2.2.3 Installing a New License File

2.2.4 License File for Tomcat as Windows Service

You should now be able to run JasperServer.

2.2.5 Check your Java JVM Options

JasperServer Professional Installation Guide

3 Starting and Stopping JasperServer

3.1 Using JasperServer Start/Stop Scripts

3.2 Using Start/Stop Scripts Without Bundled Installation

3.3 Logging into JasperServer

3.4 Starting the Included iReport

3.5 JasperServer Log Files

JasperServer Professional Installation Guide

JasperServer Professional Installation Guide

5 Install Using the War File Distribution for Tomcat or JBoss

5.1.1 Applications Supported by the War File Distribution

5.1.2 Application Versions Supported

5.2 Obtain the War File Distribution

5.3 Unpack the War File Distribution Zip

JasperServer Professional Installation Guide

5.4 Setup the JasperServer Database

5.4.1 MySQL Database Setup Steps

5.4.2 Oracle Database Setup Steps

5.4.3 DB2 Database Setup Steps

5.4.4 Microsoft SQL Server Database Setup Steps

5.4.5 PostgreSQL Database Setups Steps