TIBCO JasperReports Server Installation Guide Jasper Reports Install
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 130
| Download | |
| Open PDF In Browser | View PDF |
JASPERREPORTS® SERVER INSTALLATION GUIDE RELEASE 6.4 http://www.jaspersoft.com Copyright ©2005-2017 TIBCO Software Inc. All Rights Reserved. TIBCO Software Inc. This is version 0217-JSP64-45 of the TIBCO JasperReports Server Installation Guide. TABLE OF CONTENTS Chapter 1 Introduction 1.1 Conventions 1.2 Supported Platforms 1.3 Using IBM JDK 1.7 1.4 JasperReports Server Distributions 1.4.1 Installer Support 1.4.2 WAR File Binary Distribution Support 1.5 Release Notes 1.6 System Requirements 1.7 Support for Internationalization Chapter 2 Installing JasperReports Server 2.1 Pre-installation Steps 2.2 Starting the Installer 2.3 Accepting the License Agreement 2.4 Choosing Installation Type 2.5 Choosing an Installation Directory 2.6 Selecting a Tomcat Configuration 2.7 Selecting a PostgreSQL Configuration 2.7.1 Choosing the Bundled PostgreSQL 2.7.2 Choosing an Existing PostgreSQL on a Local Host 2.7.3 Using an Existing PostgreSQL on a Remote Host 2.7.4 Enabling Connections to a Remote Host 2.8 Installing Sample Data 2.9 Completing the Installation 2.10 Post-installation Steps 2.10.1 Updates Made by the Installer During Installation 2.10.2 Installer Output Log File Location 2.10.3 Setting your Java JVM Options 2.10.4 Installing a New License File 2.10.5 License File for Existing Tomcat as Windows Service 2.11 Starting and Stopping the Server 2.11.1 Start/Stop Menu — Windows TIBCO Software Inc. 9 10 11 11 11 12 13 14 15 15 17 17 18 18 18 19 19 20 20 20 21 22 22 22 23 23 24 24 24 24 25 25 3 TIBCO JasperReports Server Installation Guide 2.11.2 Start/Stop Scripts — Linux 2.11.3 Start/Stop Apps — Mac OSX 2.12 Logging into JasperReports Server 2.13 Log Files 2.14 Uninstalling the Server 2.14.1 Windows 2.14.2 Linux 2.14.3 Mac OSX 2.14.4 Uninstall Survey Chapter 3 Installing the WAR File Distribution 3.1 Applications Supported by the WAR File Distribution 3.1.1 Database and Application Server Support 3.1.2 Operating System Support for Bash Shell 3.2 Installing the WAR File Using js-install Scripts 3.3 Additional Steps for Using DB2 and js-install Scripts 3.4 Additional Steps for Using JBoss EAP or Wildfly 3.5 Starting the Server 3.6 Logging into the Server 3.6.1 JasperReports Server Heartbeat 3.7 Troubleshooting Your Server Configuration 3.7.1 Startup Problems 3.7.2 Error Running a Report 3.7.3 Error Running js-install Scripts (js-install.bat/sh) 3.7.4 Problem Connecting to a Cloud Database Instance 3.8 Installing the WAR File Manually Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.1 Setting JVM Options for Application Servers 4.1.1 Tomcat and JBoss JVM Options 4.1.2 Changing JVM Options for Tomcat as a Windows Service 4.1.3 Changing JVM Options for Bundled Tomcat on Linux 4.1.4 Changing GlassFish JVM Options 4.2 Setting Up the JasperReports Server License 4.2.1 Default License Configuration for All Application Servers 4.2.2 User-Defined License Location 4.3 Working With JDBC Drivers 4.3.1 Open Source JDBC Drivers 4.3.2 Commercial JDBC Drivers 4.3.3 Working with Oracle RAC 4.3.4 Application Server Copy-to Locations 4.4 Locating and Changing Buildomatic Configuration Files 4.4.1 Regenerating Buildomatic Settings 4.4.2 Locating Buildomatic-Generated Property Files 4.4.3 Buildomatic Location for JasperReports Server WAR File 4.4.4 Buildomatic Location for SQL Scripts 4.4.5 Buildomatic Location for Database Creation Scripts 4 26 27 28 29 29 29 29 30 30 31 31 31 32 32 35 36 37 37 37 38 38 38 38 39 39 43 43 43 46 46 47 48 48 49 50 50 52 54 56 56 56 56 57 57 58 TIBCO Software Inc. 4.4.6 Buildomatic Location for Sample Data Catalog ZIP Files 4.4.7 Hibernate Properties Settings 4.4.8 Database Connection Configuration Files 4.5 Configuring Report Scheduling 4.5.1 Mail Server Configuration Settings 4.5.2 Database Settings for the Quartz Driver Delegate Class 4.5.3 Settings for the Report Scheduler Web URI 4.5.4 Settings for the Quartz Table Prefix 4.5.5 Settings for Import-Export 4.5.6 Setting Properties in the default_master.properties File 4.6 Updating XML/A Connection Definitions Chapter 5 Installing the WAR File for WebSphere 5.1 Procedure for Installing and Deploying the WAR File in WebSphere 5.1.1 Installing WebSphere and a Database 5.1.2 Preparing Server Files 5.1.3 Configuring CSRFGuard, Hibernate, and Quartz Settings 5.1.4 Configuring a JDBC Provider in WebSphere 5.1.5 Deploying the WAR File in WebSphere 5.1.6 Setting JVM Options 5.2 Configuring Other Database Connections 5.2.1 Defining a JNDI Name and Sample Data Sources for MySQL 5.2.2 Defining a JNDI Name and Sample Data Sources for DB2 5.2.3 Defining a JNDI Name and Sample Data Sources for Oracle 5.2.4 Defining a JNDI Name and Sample Data Sources for SQL Server 5.3 Starting and Restarting JasperReports Server 5.4 Logging into the Server 5.5 Configuring Report Scheduling 5.5.1 Additional Fix for Scheduled Report with JNDI Data Source 5.5.2 Additional Change for Mail Server Authentication 5.6 Updating XML/A Connection Definitions (Optional) 5.7 Troubleshooting your Configuration 5.7.1 Startup Problems 5.7.2 Error Running Report 5.7.3 Filter Error Using MySQL 5.7.4 Error Creating Internationalized Name 5.7.5 Xerces Error 5.7.6 OLAP View Fails With Exception Chapter 6 Installing the WAR File for WebLogic 6.1 Procedure for Installing the WAR File for WebLogic 6.2 Setting Java Properties 6.3 Configuring Other Database Connections 6.3.1 Configuring TIBCO JDBC Driver Connections 6.3.2 Configuring Databases Using the Vendor's Driver 6.4 Starting the Server 6.5 Logging into the Server TIBCO Software Inc. 58 58 59 60 60 61 62 63 63 63 64 65 65 65 66 67 68 72 72 74 74 75 78 80 81 81 82 82 82 83 83 83 83 83 83 84 84 85 85 92 93 93 96 98 98 5 TIBCO JasperReports Server Installation Guide 6.6 Configuring Report Scheduling 6.7 Restarting the Server 6.8 Updating XML/A Connection Definitions (Optional) 6.9 Troubleshooting Your JasperReports Server Configuration 6.9.1 Startup Problems 6.9.2 Error Running Report Appendix A Troubleshooting A.1 Binary Installer Freezes A.1.1 Installer Log Files A.1.2 Installer DebugTrace Mode A.2 Error Running Buildomatic Scripts A.2.1 Missing Java JDK A.2.2 Forgot to Copy the File ant-contrib.jar A.2.3 Failure with '$' Character in Passwords in Buildomatic Scripts A.2.4 Older Apache Ant Version A.3 Unable to Edit Files on Windows 7 A.4 Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD A.5 Linux Installer Issue with Unknown Host Error A.6 Installation Error with Windows Path A.7 Mac OSX Issues A.7.1 Problem Starting JasperReports Server on Mac A.8 Database-related Problems A.8.1 Database Privileges Required By JasperReports Server A.8.2 Database Connectivity Errors A.8.3 Case-sensitive Collation in SQL Server A.8.4 Configuring the TIBCO Oracle or SQL Server Driver for NTLM Authentication A.8.5 Maximum Packet Size in MySQL A.8.6 Case Sensitivity for Table and Column Names A.8.7 PostgreSQL: Job Scheduling Error A.8.8 Invalid SQL statement Error with TIBCO JDBC Driver Under WebLogic A.8.9 Performance Issues with Oracle JDBC Queries A.8.10 Using an Oracle Service Name A.8.11 Error Running a Scheduled Report A.8.12 Error Running a Report A.8.13 Save Error with DB2 Database A.8.14 BeanDefinitionStoreException with DB2 with Vendor's Driver A.9 Application Server-related Problems A.9.1 Memory Issues Running Under Tomcat A.9.2 Java Out of Memory Error A.9.3 Configuration File Locations A.9.4 Context.xml on Tomcat: Special Case A.9.5 Tomcat Installed Using apt-get/yum A.9.6 GlassFish Modifications A.9.7 JBoss Modifications A.9.8 WebSphere Modifications 6 98 99 99 99 99 99 101 101 101 102 102 102 102 103 103 103 103 104 105 105 105 106 106 107 108 108 108 109 109 109 110 110 110 111 111 111 112 112 112 112 112 113 114 114 117 TIBCO Software Inc. A.9.9 WebLogic Modifications A.9.10 Disabling User Session Persistence in Application Servers A.9.11 Session Error Using JasperReports Server and Tomcat 7 A.10 License-related Errors A.10.1 License Not Found Errors A.10.2 Failure to Unlock TIBCO JDBC Driver Error A.10.3 License Not Found or License Corrupt Error with Tomcat as a Service A.11 Problems Importing and Exporting Data from the Repository A.11.1 Exporting a Repository That Contains UTF-8 A.12 Problems with Upgrade A.12.1 Oracle Error on Upgrade when PL/SQL Not Enabled A.12.2 DB2 Script Error on Upgrade A.12.3 Include Audit Events on Upgrade A.12.4 Overlay Upgrade Permissions Error with Bundled Installation A.12.5 Overlay Upgrade Domain Issue with MySQL and MariaDB JDBC Driver Appendix B Manually Creating the JasperReports Server Database B.1 B.2 B.3 B.4 B.5 PostgreSQL MySQL Oracle DB2 SQL Server TIBCO Software Inc. 117 117 118 119 119 119 119 120 120 120 120 121 121 121 122 123 123 124 125 127 128 7 TIBCO JasperReports Server Installation Guide 8 TIBCO Software Inc. CHAPTER 1 INTRODUCTION TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling. The server exposes comprehensive public interfaces enabling seamless integration with other applications and the capability to easily add custom functionality. This section describes functionality that can be restricted by the software license for JasperReports Server. If you don’t see some of the options described in this section, your license may prohibit you from using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to: • • • • • Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc Editor. Efficiently and securely manage many reports. Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data. Schedule reports for distribution through email and storage in the repository. Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey business trends. For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which runs as part of the server. While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of the server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be run in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the JasperReports file structure. You can use the following sources of information to learn about JasperReports Server: • • Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft Studio. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server installation. You can also access PDF and HTML versions of these guides online from the Documentation section of the Jaspersoft Community website. Our Ultimate Guides document advanced features and configuration. They also include best practice recommendations and numerous examples. You can access PDF and HTML versions of these guides online from the Documentation section of the Jaspersoft Community website. TIBCO Software Inc. 9 TIBCO JasperReports Server Installation Guide • • • Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system administrators, business users, and data integration users. The Portal is available online from the Professional Services section of our website. Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports Server, are available and documented online. Please visit our GitHub repository. If you have a subscription to our professional support offerings, please contact our Technical Support team when you have questions or run into difficulties. They're available on the web at and through email at http://support.tibco.com and js-support@tibco.com. JasperReports Server is a component of both a community project and commercial offerings. Each integrates the standard features such as security, scheduling, a web services interface, and much more for running and sharing reports. Commercial editions provide additional features, including Ad Hoc views and reports, advanced charts, dashboards, Domains, auditing, and a multi-organization architecture for hosting large BI deployments. This chapter contains the following sections: • • • • • • 1.1 Conventions Supported Platforms JasperReports Server Distributions Release Notes System Requirements Support for Internationalization Conventions This document uses the following conventions when referring to file locations: 10 Convention DescriptionThe root directory where JasperReports Server will be installed by the binary installer. For manual installations, the directory where you unpack the WAR file distribution TIB_js-jrs_6.4.0_bin.zip. See 2.5, “Choosing an Installation Directory,” on page 19 for the default values. The directory where GlassFish is installed. The directory where Java is installed. The directory where JBoss is installed. The directory where PostgreSQL is installed. If you use our bundled instance of PostgreSQL, it's in the directory. The directory where Apache Tomcat is installed. If you use our bundled instance of Tomcat, it's in directory. TIBCO Software Inc. Chapter 1 Introduction 1.2 Supported Platforms For a list of supported JDK/JVMs, application servers, databases, operating systems, and browsers, see the TIBCO Jaspersoft Platform Support document on the Documentation section of the Jaspersoft Community website. 1.3 Using IBM JDK 1.7 If you are using the IBM JDK 1.7, you need to set OWASP to use the correct Pseudo-random Number Generator (PRNG). To do this before installation, you can modify the WAR file as follows: 1. The WAR file is an archive format in a single file. a. Extract the Websphere.jrs.csrfguard.properties file using the following command: cd "%JAVA_HOME%/bin/jar" xf jasperserver-pro.war WEB-INF/csrf/Websphere.jrs.csrfguard.properties This creates the WEB-INF/csrf folder in the current location and places the extracted file there. b. Rename the file from Websphere.jrs.csrfguard.properties to jrs.csrfguard.properties using the following command: mv ./WEB-INF/csrf/Websphere.jrs.csrfguard.properties ./WEB-INF/csrf/jrs.csrfguard.properties 2. After you have modified the file, replace it in the WAR file archive using the following commands. cd "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/csrf/jrs.csrfguard.properties 1.4 JasperReports Server Distributions JasperReports Server has two main distribution packages. Distribution Package Description Installer Runs on Windows (64-bit), Linux (32- or 64-bit), and Mac OSX (64-bit). WAR File Distribution Zip Used for manual installation on Windows, Linux, Mac, and other platforms. The Installer package installs JasperReports Server, automatically configures the JasperReports Server database, and installs the sample data for working with tutorials — if you choose the Sample Data option. The WAR file binary distribution contains the JasperReports Server web archive file and the scripts to create and load the database. The WAR file distribution supports additional applications not supported by the installers. TIBCO Software Inc. 11 TIBCO JasperReports Server Installation Guide 1.4.1 Installer Support There are native installers for Linux, Macintosh, and Windows. See the Jaspersoft Platform Support document for the list of supported operating systems. 1.4.1.1 Installer Naming for 32-bit and 64-bit The 32-bit and 64-bit installers are distinguished by file name. Installer Type Naming 32-bit installer (Linux only) TIB_js-jrs_6.4.0_installer-linux-x86.run 64-bit installer TIB_js-jrs_6.4.0_installer-win-x64.exe TIB_js-jrs_6.4.0_installer-linux-x64.run TIB_js-jrs_6.4.0_installer-osx-x64.app.zip Note: x86 is shorthand referring to the 386, 486, and 586 CPU architecture. The 64-bit installer will put 64-bit versions of Java 8 and PostgreSQL 9 onto your system for increased speed and performance. Note: The 64-bit installer will not work on a 32-bit system. The 32-bit installer will work on a 64-bit system, but we don't recommend it. 1.4.1.2 Installer Distribution Components The installer is designed to get JasperReports Server up and running quickly. The server requires the Java environment, an application server, and a database. The installer distribution bundles these components: 12 Component Description JasperReports Server Application WAR file and configuration support scripts. JasperReports Server Documentation Found in the /docs directory. Apache Tomcat 8 Web application container. You can use the bundled version or an existing version. Java 1.8 Runtime Runs the web application container. PostgreSQL 9 Database Database server. You can use the bundled version or an existing version. PhantomJS Scriptable headless WebKit, required for exporting dashboards. We also recommend configuring JasperReports Server to use PhantomJS for graphical reports that are run in the background or scheduled. See the JasperReports Server Administrator Guide for more information. TIBCO Software Inc. Chapter 1 Introduction 1.4.1.3 Installing with Existing Components The installer can use either bundled or existing instances of both the Apache Tomcat application server and the PostgreSQL database: • • If you want to use an existing Tomcat, it must be on the local machine. If you want to use an existing PostgreSQL, it can be on a local or remote machine. If it’s on a remote Linux machine, configure PostgreSQL to allow remote connections as described in 2.7.4, “Enabling Connections to a Remote Host,” on page 22. For information about specific versions of third-party applications supported by the installer, refer to the JasperReports Server release notes in the root of the installation directory. 1.4.1.4 Running Components as Windows Services The Windows installer installs PostgreSQL and Tomcat as Windows Services. You can manage these Services in the Windows Control Panel: Control Panel > System and Security > Administrative Tools > Services You'll find the PostgreSQL and Tomcat services by the following names: • • jasperreportsPostgreSQL jasperreportsTomcat The bundled PostgreSQL and Tomcat applications restart automatically when the host Windows system restarts. If you don't want these components to automatically restart, change the Startup Type from automatic to manual. You can also start JasperReports Server from the Windows Start menu. 1.4.1.5 Installer on Windows 7 Due to a known issue with PhantomJS on Windows 7, you should not install PhantomJS using the bundled installer on Windows 7. Instead, to use PhantomJS, install JasperReports Server without PhantomJS and then install PhantomJS separately and configure JasperReports Server to use PhantomJS. See the JasperReports Server Administrator Guide for more information on configuring all JasperReports Server with PhantomJS. 1.4.2 WAR File Binary Distribution Support Use the WAR file binary distribution package to install the JasperReports Server application if you can't use the installer. The WAR file supports additional applications not supported by the installer. If you want to use a database other than PostgreSQL and/or an application server other than Apache Tomcat, install JasperReports Server using the WAR file. For a complete list of applications supported by the WAR file distribution, refer to the release notes included in the root directory of the distribution. The application server should reside on the local machine, but the target database can be on a remote server. Using a remote PostgreSQL database on some Linux platforms requires a change to its configuration file, as described in 2.7.4, “Enabling Connections to a Remote Host,” on page 22. The WAR file distribution includes js-install shell scripts (for Linux and Windows) that automate much of the installation using a single properties file. These scripts are: • • js-install.bat js-install.sh The main contents of the WAR file binary distribution are shown in the following table. TIBCO Software Inc. 13 TIBCO JasperReports Server Installation Guide Content Item Description JasperReports Server js-install Scripts Found at /buildomatic/js-install.bat and js-install.sh. JasperReports Server Database Scripts SQL scripts for each supported database. JasperReports Server Documentation Guides for end users and administrators. JasperReports Server Extra Samples Web Service example applications, sample reports, custom data source examples, and other sample files. JasperReports Server Standard Sample Data Sample data that highlights JasperReports Server features. JasperReports Server WAR file archive All of the JasperReports Server class files and dependent jars. 1.4.2.1 About Bundled Apache Ant The War File Distribution ZIP includes Apache Ant version 1.9.4. The buildomatic Ant scripts come with Windows and Linux batch scripts pre-configured to use the bundled version of Apache Ant. You call the buildomatic Ant scripts from the command line in the following manner: Windows: js-ant Linux and Mac OSX: ./js-ant If you want to run your own version of Ant, version 1.8.1 or higher is required. The bundled Apache Ant has an additional jar (ant-contrib.jar) that enables conditional logic in Ant. If you're running your own Ant, copy this jar to your Ant/lib folder. On Linux and Solaris, the js-ant commands may not be compatible with all shells. If you have errors, use the bash shell explicitly. For more information, see A.4, “Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD,” on page 103. 1.5 Release Notes Release notes are included with each distribution and with each new update to a distribution. Not all applications are immediately supported when a new JasperReports Server version is released. For instance, some applications require additional testing beyond what is completed for the initial General Availability (GA) release. To find out exactly what applications are supported with a particular distribution refer to the release notes in that distribution. 14 TIBCO Software Inc. Chapter 1 Introduction 1.6 System Requirements The following table contains the minimum and recommended resources for a full installation that includes PostgreSQL and an application server. The values are based on our own testing. You may find that JasperReports Server can run on systems with fewer resources or slower systems than stated in the minimum resources column. At the same time, it's possible to run out of resources with the recommended configuration. The success of your deployment depends on the intended load of the system, the number of concurrent users, the data sets, and whether the databases are installed on the same system as the JasperReports Server. 1.7 Resource Footprint Minimum Recommended Disk ~1.3 Gigabytes 10GB free 40GB + RAM 4GB 8GB + Processor 2 core minimum 2.5GHz + multi-core Pentium for Windows, Mac, and Linux Support for Internationalization JasperReports Server supports the full Unicode character set using UTF-8 encoding. It also depends on the underlying database and application server to support the UTF-8 character encoding. UTF-8 is configured by default in the bundled Tomcat and PostgreSQL software. If you use any other software, refer to the JasperReports Server Administrator Guide for instructions about configuring software to support UTF-8. TIBCO Software Inc. 15 TIBCO JasperReports Server Installation Guide 16 TIBCO Software Inc. CHAPTER 2 INSTALLING JASPERREPORTS SERVER This chapter describes how to install JasperReports Server using the installer executable. This chapter contains the following sections: • • • • • • • • • • • • • 2.1 Pre-installation Steps Starting the Installer Accepting the License Agreement Choosing Installation Type Selecting a Tomcat Configuration Selecting a PostgreSQL Configuration Installing Sample Data Completing the Installation Post-installation Steps Starting and Stopping the Server Logging into JasperReports Server Log Files Uninstalling the Server Pre-installation Steps When you run the installation executable, you can choose to install the bundled Apache Tomcat application server and PostgreSQL database or use an existing Tomcat and PostgreSQL. If you want to use an existing database instance, the database must be running at install time. If you want to use an existing Apache Tomcat, the Tomcat instance must be stopped. If you choose to install the bundled Tomcat and database, both are installed on the same host as the server. The bundled installer is not meant for use in Enterprise Production environments. TIBCO Software Inc. 17 TIBCO JasperReports Server Installation Guide 2.2 Starting the Installer In Windows, you'll need Administrative privileges to run the installer executable file. Right-click the binary installer file and select “Run as administrator” from the context menu. TIB_js-jrs_6.4.0_installer-win-x64.exe (64 bit only) The Windows installer will get an error installing the PostgreSQL database if the Windows user does not have sufficient Administrative privileges and if the installer is not started by right-clicking to use “Run as administrator”. In Linux, the installer is a .run file; you can run it from the command line or from a graphical environment. To start the installer from the command line, open a bash shell, and enter the name of the installer file. For example: ./TIB_js-jrs_6.4.0_installer-linux-x86.run (32 bit) ./TIB_js-jrs_6.4.0_installer-linux-x64.run (64 bit) In Mac OSX, the installer is a .zip file. After download, you should find the installer already unpacked in your /Downloads folder. Double-click the following: TIB_js-jrs_6.4.0_installer-osx-x64.app (64 bit only) Whether you run the installer from the command line or in a graphical environment, you'll be prompted for the same information. The following sections describe these prompts and assume you're in a graphical environment. If you're 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. The welcome screen introduces the installer. Click Next. If you're installing a 32-bit installer onto a 64-bit operating system you may get a popup reminder that a 64-bit installer is available. You can continue the 32-bit installation if you choose to. On Windows you'll get an error installing the PostgreSQL database if you don't have Administrative privileges and if you don't start the installer by right-clicking to use “Run as administrator”. 2.3 Accepting the License Agreement You must accept the license agreement or exit the installer. When prompted, read the agreement and click I accept the agreement then click Next. If installing from the command line, you must page through several screens of text to read the full agreement. 2.4 Choosing Installation Type You can choose a full install of all components and sample data or a custom install that lets you choose the components you want and to take or leave the sample data. Install All Option: This option copies a Bundled version of the Apache Tomcat package and a Bundled version of the PostgreSQL database to your file system; adds all sample data (Reports, Data Sources, OLAP Views, etc) to your 18 TIBCO Software Inc. Chapter 2 Installing JasperReports Server JasperReports Server; and creates additional sample databases. The installer looks for open Tomcat ports from 8080 up and for open PostgreSQL ports from 5432 up. After you choose this option, you can choose the installation directory for JasperReports Server. All files and components can then be installed with no further information required. Custom Install: With the custom install, you have the following choices: install a Bundled Tomcat or use an Existing Tomcat, install a Bundled PostgreSQL or use an Existing PostgreSQL, choose ports for Tomcat and PostgreSQL, and choose whether or not to install sample data. 2.5 Choosing an Installation Directory When you're prompted to choose the JasperReports Server installation directory, you can accept the default directory or click Browse and choose a different location. On the command line, press Enter to accept the default or enter a directory at the prompt to choose a different location. The default directory depends on your operating system: Windows: C:\Jaspersoft\jasperreports-server- Linux: /jasperreports-server- Linux (as root) /opt/jasperreports-server- Mac OSX /Applications/jasperreports-server- On Linux, choose a path that’s no more than 84 characters. 2.6 Selecting a Tomcat Configuration JasperReports Server requires an application server. The installer is configured to run with the Apache Tomcat server. When you run the installer, two options appear on Setup — Please select the Tomcat configuration you want to use: • I want to use the bundled Tomcat If you choose this option, the installer puts an instance of Tomcat 8 onto your system. Later, after choosing a bundled or existing database, you're prompted for the server port and shutdown port Tomcat will use. You can accept the default values or enter alternate values. • I want to use an existing Tomcat If you have an instance of Tomcat on your system, you can choose this option. Later, after choosing a bundled or existing database, you're prompted for the location of Tomcat. • Browse to the folder where you installed Tomcat. After selecting a PostgreSQL configuration, you're prompted for Tomcat's server port and shutdown port. Accept the default values or enter alternate values. TIBCO Software Inc. 19 TIBCO JasperReports Server Installation Guide 2.7 Selecting a PostgreSQL Configuration JasperReports Server requires a database. The installer is pre-configured to run with the PostgreSQL database. You have two options: • • 2.7.1 I want to use the bundled PostgreSQL database I want to use an existing PostgreSQL database Choosing the Bundled PostgreSQL If you choose to install the bundled PostgreSQL, the installer puts PostgreSQL 9 onto your system. The default PostgreSQL port is 5432. If port 5432 is in use, the installer will prompt you to pick an alternate port. The installer sets the PostgreSQL administrator password to postgres and creates a PostgreSQL database user with administrator privileges and the credentials jasperdb/password. The following table summarizes the parameters set during installation of the bundled PostgreSQL: 2.7.2 Parameter Default Value and Description Binary Directory The directory where the postgres and pgAdmin3 binaries are located. Port The port number PostgreSQL uses (default is 5432). Choose an alternate port if 5432 is in use. IP or Host Name The IP address or name of the machine where PostgreSQL is installed. The default value is 127.0.0.1. PostgreSQL Administrative Password Password of the database administrative user: postgres. The installer cannot handle special characters at the end of a password string. Incompatible characters include: & ; $ Database User Name Hard coded default: jasperdb - The installer creates this user which is used to connect to the JasperReports Server database Database User Password Hard coded default: password - The installer uses this password for the jasperdb user. Additional notes for Linux If your Linux installation does not have a locale setting that supports UTF-8 encoding, your Bundled PostgreSQL instance will be initialized using a temporary locale (--locale=C). This will allow the PostgreSQL initdb to succeed with the desired UTF-8 database encoding. Choosing an Existing PostgreSQL on a Local Host If you choose to use an existing PostgreSQL database, you'll be prompted for the location of PostgreSQL and the port to use. If you have an instance of PostgreSQL installed locally, accept the default, which is 127.0.0.1, the localhost. Accept the default location for the PostgreSQL \bin directory, or click Browse to select another location. You'll also be prompted for the default administrative account password of the PostgreSQL administrative user. The database administrative user account name postgres is used by default. Enter the database administrative user password and click Enter. 20 TIBCO Software Inc. Chapter 2 Installing JasperReports Server If the installer displays an error message saying FATAL: password authentication failed for user postgres, try reentering the administrative password for your PostgreSQL database. The following table summarizes the parameters set during the installation of an existing PostgreSQL: Defaults Used Hardcoded Default Values Used or Created PostgreSQL Administrative User Name postgres - The default administrative database user. jasperserver Database User Name jasperdb - The installer creates this database user to connect to jasperserver database. jasperserver Database User Password password - The installer creates this password for the jasperdb database user. To improve system security, Jaspersoft recommends that you change the default password for jasperdb as soon as possible. To change the jasperdb connection password in JasperReports Server, edit: /apache-tomcat/jasperserver-pro/META-INF/context.xml. (And delete: /apache-tomcat/conf/Catalina/localhost/jasperserver-pro.xml, if it exists.) Then make the same change in PostgreSQL using pgAdmin III or psql. 2.7.3 Using an Existing PostgreSQL on a Remote Host If you're installing to a remote instance of PostgreSQL, you need to have the PostgreSQL client tools on your local machine. The client tools version should match the version of your remote PostgreSQL. You can check the version of PostgreSQL instance by entering this command on the computer where it’s installed: psql --version or /psql --version For instance: C:/Jaspersoft/PostgreSQL/9.0/bin/psql --version To verify that you can connect to the target remote PostgreSQL from the local installation machine: • Using your local PostgreSQL client tools, enter this command: psql -U postgres -h -d postgres or /psql -U postgres -h -d postgres You might also need to enable connections as described below. TIBCO Software Inc. 21 TIBCO JasperReports Server Installation Guide 2.7.4 Enabling Connections to a Remote Host On most platforms, the default PostgreSQL installation doesn’t allow remote connections for security reasons. You need to enable remote connections as described in this documentation: • • The PostgreSQL configuration documentation on the PostgreSQL web site The \docs directory of your PostgreSQL installation To enable connections from the installation machine to the remote PostgreSQL server: 1. Locate the following PostgreSQL host-based authentication (hba) configuration file on the remote PostgreSQL server instance: Windows: C:\Program Files\PostgreSQL\9.0\data\pg_hba.conf Linux: /var/lib/pgsql/data/pg_hba.conf 2. Add the IP address of your local JasperReports Server installation machine to this file. For example, to allow the local installation machine with address 192.168.12.10 to connect to the PostgreSQL server, add this entry to the pg_hba.conf file: host all 192.168.12.10/32 trust 3. Allow TCP/IP connections to the remote PostgreSQL server instance by making the following change to the postgresql.conf file on the remote machine: From: listen_addresses = 'localhost' To: listen_addresses = '*' 2.8 4. Restart PostgreSQL. 5. Using your local PostgreSQL client tools, verify that you can connect to the target remote PostgreSQL from the local installation machine, as described in 2.7.3, “Using an Existing PostgreSQL on a Remote Host,” on page 21. Installing Sample Data During installation, you'll be prompted to install sample databases and sample reports. We provide these resources to help you evaluate the many features of JasperReports Server. This sample data includes: • • • SugarCRM data that simulates three years of operations for a fictitious company that relies on the SugarCRM open source application. Foodmart data that simulates three years of operations for a fictitious company. JasperReports Server repository resources such as Reports, OLAP Views, Ad Hoc Topics, Domains, Data Sources, and Input Controls. Our documentation provides tutorials that use this sample data. We strongly recommend that you install it. 2.9 Completing the Installation After you've installed the files, you'll see several post-installation options on the final screen: • • 22 View Release Notes - If you choose to view the release notes, you'll have to exit the release notes text viewer before JasperReports Server will launch. Launch JasperReports Server Now (for bundled Tomcat and PostgreSQL only) If you’re installing on Linux, don't close the terminal window running the start script. TIBCO Software Inc. Chapter 2 Installing JasperReports Server If you choose not to Launch JasperReports Server Now, the bundled components won't be started. If you have only one bundled component, it won't be started unless you use the Start/Stop menus or scripts. • Opt-in for JasperServer Heartbeat - Sends anonymous system and version information to Jaspersoft using HTTPS. 2.10 Post-installation Steps 2.10.1 Updates Made by the Installer During Installation This section lists the standard updates the installer makes to your local environment when you install to existing applications. When the installation completes, you can check whether the updates, or corresponding changes, were successful. Updates made to the application server If you installed to an existing Tomcat, the installer attempted the following updates to the Tomcat environment: File or Directory Updates Windows: bin/setclasspath.bat Modifies JAVA_OPTS to add -Djs.license.directory. Linux and Mac OSX: bin/setclasspath.sh (Commercial installer only) All platforms: lib Adds JDBC drivers for databases to this directory. Updates made to the PostgreSQL database If you installed to an existing PostgreSQL database, the installer created new schemas and users in your database instance: PostgreSQL Updates Description Database jasperserver created This is the JasperReports Server repository database. This database holds all of system information, such as users, roles, data sources, and report definitions. Database user jasperdb created The JasperReports Server application uses this user to connect to the database. Sample database foodmart created (optional) Database created if install sample data option was chosen. Sample database sugarcrm created (optional) Database created if install sample data option was chosen. TIBCO Software Inc. 23 TIBCO JasperReports Server Installation Guide 2.10.2 Installer Output Log File Location The installer creates a log during installation that records information as the installation progresses. If you encounter any problems when you install JasperReports Server, it can be helpful to look at the installer log. You can find the installer log at /installation.log. 2.10.3 Setting your Java JVM Options You need to set your Java JVM options. There are number of files where you can do this; refer to 4.1, “Setting JVM Options for Application Servers,” on page 43. 2.10.4 Installing a New License File By default, JasperReports Server is installed with an evaluation license that expires a number of days after installation. After the license expires, you can start the server, but you can't log in. To obtain a commercial license, contact TIBCO Jaspersoft Technical Support (http://support.tibco.com) or your sales representative. To upgrade the evaluation license to a commercial one, copy the commercial license file over the evaluation license file. Application servers have work directories where JSP files are compiled and cached and other objects are stored. These directories can cause errors when upgrading a license. To avoid errors, clear the work directory before upgrading your license. For instance, if you’re using Tomcat: 1. Change directory to /work 2. Delete all the files in the directory After changing to a commercial license, make sure you stop the server before replacing the license file: 1. Stop the server 2. Replace the license named jasperserver.license in the deployed JasperReports Server root directory with the new license file The file name should be jasperserver.license 3. Restart the server By default, the license is in the directory, but can be located elsewhere. You need to define the -Djs.license.directory Java Environment Variable in the Tomcat startup scripts to point to the license location. The name of the license file is jasperserver.license. Make sure the new license file has this name. Restart JasperReports Server and log in to see if the license grants access. For information about license errors, see the troubleshooting section A.10, “License-related Errors,” on page 119. For additional license configuration options, refer to 4.2, “Setting Up the JasperReports Server License,” on page 48. 2.10.5 License File for Existing Tomcat as Windows Service If you installed JasperReports Server into an existing Tomcat installation on a Windows system running as a Windows Service and the license file is not in the default location, because you didn't choose the default installation directory (2.4, “Choosing Installation Type,” on page 18), manually configure Tomcat to locate the license file. 24 TIBCO Software Inc. Chapter 2 Installing JasperReports Server Follow these steps to examine and update the license location: 1. Open the Tomcat configuration tool by right-clicking the Tomcat icon in your quick-launch bar (usually in the lower-right corner of your desktop) or from the Windows 7 menu, expand Start > All Programs > Apache Tomcat. Right-click Configure Tomcat and select Run as administrator. 2. Select the Java tab. 3. At the bottom of the Java Options field, enter the following option: -Djs.license.directory= For example: -Djs.license.directory=C:\Jaspersoft\jasperreports-server- 4. Stop and restart the application server. You should now be able to run JasperReports Server. 2.11 Starting and Stopping the Server • • • 2.11.1 Start/Stop Menu — Windows Start/Stop Scripts — Linux Start/Stop Apps — Mac OSX Start/Stop Menu — Windows This section describes start and stop procedures that vary depending on whether you installed the bundled Tomcat and PostgreSQL or used your own Tomcat and PostgreSQL. 2.11.1.1 Start/Stop Menus — Bundled Tomcat and PostgreSQL If you installed the bundled Tomcat and PostgreSQL, use the Windows Start menu to start and stop JasperReports Server. • Click Start > All Programs >JasperReports Server> Start or Stop Services then select Start Service or Stop Service. 2.11.1.2 Additional Information about the Bundled Tomcat and PostgreSQL JasperReports Server Windows Service Names: PostgreSQL and Tomcat, installed as Windows Services, are listed in the Windows Services Panel as: • • jasperreportsPostgreSQL jasperreportsTomcat Preventing JasperReports Server from starting up automatically: By default, the bundled services start automatically on a reboot, which also starts JasperReports Server. To change the startup mode for the services from automatic to manual: • • • • In the Windows Services Panel, select jasperreportsTomcat Right-click the jasperreportsTomcat service, and select properties Change the Startup type drop-down setting from Automatic to Manual Do the same for the jasperreportsPostgreSQL service TIBCO Software Inc. 25 TIBCO JasperReports Server Installation Guide To • • • Start JasperReports Server from the Windows Services Panel: Open the Windows Services Panel Select jasperreportsPostgreSQL, click Start Select jasperreportsTomcat, click Start To • • • • Start JasperReports Server from the CMD Shell: Open a Windows CMD Shell Navigate to the root of the folder (C:\Jaspersoft\jasperreports-server-) servicerun START servicerun STOP (to shutdown JasperReports Server) Running Processes: When JasperReports Server is running, the Windows Task Manager lists information about the processes running under the SYSTEM user name: • • postgres.exe tomcat7.exe 2.11.1.3 Start/Stop Scripts — No Bundled Applications During installation, if you chose to install one bundled and one existing Tomcat or PostgreSQL, you can use the Windows start/stop scripts to start and stop only the bundled one. For example, if you have an existing Tomcat and you install the bundled PostgreSQL, the scripts and menus specified in the previous section would start and stop the PostgreSQL application. To start and stop the existing Tomcat, you would use the management scripts provided by the Tomcat application. JasperReports Server requires database and application servers to be started in this order: 1. Database server. 2. Application server. 2.11.2 Start/Stop Scripts — Linux This section describes start and stop procedures that vary depending on whether you installed the bundled Tomcat and PostgreSQL or used your own Tomcat and PostgreSQL. 2.11.2.1 Manual Start/Stop You typically start and stop JasperReports Server at the Linux command line. Run the following commands in a Linux shell. Start JasperReports Server: cd ./ctlscript.sh start Stop JasperReports Server: cd ./ctlscript.sh stop 26 TIBCO Software Inc. Chapter 2 Installing JasperReports Server To start and stop individual components: cd ./ctlscript.sh start|stop ./ctlscript.sh start|stop postgresql tomcat 2.11.2.2 Auto Start/Stop with Bundled Tomcat and PostgreSQL If you want JasperReports Server to start automatically when you reboot your Linux server, you need to install the JasperReports Server database and application server as services. If you have installed JasperReports Server using the binary installer with the bundled Tomcat and bundled PostgreSQL options, you'll find an example jasperserver service script in the following location: /scripts/linux/jasperserver Edit this script and set permissions as described in the /scripts/linux/readme file in the same location. Once installed, these services start automatically when you reboot, which also starts JasperReports Server. 2.11.3 Start/Stop Apps — Mac OSX After you complete the Mac OSX installation, you typically find JasperReports Server installed in the following location: /Applications/jasperreports-serverWhen JasperReports Server is running, you can see the names of the Java and PostgreSQL processes in the Activity Monitor. To start JasperReports Server, locate this folder in Finder and double-click the following app: jasperServerStart.app To stop JasperReports Server, locate this folder in Finder and double-click the following app: jasperServerStop.app The Mac lists the following information in the Activity Monitor: • java or org.apache.catalina.startup.Bootstrap • postgres 2.11.3.1 Start/Stop Apps — Mac Dock Using Finder, move the following apps into the Mac Dock to start, stop, and login to JasperReports Server: • • • jasperServerStart.app jasperServerStop.app jasperServerLogin.app 2.11.3.2 Start/Stop JasperReports Server — Mac Terminal Shell To start and stop JasperReports Server using the Mac terminal shell: 1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon). 2. Navigate to the folder. For instance: /Applications/jasperreports-server- TIBCO Software Inc. 27 TIBCO JasperReports Server Installation Guide 3. To start PostgreSQL, Tomcat, and JasperReports Server, enter: ./ctlscript.sh start 4. To shutdown PostgreSQL, Tomcat, and JasperReports Server, enter: ./ctlscript.sh stop 5. To start and stop individual components: cd ./ctlscript.sh start|stop ./ctlscript.sh start|stop 2.12 postgresql tomcat Logging into JasperReports Server To log into JasperReports Server on any operating system: 1. Start JasperReports Server. 2. Open a supported browser: Firefox, Internet Explorer, Chrome, or Safari. 3. Log into JasperReports Server by entering the startup URL in your browser’s address field. The URL depends upon your application server. If you installed the default, bundled Tomcat use: http:// :8080/jasperserver-pro • • is the name or IP address of the computer hosting JasperReports Server. 8080 is the default port number for the Apache Tomcat application server. If you used a different port when installing your application server, specify its port number instead of 8080. The login page appears. 4. Log in using the following credentials: User ID Password Description superuser superuser System-wide administrator jasperadmin jasperadmin Administrator for the default organization If you installed the sample data, these additional sample end-users are also created. These users are nonadministrative users with fewer system privileges. User ID Password Description joeuser joeuser Sample end-user demo demo Sample end-user for the SuperMart Dashboard demonstration When you complete the evaluation or testing of your JasperReports Server instance, change the administrator and superuser passwords (jasperadmin and superuser) and remove any sample endusers. Leaving the default passwords and end-users in place weakens the security of your installation. 28 TIBCO Software Inc. Chapter 2 Installing JasperReports Server To log into JasperReports Server on Windows: On Windows, you can launch the login page from the desktop of the JasperReports Server host computer by clicking Start > All Programs > JasperReports Server> JasperReports Server Login. To log into JasperReports Server on Mac OSX: On Mac OSX, you can launch the login page by going to Finder and clicking the following script: /Applications/ /jasperServerLogin For example: /Applications/jasperreports-server-/jasperServerLogin To use the Dock to log into JasperReports Server: From Finder, you can drag the /Applications/ /jasperServerLogin.app to the Dock to handle logging into JasperReports Server using your default system browser. 2.13 Log Files Log files contain important information about JasperReports Server operations. If your application server is Tomcat, JBoss, or GlassFish, the log output goes to one of the following files: Tomcat: /webapps/jasperserver-pro/WEB-INF/logs/jasperserver.log JBoss: /server/default/deploy/jasperserver-pro.war/WEB-INF/logs/jasperserver.log GlassFish: /domains/domain1/autodeploy/jasperserver-pro.war/WEB-INF/logs/jasperserver.log You can configure the log output and logging levels in the log4j.properties file in the WEB-INF folder. To change the logging levels while you are running JasperReports Server: 1. Browse to http:// :8080/jasperserver-pro/log_settings.html. The Log Settings page appears. 2. Change logging levels using the drop-down menus. Changes to logging levels affect only the current session of JasperReports Server. Logging levels revert to default settings as defined in the properties files at the next startup. For more information about system logging, see the JasperReports Server Administrator Guide. 2.14 Uninstalling the Server If you install JasperReports Server using the installer executable, you can uninstall it programmatically. 2.14.1 Windows To uninstall JasperReports Server on Windows 7: Click Start > All Programs > JasperReports Server > Uninstall JasperReports Server. 2.14.2 Linux On Linux, the folder includes an executable that removes JasperReports Server from the host. TIBCO Software Inc. 29 TIBCO JasperReports Server Installation Guide To uninstall JasperReports Server: 1. From the command line, log in as the root user (or any user with sufficient privileges). 2. Enter the following commands: cd ./uninstall 3. 2.14.3 Respond Y or yes to the prompt that asks if you want to remove JasperReports Server from this computer. Mac OSX To use Finder to uninstall JasperReports Server: 1. Navigate to the folder. For example: /Applications/jasperreports-server2. 2.14.4 Click the uninstall.app to launch the uninstaller. Uninstall Survey After running the uninstaller, you're prompted to take an uninstall survey from Jaspersoft. Survey answers are anonymous and help us improve our products. When you click Yes, the survey launches on the Jaspersoft web site in a new browser window. Select all the reasons that led you to uninstall JasperReports Server. If none of the reasons apply, enter a short explanation. Thank you for your feedback. 30 TIBCO Software Inc. CHAPTER 3 INSTALLING THE WAR FILE DISTRIBUTION For production environments, use the stand-alone WAR file distribution to install the JasperReports Server application. Download the WAR file distribution from TIBCO Jaspersoft Technical Support (http://support.tibco.com) or contact your sales representative. The WAR file distribution comes in a file named TIB_js-jrs_6.4.0_bin.zip in compressed ZIP format. This chapter contains the following sections: • • • • • • • Applications Supported by the WAR File Distribution Installing the WAR File Using js-install Scripts Additional Steps for Using DB2 and js-install Scripts Starting the Server Logging into the Server Troubleshooting Your Server Configuration Installing the WAR File Manually 3.1 Applications Supported by the WAR File Distribution 3.1.1 Database and Application Server Support The instructions in this and subsequent chapters support the following configurations: Database Application Server Instructions Located In PostgreSQL Apache Tomcat JBossEAP/Wildfly GlassFish This chapter. WebSphere Chapter 5, “Installing the WAR File for WebSphere,” on page 65 WebLogic Chapter 6, “Installing the WAR File for WebLogic,” on page 85 MySQL DB2 Oracle SQL Server Jaspersoft recommends that you use Apache Tomcat with PostgreSQL as your repository, unless you have a strong reason to use another configuration. For version information about these databases and application servers refer to the release notes in the root of the unpacked distribution ZIP. TIBCO Software Inc. 31 TIBCO JasperReports Server Installation Guide 3.1.2 Operating System Support for Bash Shell JasperReports Server is a Java Web Application. Therefore, it supports all operating system platforms where Java is fully supported. However, for the js-install shell scripts (described in the section below), the default shell required is the bash shell. Here is a list of shells required: 3.2 Operating System Required Shell for js-install scripts System Default Shell Script to Run Windows CMD shell CMD shell js-install.bat Linux Bash shell Bash shell js-install.sh Solaris Bash shell Korn shell (ksh) js-install.sh IBM AIX Bash shell Korn shell (ksh) js-install.sh HP UX Bash shell Posix shell (posix/sh) js-install.sh FreeBSD Bash shell C shell (tcsh) js-install.sh Installing the WAR File Using js-install Scripts Follow this procedure to install JasperReports Server using the WAR file distribution. The js-install shell scripts, supported on Windows, Linux, and Mac, do most of the work for you. Prerequisites for installing the WAR file: 1. Install a supported version of the Java Development kit (JDK). See the TIBCO Jaspersoft Platform Support document on the Documentation section of the Jaspersoft Community website for a list. 2. Create and set the JAVA_HOME system environment variable to point to the Java JDK location. 3. Locate or install one of the following application servers: • • • 4. Apache Tomcat 6, 7, or 8 JBoss EAP 6.x or 7.x or Wildfly 8.x, 9.x, 10.x (additional steps may be required for JBoss EAP or Wildfly. Please see 3.4, “Additional Steps for Using JBoss EAP or Wildfly ,” on page 36) Glassfish 4.1 using the default domain (domain1) If you use a custom domain with GlassFish, see A.9.6, “GlassFish Modifications,” on page 114. Locate or install the PostgreSQL, MySQL, Oracle, SQL Server, or DB2 database. If you use DB2, follow the steps in 3.3, “Additional Steps for Using DB2 and js-install Scripts,” on page 35. The target database can be on a remote server. The application server should reside on the local machine. For an optional pre-install validation test, run js-install.bat/sh test. See 3.7.3.1, “js-install Script Test Mode,” on page 39 for more information. 32 TIBCO Software Inc. Chapter 3 Installing the WAR File Distribution To install the WAR file using js-install scripts: The scripts are intended for the bash shell. If installing to non-Linux Unix platforms such as HP-UX, IBM AIX, FreeBSD, or Solaris, the bash shell is required for using the js-install scripts. 1. Extract all files from TIB_js-jrs_6.4.0_bin.zip. Choose a destination, such as C:\Jaspersoft on Windows, /home/ on Linux, or /Users/ on Mac. The directory, TIB_js-jrs_6.4.0_bin, appears in the file location you choose. 2. Copy the _master.properties file for your database from sample_conf and paste it to buildomatic: • Copy from — /buildomatic/sample_conf/ • Paste to — /buildomatic For example, if your database is PostgreSQL, copy postgresql_master.properties to /buildomatic. 3. Rename the file you copied to default_master.properties. 4. Edit the default_master.properties file to add the settings for your database and application server. Table 3-1 lists sample property values for each supported database. Table 3-1 Sample Values for the default_master.properties File Database Sample Property Values PostgreSQL appServerType=tomcat [jboss-eap-6, wildfly, glassfish, skipAppServerCheck] appServerDir=c:\\Program Files\\Apache Software Foundation\\Tomcat 8.0.36 dbHost=localhost dbUsername=postgres dbPassword=postgres MySQL appServerType=tomcat [jboss-eap-6, wildfly, glassfish, skipAppServerCheck] appServerDir=c:\\Program Files\\Apache Software Foundation\\Tomcat 8.0.36 dbUsername=root dbPassword=password dbHost=localhost All Oracle versions other than Oracle 12c with CDB/PDB (including 12c nonCDB) appServerType=tomcat [jboss-eap-6, wildfly, glassfish, skipAppServerCheck] appServerDir=c:\\Program Files\\Apache Software Foundation\\Tomcat 8.0.36 dbUsername=jasperserver dbPassword=password sysUsername=system sysPassword=password dbHost=hostname Oracle 12c with CDB/PDB Use settings for Oracle, except for the following changes: dbUsername=c##jasperserver sid=cdb1 If you are using sample databases: foodmart.dbUsername=c##foodmart sugarcrm.dbUsername=c##sugarcrm TIBCO Software Inc. 33 TIBCO JasperReports Server Installation Guide Database Sample Property Values DB2 appServerType=tomcat [jboss-eap-6, wildfly, glassfish, skipAppServerCheck] appServerDir=c:\\Program Files\\Apache Software Foundation\\Tomcat 8.0.36 dbUsername=db2admin dbPassword=password dbHost=localhost If you use DB2, follow the steps in 3.3, “Additional Steps for Using DB2 and js-install Scripts,” on page 35 For DB2 8.x, change your deployed JDBC driver as described in 4.4, “Locating and Changing Buildomatic Configuration Files,” on page 56. SQL Server appServerType=tomcat [jboss-eap-6, wildfly, glassfish, skipAppServerCheck] appServerDir=c:\\Program Files\\Apache Software Foundation\\Tomcat 8.0.36 dbUsername=sa dbPassword=sa dbHost=localhost Note the following: When the property appServerType is set to skipAppServerCheck, buildomatic skips any application server validation. Backslashes in paths must be doubled in properties files, for example: appServerDir=C:\\Apache Software Foundation\\Tomcat 7. The dbUsername must be the same as the Oracle user name. In addition, buildomatic will not work with the “sys as sysdba” syntax. For Oracle 12c without CDB/PDB, do not use the c##jasperserver dbUsername. Use the standard jasperserver dbUsername instead. On Linux, if Tomcat is installed using apt-get, yum, or rpm, see A.9.5, “Tomcat Installed Using aptget/yum,” on page 113. 5. Password encryption The default_master.properties file has a property setting to enable encryption of passwords that reside on the file system. This applies to all files found under the buildomatic folder, as well as the connection pooling file used by Apache Tomcat (context.xml). Currently, password encryption for connection pooling supports only the Tomcat application server. To enable encryption on the file system, uncomment the encrypt property so it looks like this: encrypt=true For more information about the encryption functionality, refer to the JasperReports Server Security Guide. 6. 34 Run the js-install scripts: a. Start your database server. b. Stop your application server. c. Open Command Prompt as Administrator on Windows or open a terminal window on Linux and Mac OSX. TIBCO Software Inc. Chapter 3 Installing the WAR File Distribution d. Run the js-install script: Commands Description cd /buildomatic js-install.bat (Windows) ./js-install.sh (Linux and Mac OSX) js-install.bat minimal (Windows) ./js-install.sh minimal (Linux and Mac OSX) Installs JasperReports Server, sample data, and sample databases (foodmart and sugarcrm) Installs JasperReports Server, but not the sample data and sample databases For Oracle 12c, do not install sample databases. You must use js-install.bat/sh minimal with Oracle 12c. If you encounter errors during the js-install script execution, see 3.7.3, “Error Running js-install Scripts (js-install.bat/sh),” on page 38. 7. Set Java JVM Options (required), as described in 4.1, “Setting JVM Options for Application Servers,” on page 43. 8. Set up the license (required) as described in 4.2, “Setting Up the JasperReports Server License,” on page 48. To view the output log, look in: /buildomatic/logs/js-install- .log 3.3 Additional Steps for Using DB2 and js-install Scripts The buildomatic scripts cannot automatically connect to a remote DB2 database and carry out Admin operations, so you have to perform additional steps to create the databases. The DB2 client software, db2 or db2cmd, can be used to interact with DB2. 1. Enter commands similar to the ones below in the DB2 command window to create and initialize the repository database, called jsprsrvr in DB2 to conform to the 8-character limitation: db2 create database jsprsrvr using codeset utf-8 territory us pagesize 16384 2. (Optional) Run the following commands in the DB2 command window if you want to install sample databases: db2 create database sugarcrm db2 create database foodmart 3. Continue installing JasperReports Server as described in 3.2, “Installing the WAR File Using js-install Scripts,” on page 32. TIBCO Software Inc. 35 TIBCO JasperReports Server Installation Guide Further considerations: • • If you're using DB2 8.1, set the LOGFIL_SIZ parameter to a minimum of 3000 to avoid possible log file errors while loading the foodmart database. Configure your foodmart database right after creating it by using Control Center. If JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts: /SQLLIB/java/db2jcc.jar 3.4 Additional Steps for Using JBoss EAP or Wildfly If you're using JBoss EAP or Wildfly as your application server and Oracle, SQL Server, or DB2 as your database, an additional set of steps is required to handle the JDBC driver. If you're using a driver different from the one supplied with JasperReports Server, you should have already downloaded a JDBC driver jar for your database type. (See 4.3, “Working With JDBC Drivers,” on page 50, if you have not yet done this.) You need to make an explicit reference to your JDBC driver file name so that JBoss EAP/Wildfly will know the exact file name. 1. Update your default_master.properties file to specify the exact name (artifactId and version) of your JDBC driver: Edit: /buildomatic/default_master.properties Look for the section "Setup JDBC Driver" Uncomment and edit these two lines: # maven.jdbc.artifactId=ojdbc5 # maven.jdbc.version=11.2.0 So that they look like this: maven.jdbc.artifactId=ojdbc5 maven.jdbc.version=11.2.0 (This will work for a driver with the filename: ojdbc5-11.2.0.jar) 2. Edit your jboss-deployment-structure.xml file so that the JDBC filename is specified: Edit: /buildomatic/install_resources/jboss/jboss-deployment-structure.xml Look for the section "Setup JDBC Driver" Uncomment and edit the line for your database type (for instance): So that it looks like this: (This will work for a driver with the filename: ojdbc5-11.2.0.jar) Note: If your JDBC driver filename does not have a version number, you may need to rename the file and give it a version number. For instance, if you have a file named: sqljdbc4.jar You can rename it with a "dummy" version number: sqljdbc4-1.0.jar Then the artifactId and version can look like this: maven.jdbc.artifactId=sqljdbc4 maven.jdbc.version=1.0 36 TIBCO Software Inc. Chapter 3 Installing the WAR File Distribution 3.5 Starting the Server To run JasperReports Server: Start your application server using one of these commands: Tomcat: JBoss: GlassFish: Windows \bin\startup.bat Linux and Mac OSX /bin/startup.sh Windows \bin\standalone.bat Linux and Mac OSX /bin/standalone.sh Windows, Linux, and Mac OSX asadmin start-domain domain1 To view the JasperReports Server application logs, see 2.13, “Log Files,” on page 29. 3.6 Logging into the Server After JasperReports Server starts up, log in by going to this URL: http:// :8080/jasperserver-pro Example: http://localhost:8080/jasperserver-pro http://jasperserver.example.com:8080/jasperserver-pro The login page appears after compiling the necessary JSP files (this will take a few moments). Use the following credentials to log into JasperReports Server: User ID Password Description superuser superuser System-wide administrator jasperadmin jasperadmin Administrator for the default organization If you logged in successfully, your JasperReports Server home page appears. When you complete the evaluation or testing of your JasperReports Server instance, change the administrator and superuser passwords (jasperadmin and superuser) and remove any sample endusers. Leaving the default passwords and end-users in place weakens the security of your installation. Refer to the JasperReports Server User Guide to begin adding reports and other objects to the server. 3.6.1 JasperReports Server Heartbeat After your initial login, you're asked to opt in to the JasperReports Server Heartbeat. The heartbeat helps Jaspersoft understand customer installation environments to improve our products. If you choose to enable the heartbeat, an HTTPS call at server startup time sends information like this to Jaspersoft: • • • Operating System and JVM type and version Application Server and Database type and version JasperReports Server type and version TIBCO Software Inc. 37 TIBCO JasperReports Server Installation Guide • Unique, anonymous identifier value You can manually enable or disable the heartbeat by modifying the following property file jasperserverpro/WEB-INF/js.config.properties. To disable the heartbeat, set the heartbeat.enabled property to false: heartbeat.enabled=false For additional information about enabling and disabling the heartbeat component, see the JasperReports Server Administrator Guide. 3.7 Troubleshooting Your Server Configuration This section helps you troubleshoot the most common installation problems. 3.7.1 Startup Problems If you encounter a problem trying to run a new JasperReports Server, an incorrect database configuration is the likely culprit. Another common cause is a mistake in the application server configuration files. For information about resolving these types of errors, see Appendix A, “Troubleshooting,” on page 101. 3.7.2 Error Running a Report If you have trouble running reports in your new JasperReports Server instance, see “Error Running a Report” in Appendix A, “Troubleshooting,” on page 101. 3.7.3 Error Running js-install Scripts (js-install.bat/sh) The js-install script creates an output log that captures standard output and error output. If you encounter problems during the execution of the script, or if you want to remember which options you chose, open the output log file. To troubleshoot problems running js-install scripts: 1. Open the output log file located in: /buildomatic/logs/js-install- - .log 2. Try to find the first error encountered by the js-install steps. • • 3. Go to the end of the output log. Scroll back through lines of error messages until you find the first error logged. Typically, this error causes more errors later in the log. • Finding the original error is the way to understand the problem. However, this can often be tricky because Java stack traces in conjunction with the Spring application component framework can make the error output quite long. Incorrect settings in the default_master.properties file cause most problems, which you can correct by editing your default_master.properties settings. Common errors are: • • 38 Typos in the path for the application server Misspelling the hostname or password for the database TIBCO Software Inc. Chapter 3 Installing the WAR File Distribution To recreate your default_master.properties settings: 1. Open the file /buildomatic/default_master.properties, make corrections, and save it. 2. Re-run the js-install script. The js-install script uses the current values in the default_master.properties file. To help isolate errors, run the js-install scripts in test mode. 3.7.3.1 js-install Script Test Mode You can run the js-install and js-upgrade scripts in test mode using the test option. In test mode, the js-install scripts check your default_master.properties settings and validate the application server location and connection to the specified database. Using test mode can help debug issues, such as an incorrect database password. Your system isn’t altered when executing the script in test mode. To run the js-install script in test mode on Windows: 1. Navigate to the buildomatic directory: cd /buildomatic 2. Enter the following command to run the js-install script in test mode: js-install.bat test To run the js-install script in test mode on Linux or Mac OSX: 1. Navigate to the buildomatic directory: cd /buildomatic 2. Enter the following command to run the js-install script in test mode: ./js-install.sh test 3.7.4 Problem Connecting to a Cloud Database Instance A cloud database instance (such as Amazon EC2) typically disables unused IP ports. When the js-install script runs, it validates the database hostname using the built-in ant operation . This operation is similar to a network ping and may cause a “hang” issue if the port is unavailable. In this case, the validateHost step can be commented out in the buildomatic/validation.xml file. See the comment in the do-pre-install-test target. 3.8 Installing the WAR File Manually You may need to install the WAR file manually when you cannot use the js-install scripts. The manual buildomatic steps described in this procedure execute the same Ant targets as the js-install scripts (js-install.sh/.bat). The procedure shows which buildomatic targets to execute manually if you are unable to use the js-install scripts. To install the WAR file distribution using manual buildomatic steps: 1. Start your database server. 2. Stop your application server. 3. Create and edit a default_master.properties file to add the settings in for your database and application server as described in 3.2, “Installing the WAR File Using js-install Scripts,” on page 32. TIBCO Software Inc. 39 TIBCO JasperReports Server Installation Guide 4. Open a Command Prompt as Administrator on Windows or open a terminal window on Linux or Mac. Run the following commands: Table 3-2 Buildomatic Targets to Execute to Install the WAR File Commands Description cd /buildomatic Makes the buildomatic directory your current directory. js-ant create-js-db Creates the JasperReports Server repository database. js-ant create-sugarcrm-db (Optional) Creates the sample databases. js-ant create-foodmart-db js-ant load-sugarcrm-db (Optional) Loads sample data into the sample databases. js-ant load-foodmart-db js-ant update-foodmart-db (Optional) Initializes the sample databases js-ant init-js-db-pro js-ant import-minimal-pro Initializes the jasperserver database, loads core application data. Running js-ant import-minimal-pro is mandatory. The server cannot function without this data. js-ant import-sample-data-pro (Optional) Loads the demos that use the sample data. js-ant deploy-webapp-pro Configures and deploys the WAR file to Tomcat, JBoss, or Glassfish. On non-Linux Unix platforms, the js-ant commands may not be compatible with all shells. If you have errors, use the bash shell explicitly. For more information, see A.4, “Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD,” on page 103. If you encounter an error when running create-sugarcrm-db, create-foodmart-db, or create-js-db, you can create the JasperReports Server database manually using the database administration tool for your particular database type. To create the JasperReports Server database manually for PostgreSQL, MySQL, Oracle, SQL Server, or DB2, see Appendix B, “Manually Creating the JasperReports Server Database,” on page 123. If you have previously installed the databases, you can drop the old versions and then recreate the databases. To do this, run the following drop commands before running the commands in Table 3-3 Table 3-3 Buildomatic Targets to Execute to Delete Sample Databases Commands Description js-ant drop-sugarcrm-db (Optional) Deletes the sample databases. js-ant drop-foodmart-db js-ant drop-js-db 40 (WARNING) This will delete the JasperReports Server repository database. Only run this command if you intend to recreate the jasperserver database TIBCO Software Inc. Chapter 3 Installing the WAR File Distribution 5. Set Java JVM Options (required) as described in 4.1, “Setting JVM Options for Application Servers,” on page 43. 6. Set up the license (required) as described in 4.2, “Setting Up the JasperReports Server License,” on page 48. TIBCO Software Inc. 41 TIBCO JasperReports Server Installation Guide 42 TIBCO Software Inc. CHAPTER 4 JVM OPTIONS, LICENSE SETUP, WORKING WITH JDBC DRIVERS This chapter contains the following sections: • • • • • • 4.1 Setting JVM Options for Application Servers Setting Up the JasperReports Server License Working With JDBC Drivers Locating and Changing Buildomatic Configuration Files Configuring Report Scheduling Updating XML/A Connection Definitions Setting JVM Options for Application Servers Java Virtual Machine (JVM) runtime parameters normally need to be explicitly set so that the memory settings have values larger than the default settings. The options and values depend on your version of Java and the application server you use. For a list of supported JDK/JVMs and application servers, see the TIBCO Jaspersoft Platform Support document on the Documentation section of the Jaspersoft Community website. The settings in this section apply specifically to the Oracle/Sun JVM. Other JVMs may or may not have equivalent settings. For the Oracle database, setting the Oracle localization option, defaultNChar, can substantially impact the performance of JDBC queries. If you do not need to support UTF-8 for your Oracle database, you can omit this setting. 4.1.1 Tomcat and JBoss JVM Options The following tables present some typical settings of JVM options that affect JasperReports Server. For information about changing a JVM option setting for your particular environment, see your application server documentation. The following example settings are for 64-bit systems. For 32-bit systems, see “Setting your Java JVM Options” on page 24. TIBCO Software Inc. 43 TIBCO JasperReports Server Installation Guide JVM Options on Windows (64 bit) Options for all app servers set JAVA_OPTS=%JAVA_OPTS% -Xms1024m -Xmx2048m -Xss2m Additional options for JDK 1.7 set JAVA_OPTS=%JAVA_OPTS% -XX:PermSize=32m -XX:MaxPermSize=512m Additional options for JDK 1.8 set JAVA_OPTS=%JAVA_OPTS% -XX:MetaspaceSize=128m For Oracle set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true Additional options for JBoss 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 Additional option for JBoss EAP 6.1 set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl set JAVA_OPTS=%JAVA_OPTS% -XX:+UseConcMarkSweepGC set JAVA_OPTS=%JAVA_OPTS% -XX:+CMSClassUnloadingEnabled JasperReports Server doesn’t provide a virtual X frame buffer on Linux. If your Linux applications are graphical, set the -Djava.awt.headless=true to prevent Java from trying to connect to an X Server for image processing. JVM Options on Linux and Mac OSX (64 bit) Options for all app servers, all JDKs export JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m -Xss2m" Additional options for JDK 1.7 export JAVA_OPTS="$JAVA_OPTS -XX:PermSize=32m -XX:MaxPermSize=512m " Additional options for JDK 1.8 export JAVA_OPTS="$JAVA_OPTS -XX:MetaspaceSize=128m " For Oracle export JAVA_OPTS="$JAVA_OPTS -Doracle.jdbc.defaultNChar=true" Additional options for JBoss export JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl" export JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl" export JAVA_OPTS="$JAVA_OPTS -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl" 44 export JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC" export JAVA_OPTS="$JAVA_OPTS -XX:+CMSClassUnloadingEnabled" TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers JVM Options on Linux and Mac OSX (64 bit) Additional option for JBoss EAP 6.1 export JAVA_OPTS="$JAVA_OPTS -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl" You can set JVM options multiple ways. Sections 4.1.2 - 4.1.4 present step-by-step instructions for performing this task. Alternatively, you can add your JAVA_OPTS settings to any of the following files. File Add JVM Options After This Line on Windows \bin\setclasspath.bat set JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed \bin\setenv.bat JAVA_OPTS setting can go anywhere in this file. \bin\standalone.conf.bat Find the existing JAVA_OPTS line, remove the default memory settings from this line, and add a new line with the recommended JAVA_OPTS after this line. (For example, for JBoss EAP 6.1 on JDK 1.7, remove Xms1303M -Xmx1303M -XX:MaxPermSize=256" and add the recommended settings on a new line.) File Add JVM Options After This Line on Linux /bin/setclasspath.sh JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed /bin/setenv.sh JAVA_OPTS setting can go anywhere in this file. /bin/standalone.conf Find the existing JAVA_OPTS line, remove the default memory settings from this line, and add a new line with the recommended JAVA_OPTS after this line. (For example, for JBoss EAP 6.1 on JDK 1.7, remove Xms1303M -Xmx1303M -XX:MaxPermSize=256 and add the recommended settings on a new line.) TIBCO Software Inc. 45 TIBCO JasperReports Server Installation Guide 4.1.2 Changing JVM Options for Tomcat as a Windows Service If you installed JasperReports Server to use Tomcat running as a Windows service, you can set Java options on the Java Tab of the Tomcat Properties dialog: 1. Launch the Tomcat configuration application. If you installed the bundled Tomcat, you can do this by going to the /apache-tomcat/bin directory and double-clicking the jasperreportsTomcat.exe file. (If you have multiple instances of JasperReports Server installed, the file name will be of the form jasperreportsTomcatnum .exe, for example, jasperreportsTomcatnum2.exe.) If you installed Tomcat using an existing Windows service, look for an .exe file in the same location, with the same name as your Tomcat service, or select the service from the Windows Start menu: Start > Programs > Apache Tomcat > Configure Tomcat (Run as administrator) 2. 3. In the Apache Tomcat Properties dialog, click the Java tab. In the Java Options field, add your JAVA_OPTS values according to the tables above. Enter only the options preceded by -X or -D, not set JAVA_OPTS=%JAVA_OPTS%. Enter only one Java option setting per line. 4. For instance, on JDK 1.7, add options as follows: -Xms1024m -Xmx2048m -XX:PermSize=32m -XX:MaxPermSize=512m -Xss2m These example settings are for 64-bit systems. For 32-bit systems, see “Setting your Java JVM Options” on page 24. 4.1.3 5. Click Apply, then click OK. 6. Stop and restart Tomcat. Changing JVM Options for Bundled Tomcat on Linux If you installed the bundled Tomcat, you can set Java options by editing the appropriate Tomcat configuration script. The steps to change JVM options are: 1. Open the following file for editing: cd /apache-tomcat/scripts/ctl.sh 2. Look for the start_tomcat() function and locate the JAVA_OPTS variable inside it. 3. Modify the JAVA_OPTS values according to the tables above. For example, on JDK 1.7: start_tomcat() { is_tomcat_running ... export JAVA_OPTS="-Xms1024m -Xmx2048m -XX:PermSize=32m -XX:MaxPermSize=512m" export JAVA_OPTS="-Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled" ... } There may be more than one occurrence of the Java_OPTS variable in the ctl.sh file. Make sure you edit the instance inside the start_tomcat() function. 46 TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.1.4 4. Save and close the ctl.sh file. 5. Stop and restart PostgreSQL and Tomcat as described in 2.11, “Starting and Stopping the Server,” on page 25. Changing GlassFish JVM Options The following sections describe how to set the JVM options for GlassFish using the command line or a configuration file. 4.1.4.1 Setting GlassFish JVM Options with the asadmin Command 1. First make sure your GlassFish instance is up and running, then enter the command as a single line. For example, on JDK 1.7: asadmin create-jvm-options -Xms1024m:-Xmx2048m:-XX\:PermSize=32m: -XX\:MaxPermSize=512m:-Xss2m:-XX\:+UseConcMarkSweepGC: -XX\:+CMSClassUnloadingEnabled: -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl: -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl: -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl: -Doracle.jdbc.defaultNChar=true If you're not using an Oracle database, you can omit the last option in the example above. 2. Restart the application server using the following commands: asadmin stop-domain domain1 asadmin start-domain domain1 When running the asadmin create-jvm-options command, you may see error messages like this: [exec] CLI167 Could not create the following jvm options. Options exist: [exec] -Xmx512m [exec] CLI137 Command create-jvm-options failed. This message indicates that one of the options specified was already set in the JVM. The command will succeed for all other JVM options on the command line. No further action is necessary. 4.1.4.2 Setting GlassFish JVM Options by Editing domain.xml 1. Open the /domains/domain1/config/domain.xml configuration file for editing. 2. Add the appropriate lines to the section java-config. For example, on JDK 1.7: -Xms1024m -Xmx2048m -XX:PermSize=32m -XX:MaxPermSize=512m -Xss2 -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl -Doracle.jdbc.defaultNChar=true If you're not using an Oracle database, you can omit the last option in the example above. TIBCO Software Inc. 47 TIBCO JasperReports Server Installation Guide 3. If you're modifying the settings for a running instance of GlassFish, restart the application server using the following commands: asadmin stop-domain domain1 asadmin start-domain domain1 4.2 Setting Up the JasperReports Server License JasperReports Server requires a license and comes with an evaluation license valid for 30 days. Please contact TIBCO Jaspersoft Technical Support (http://support.tibco.com) or your sales representative to get your commercial license. The license file is in the following location:/jasperserver.license The license file specifies the terms of your license, such as the following: • • Expiration date, number of users, and/or number of CPUs Features licensed separately from the basic commercial license, such as multi-tenancy Jaspersoft receives information about your system periodically. The information is used only to monitor compliance with your license. No personal information is collected or transmitted. 4.2.1 Default License Configuration for All Application Servers At startup JasperReports Server automatically looks for the jasperserver.license file in the home directory of the system user running the application server. Table 4-1 lists the application server user home directories for supported operating systems. To configure the license: 1. Stop the application server. 2. Copy the jasperserver.license file in to the directory for your operating system. Table 4-1 License Locations Operating System 48 Linux /home/ / Mac OSX /Users/ / Windows 7 installed from WAR file C:\Users\ \ Windows 7 installed from the binary installer C:\Users\ Windows 7 using an existing Tomcat Windows service C:\ Windows 2003 C:\Documents and Settings\ \ Windows 2008 C:\Documents and Settings\ \ TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.2.2 User-Defined License Location If you prefer to put your license in another directory, modify your application server startup script to set a JAVA_OPT value to explicitly point to that directory. 4.2.2.1 Alternate License Setup for Tomcat If your license is not located in the home directory of the application server user, you can set a JAVA_OPT value to explicitly point to your license. On Windows: 1. In the file \bin\setclasspath.bat, locate the following line: set JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed Alternatively, create an empty file called /bin/setenv.bat. 2. Below that line or in the new file, insert the following line: set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory=" " For example: set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-bin" On Linux and Mac OSX: 1. In the file /bin/setclasspath.sh, locate the following line: JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed Alternatively, create an empty file called /bin/setenv.sh. 2. Below that line or in the new file, insert the following line: export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory= " For example: export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-bin" 4.2.2.2 Alternate License Setup for Bundled Tomcat as a Windows Service The Windows binary installer installs the bundled Tomcat component as a Windows Service by default. The steps to specify a specific folder to hold the jasperserver.license are: 1. Open this file for editing: cd /apache-tomcat/bin/service.bat 2. Look for the second line of two lines that set JVM options, specifically the line which contains the license string. For example, -Djs.license.directory=C:\Jaspersoft\jasperreports-server-. 3. Update the line to point to your license location, for example: -Djs.license.directory=C:\MyLicenses Because Tomcat is installed as a service, you need to re-install the service. From a Windows Command shell, enter these commands (Note: the cmd shell will disappear when these commands are run. You need to open a new cmd shell for each command.). To open a cmd shell: Start Menu > Run... > cmd: cd \apache-tomcat\scripts serviceinstall.bat REMOVE serviceinstall.bat INSTALL The Tomcat service is removed and then installed. After execution of these commands, the service is running. TIBCO Software Inc. 49 TIBCO JasperReports Server Installation Guide 4.2.2.3 Alternate License Location for Existing Tomcat as a Windows Service Windows 7: If you have an existing Tomcat as a Windows Service under Windows 7, copy your license to the root of the C: drive. This is the home folder for the SYSTEM user. The location is: C:\jasperserver.license 4.2.2.4 Alternate License Setup for JBoss If your license is not located in the home directory of the application server user, you can set a JAVA_OPT value to explicitly point to your license. On Windows: 1. In the file /bin/run.bat, locate the following line: set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% 2. Below that line, insert the following line: set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory=" " For example: set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\jasperserver-bin" On Linux and Mac OSX: 1. In the file /bin/run.sh, locate the following line: export JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME" 2. Below that line, insert this line: export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory= " For example: export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/jasperserver-bin" 4.3 Working With JDBC Drivers This section describes how to set up your installation to use a driver other than the default driver. 4.3.1 Open Source JDBC Drivers For open source JDBC drivers, buildomatic is set up to use a single default driver. If you want to use a driver other than the default driver, you can modify the buildomatic property files that determine the default JDBC driver. The buildomatic JDBC driver property files are set up to point to a specific driver jar. This allows for multiple driver jar files in the same buildomatic/conf_source/db/ /jdbc folder. During the installation procedure only the default driver jar is copied to your application server. If you want to use a newer JDBC driver version or a different JDBC driver, you can modify the buildomatic properties seen in your default_master.properties file. 50 TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.3.1.1 PostgreSQL Example The buildomatic/conf_source/db/postgresql/jdbc folder contains these driver files: postgresql-9.2-1002.jdbc3.jar postgresql-9.2-1002.jdbc4.jar If, for instance, you want to change the default driver used by PostgreSQL from type jdbc4 to jdbc3, edit your default_master.properties file: /buildomatic/default_master.properties Uncomment and change: # maven.jdbc.version=9.2-1002.jdbc4 To: maven.jdbc.version=9.2-1002.jdbc3 When you next run a buildomatic command, such as deploy-webapp-pro, the jdbc3 driver will be copied to your application server. 4.3.1.2 MySQL Example The buildomatic/conf_source/db/mysql/jdbc folder contains this driver file: mariadb-java-client-1.1.2.jar If, for instance, you want to use a JDBC driver built and distributed by the MySQL project, such as mysqlconnector-java-5.1.30-bin.jar, you first need to download the driver from the MySQL Connector/J download location: https://dev.mysql.com/downloads/connector/j/ Next, change your buildomatic configuration properties to point to this new driver. Edit your default_master.properties file: /buildomatic/default_master.properties Uncomment and change: # jdbcDriverClass=com.mysql.jdbc.Driver # maven.jdbc.groupId=mysql # maven.jdbc.artifactId=mysql-connector-java # maven.jdbc.version=5.1.30-bin To: jdbcDriverClass=com.mysql.jdbc.Driver maven.jdbc.groupId=mysql maven.jdbc.artifactId=mysql-connector-java maven.jdbc.version=5.1.30-bin TIBCO Software Inc. 51 TIBCO JasperReports Server Installation Guide 4.3.2 Commercial JDBC Drivers As of version 5.6.1, JasperReports Server includes the TIBCO JDBC drivers for the following commercial databases. You can connect to these databases using the TIBCO JDBC driver without additional steps. The driver name is in the \buildomatic\conf_source\db\ \jdbc directory in the following form: • • • Oracle — TIoracle-X.X.jar SQL Server — TIsqlserver-X.X.jar DB2 — TIdb2-X.X.jar These drivers require a valid JasperReports Server license. The driver is for use by JasperReports Server only, and the driver jar must be located under the jasperserver-pro directory, for example, /tomcat/jasperserverpro/web-inf/lib. If you're using the default settings for the driver, you don't need to edit default_master.properties. You can also choose to use the driver supplied by the database vendor as described below. To do this, you must first obtain and install the driver you want, then modify your default_master.properties to use your driver. 4.3.2.1 Download an Optional JDBC Driver Jar To use the driver supplied by the database vendor, you can optionally download and install it. Download Driver Jar from Vendor Website: You can download a commercial JDBC driver from the vendor's website. Here are some sites where you can download packages for supported databases: • • • http://www.microsoft.com/en-us/download/details.aspx?id=11774 (SQL Server) http://www.oracle.com/technetwork/indexes/downloads (Oracle) http://www-01.ibm.com/software/data/db2/linux-unix-windows/downloads.html (DB2) Once you have downloaded your driver, copy it to the correct location and configure your files as described in the sections below. Collect Driver Jar from Existing Application: You may already have a JDBC driver in an application running on your network. If so, you can simply copy that driver jar to the JasperReports Server install location. 4.3.2.2 Oracle Example 1. Copy your Oracle driver to the following directory: /buildomatic/conf_source/db/oracle/native.jdbc 52 2. Change to the /buildomatic directory and open default_master.properties in a text editor. 3. Go to the Additional Settings section in this file. 4. Go to the first setup item, Setup Standard Oracle JDBC Driver. TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 5. Follow the instructions to uncomment the required properties and enable your driver. The following example shows how to set up default_master.properties to point to a driver named ojdbc6-11.2.0.3.jar using SID: # 1) Setup Standard Oracle JDBC Driver # # Uncomment and modify the value to native jdbcDriverMaker=native # # Uncomment and modify the value in order to change the default # 1a) Driver will be found here: /buildomatic/conf_source/db/oracle/native.jdbc # maven.jdbc.groupId=oracle maven.jdbc.artifactId=ojdbc6 maven.jdbc.version=11.2.0.3 If you're using an Oracle service name instead of an SID, uncomment the line serviceName= and add your service name. 6. Save the default_master.properties file. 4.3.2.3 SQL Server Example 1. Copy your SQL Server driver to the following directory: /buildomatic/conf_source/db/sqlserver/native.jdbc 2. Change to the /buildomatic directory and open default_master.properties in a text editor. 3. Go to the Additional Settings section in this file. 4. Go to the first setup item, Setup Standard SQL Server JDBC Driver. 5. Uncomment the required properties and enable your driver. The following example shows how to set up default_master.properties to point to a driver named sqljdbc-1.6.jar: # 1) Setup Standard SQLServer JDBC Driver # # Uncomment and modify the value to native jdbcDriverMaker=native # # Uncomment and modify the value in order to change the default # Driver will be found here: /buildomatic/conf_source/db/sqlserver/native.jdbc # maven.jdbc.groupId=sqlserver maven.jdbc.artifactId=sqljdbc maven.jdbc.version=1.6 6. Save the default_master.properties file. 4.3.2.4 DB2 Example 1. Copy your DB2 driver to the following directory: /buildomatic/conf_source/db/db2/native.jdbc 2. Change to the /buildomatic directory and open default_master.properties in a text editor. 3. Go to the Additional Settings section in this file. 4. Go to the first setup item, Setup Standard DB2 JDBC Driver. 5. Uncomment the required properties and enable your driver. TIBCO Software Inc. 53 TIBCO JasperReports Server Installation Guide # 1) Setup Standard DB2 JDBC Driver # # Uncomment and modify the value to native jdbcDriverMaker=native # # Uncomment and modify the value in order to change the default # Driver will be found here: /buildomatic/conf_source/db/db2/native.jdbc # maven.jdbc.groupId=ibm maven.jdbc.artifactId=db2jcc maven.jdbc.version=9.7 6. Add the following additional properties, setting the correct values for your installation. For example: db2.driverType=4 db2.fullyMaterializeLobData=true db2.fullyMaterializeInputStreams=true db2.progressiveStreaming=2 db2.progressiveLocators=2 dbPort=50000 js.dbName=JSPRSRVR sugarcrm.dbName=SUGARCRM foodmart.dbName=FOODMART 7. 4.3.3 Save the default_master.properties file. Working with Oracle RAC As of JasperReports Server 6.1, you can use Oracle 12c RAC with the TIBCO JDBC Oracle driver. This driver works with Oracle 12c RAC with the following settings: • • Use Oracle 12C for non-CDB/PDB connection settings as described in All Oracle versions other than Oracle 12c with CDB/PDB (including 12c non-CDB). Use js-install.bat/sh minimal with Oracle 12c. This option does not install sample databases. To support additional functionality with Oracle RAC, such as load balancing with multiple servers, you need to configure your application server and manually set up the correct connection URL. 4.3.3.1 Tomcat Load Balancing Example 1. Change to the /webapps/jasperserver-pro/META-INF directory and open context.xml in a text editor. 2. Edit the url property by adding additional connection properties for data sources you want. The following example shows how to set up connection pool to use Oracle RAC with load balancing with a primary server and three alternate servers: jdbc:tibcosoftware:oracle//server1:1521;ServiceName=SERVICE;AlternateServers=(server2:1521,server3:1521,server4:1521);LoadBalancing=true 4.3.3.2 JBoss EAP/WildFly Load Balancing Example 1. Change to the /standalone/deployments/jasperserver-pro.war/WEB-INF directory and open js-jboss7-ds.xml in a text editor. 2. 54 Edit the connection-url tag for the data sources you want. The following example shows how to set up a connection pool to use Oracle RAC with load balancing with a primary server and three alternate servers. TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.3.3.3 Glassfish Load Balancing Example For Glassfish, the URL must be edited from the admin console. 1. Open the Glassfish admin console. The default location is http://hostname:4848 2. Go to Resources > JDBC > JDBC Connection Pools and select the connection pool for the data sources you want. 3. Select the Additional Properties tab and set the url property. For example: jdbc:tibcosoftware:oracle//server1:1521;ServiceName=SERVICE;AlternateServers=(server2:1521,server3:1521,server4:1521);LoadBalancing=true 4.3.3.4 Websphere Load Balancing Example Using the Websphere console, set up the TIBCO Oracle driver as described in 5.2.2, “Defining a JNDI Name and Sample Data Sources for DB2,” on page 75. Then define custom properties as described in Table 5-8, “Custom Properties for TIBCO JDBC Driver for Oracle,” on page 79. For example, set the AlternateServers and LoadBalancing properties. Property Name Value serverName server1 portNumber 1521 ServiceName SERVICE AlternateServers (server2:1521,server3:1521,server4:1521) LoadBalancing true TIBCO Software Inc. 55 TIBCO JasperReports Server Installation Guide 4.3.3.5 WebLogic Load Balancing Example Using the WebLogic console, set up the driver as described in 6.3.1.1, “Configuring a TIBCO JDBC Oracle Connection,” on page 93. Then set the URL property for your servers, for example: jdbc:tibcosoftware:oracle//server1:1521;ServiceName=SERVICE;AlternateServers= (server2:1521,server3:1521,server4:1521);LoadBalancing=true 4.3.4 Application Server Copy-to Locations When the deploy-webapp-pro buildomatic target is executed it copies the JDBC driver to the following default locations: 4.4 Tomcat: jdbc:tibcosoftware:oracle//server1:1521;ServiceName=SERVICE;AlternateServers= (server2:1521,server3:1521,server4:1521);LoadBalancing=true TIoracle-5.14.2.jar jasperserver password 5 50 true false false SELECT 1 FROM DUAL false /lib JBoss: /standalone/deployments Wildfly: /standalone/deployments GlassFish: /domains/domain1/lib/ext Locating and Changing Buildomatic Configuration Files The Ant-based buildomatic scripts contain support files for setting up and configuring a number of databases and application servers. This section describes the locations of some of these files and how to change their content. 4.4.1 Regenerating Buildomatic Settings Whenever you change your default_master.properties file and re-run the js-install scripts (or any other buildomatic target), your generated configuration settings are automatically updated. The generated settings are in this location: /buildomatic/build_conf/default The settings are regenerated automatically based on the updated timestamp on the properties file. If you want to explicitly regenerate your configuration, run the following buildomatic targets: cd /buildomatic js-ant clean-config js-ant gen-config The first target clears the configuration template files in buildomatic/build_conf/default directory. The second re-builds the configuration settings. 4.4.2 Locating Buildomatic-Generated Property Files After you set your database and application server property values, initiate buildomatic to automatically generate the database and application server configuration files needed to prepare for a JasperReports Server installation. The generated property files are in this location: /buildomatic/build_conf/default 56 TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers Some of the key configuration files are: js.jdbc.properties js.quartz.properties js-glassfish-ds.xml js-jboss-ds.xml maven_settings.xml - (used for source code build) More generated property files are: /buildomatic/build_conf/default/webapp Included in the /webapp directory are configuration files, such as: META-INF/context.xml WEB-INF/hibernate.properties WEB-INF/js.quartz.properties These autogenerated files are removed if you run the buildomatic target: clean-config. You can then regenerate the files by running the target: gen-config. (Also, after running clean-config, any subsequent target will regenerate the configuration files.) 4.4.3 Buildomatic Location for JasperReports Server WAR File Buildomatic takes the JasperReports Server WAR file from the root of the directory: /jasperserver-pro.war When you run the deploy-webapp-pro target, buildomatic unpacks the war archive into your application server and copies the needed database configuration files to their appropriate locations. For instance, in the case of Tomcat: 4.4.4 • /jasperserver-pro.war Unpacked and copied to /webapps/jasperserver-pro/* • /buildomatic/build_conf/default/webapp/META-INF/context.xml Copied to /webapps/jasperserver-pro/META-INF/context.xml • /buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties Copied to /webapps/jasperserver-pro/WEB-INF/hibernate.properties • /buildomatic/build_conf/default/webapp/WEB-INF/js.quartz.properties Copied to /webapps/jasperserver-pro/WEB-INF/js.quartz.properties • /buildomatic/build_conf/db/postgres/jdbc/postgresql-9.2-1002.jdbc4.jar Copied to /lib Buildomatic Location for SQL Scripts Buildomatic comes with SQL scripts and other utilities that support a number of databases. These files are in: /buildomatic/install_resources/sql/ For example, some key files are (same pattern for additional databases): /buildomatic/install_resources/sql/postgresql/js-pro-create.ddl /buildomatic/install_resources/sql/postgresql/quartz.ddl /buildomatic/install_resources/sql/postgresql/upgrade-postgresql-6.0.0-6.1.0-pro.sql /buildomatic/install_resources/sql/postgresql/js-pro-drop.ddl TIBCO Software Inc. 57 TIBCO JasperReports Server Installation Guide /buildomatic/install_resources/sql/postgresql/drop-quartz.ddl You can run these scripts manually by copying them to the location of your database client software. 4.4.5 Buildomatic Location for Database Creation Scripts For most databases the buildomatic scripts can create the metadata repository database used by JasperReports Server. This is the database that stores data defining users, roles, data sources, reports, OLAP views, domains, and other data. This database is normally named jasperserver. Buildomatic attempts to create the jasperserver database via JDBC when the create-js-db target is executed. The scripts and property files used to create the jasperserver database are located in the following directory: /buildomatic/conf_source/db/ /scripts.properties 4.4.6 Buildomatic Location for Sample Data Catalog ZIP Files Buildomatic includes export files that hold the JasperReports Server sample data (with examples of new features). This sample data is loaded when you run the buildomatic target import-sample-data-pro, for instance. These export files along with other important export files are located here: /buildomatic/install_resources/export/ Here are some key files: js-catalog- -minimal-pro.zip js-catalog- -pro.zip 4.4.7 Hibernate Properties Settings After you run buildomatic to generate your configuration files, your hibernate.properties settings are in the following directory: /buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties Within the jasperserver-pro WAR file the hibernate.properties file is found at the following location: /jasperserver-pro/WEB-INF/hibernate.properties The buildomatic scripts automatically create this configuration file. When you run the buildomatic target deploy-webapp-pro this file is copied to JasperReports Server in your application server. Hibernate property values are: PostgreSQL: metadata.hibernate.dialect=com.jaspersoft.hibernate.dialect.PostgresqlNoBlobDialect MySQL 5.1: metadata.hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect MySQL 5.5: metadata.hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect DB2: metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.DB2JICustomDialect Oracle: metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.OracleJICustomDialect SQL Server: metadata.hibernate.dialect=com.jaspersoft.ji.hibernate.dialect.SQLServerJICustomDialect 58 TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.4.8 Database Connection Configuration Files 4.4.8.1 Tomcat When you've set up the buildomatic configuration for your database, the Tomcat context.xml will be automatically created with the appropriate settings for JasperReports Server. When you run the buildomatic target deploy-webapp-pro, the context.xml will be automatically copied into the jasperserver-pro WAR set of files. You can view the automatically generated context.xml at the following location: /buildomatic/build_conf/default/webapp/META-INF/context.xml The final location of the context.xml is: /webapps/jasperserver-pro/META-INF/context.xml Older versions of Tomcat will create a copy of the context.xml file with a changed name that will be read instead of the one found in the jasperserver-pro war file. This can be confusing for Tomcat users who try to change their database settings. If you change your settings, delete the file in this location: /conf/Catalina/localhost/jasperserver-pro.xml 4.4.8.2 JBoss When you've set up the buildomatic configuration for your database, the JBoss data source definition file will be automatically created with the appropriate settings for JasperReports Server. When you run the buildomatic target deploy-webapp-pro, the js-jboss-ds.xml will be automatically copied into the JBoss instance. You can view the automatically generated js-jboss-ds.xml at the following location: /buildomatic/build_conf/default/js-jboss-ds.xml The final location of the js-jboss-ds.xml is: /standalone/deployments/jasperserver-pro.war/WEB-INF/js-jboss7-ds.xml When JasperReports Server is running under JBoss, a couple of INFO log messages and an XML/A connection error may occur depending on the version of JBoss you're running. For more information, refer to troubleshooting section A.9.7, “JBoss Modifications,” on page 114. 4.4.8.3 Glassfish After you've set up the buildomatic configuration for your database, the Glassfish data source definition file jsglassfish-ds.xml will be automatically created with the appropriate settings. When you run the buildomatic target deploy-webapp-pro, the file is automatically deployed to the Glassfish instance. You can view the automatically generated js-glassfish-ds.xml at the following location: /buildomatic/build_conf/default/js-glassfish-ds.xml To deploy the data source definition manually, run a command similar to the following: asadmin add-resources " /buildomatic/build_conf/default/js-glassfish-ds.xml" TIBCO Software Inc. 59 TIBCO JasperReports Server Installation Guide 4.5 Configuring Report Scheduling The JasperReports Server report scheduling feature is powered by the Quartz scheduler tool. Buildomatic automatically handles configuration settings for Quartz-based report scheduling. In a deployed JasperReports Server instance, you'll find the js.quartz.properties file in this location: /jasperserver-pro/WEB-INF/js.quartz.properties For mail server configuration, you'll find an additional property setting for authentication in this file: /webapps/jasperserver-pro/WEB-INF/applicationContext-report-scheduling.xml The following configurations are discussed in this section: • • • • • • 4.5.1 Mail Server Configuration Quartz Driver Delegate Class Report Scheduler Web URI Quartz Table Prefix Settings for import-export Setting Properties in the default_master.properties File Mail Server Configuration Settings You can specify email addresses to notify when a report completes. To do this, configure JasperReports Server to contact an email server as shown in the following table. 60 TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers Configuration File / /WEB-INF/js.quartz.properties Property Description report.scheduler.mail.sender.host The name of the computer hosting the mail server report.scheduler.mail.sender.username The name of the mail server user JasperReports Server can use report.scheduler.mail.sender.password The password of the mail server user report.scheduler.mail.sender.from The address for in the From field on email notifications report.scheduler.mail.sender.protocol The protocol that the mail server uses. JasperReports Server supports only SMTP. Note: Your entry must be lower case (smtp) report.scheduler.mail.sender.port The port number the mail server uses. The default is typically 25 (other ports may not work in earlier JasperReports Server versions). Configuration File / /WEB-INF/applicationContext-report-scheduling.xml 4.5.2 Property Bean Description javaMailProperties key="mail.smtp.auth" reportScheduler If your mail server requires authentication, change this property from false to true. MailSender Database Settings for the Quartz Driver Delegate Class Quartz uses the Quartz driver delegate class to interact with the JDBC driver. If you used buildomatic to install JasperReports Server, the correct value of the Quartz driver delegate class is automatically set for your database. TIBCO Software Inc. 61 TIBCO JasperReports Server Installation Guide If you didn’t use buildomatic to install JasperReports Server, refer to the following table to edit the js.quartz.properties file and set the value of the Quartz driver delegate class to the correct value for your database. Configuration File / /WEB-INF/js.quartz.properties Property Database Value quartz.delegateClass MySQL org.quartz.impl.jdbcjobstore.StdJDBCDelegate PostgreSQL org.quartz.impl.jdbcjobstore.PostgreSQLDelegate DB2 org.quartz.impl.jdbcjobstore.DB2v8Delegate Oracle org.quartz.impl.jdbcjobstore.StdJDBCDelegate SQL Server1 org.quartz.impl.jdbcjobstore.StdJDBCDelegate 1. For SQL Server on WebSphere 8.5 use org.quartz.impl.jdbcjobstore.MSSQLDelegate 4.5.3 Settings for the Report Scheduler Web URI JasperReports Server uses the Report Scheduler Web URI to construct the link it sends in the output of a scheduled job. This link must be correct for the user to access the report on the server. The port on which you run JasperReports Server and the context root of the deployed JasperReports Server web application determine the report scheduler Web URI. The default context root is jasperserver. To set this value manually, edit this file: / /WEB-INF/js.quartz.properties. Change the properties as shown in the following table. 62 Property App Server Example Value report.scheduler.web.deployment.uri Apache Tomcat http://localhost:8080/jasperserver-pro JBoss http://localhost:8080/jasperserver-pro GlassFish http://localhost:8080/jasperserver-pro WebLogic http://localhost:7001/jasperserver-pro WebSphere http://localhost:9080/jasperserver-pro TIBCO Software Inc. Chapter 4 JVM Options, License Setup, Working with JDBC Drivers 4.5.4 Settings for the Quartz Table Prefix For databases that support schemas, such as Oracle, SQL Server, and DB2, you can set the Quartz table prefix to include the schema, if you use one. In the default configuration, only DB2 requires an explicit schema name. If you installed JasperReports Server using buildomatic the Quartz table prefix is set automatically. To set this value, edit the file / /WEB-INF/js.quartz.properties. Change the following property: 4.5.5 Property Description quartz.tablePrefix The prefix for the quartz table, including any schema name, for example JSPRSRVR.QRTZ_ for DB2. Settings for Import-Export If you manually configure the import-export shell scripts instead of using the buildomatic, make sure your settings for the Quartz driver delegate class property are correct for your database. If you install using buildomatic, these settings are handled automatically (in buildomatic import-export). To configure the import-export scripts manually, edit this file: /buildomatic/conf_source/iePro/js.quartz.properties Change the following properties: 4.5.6 Property Description quartz.delegateClass Set to the same value as described in 4.5.2, “Database Settings for the Quartz Driver Delegate Class,” on page 61. quartz.tablePrefix Set to the same value as described in 4.5.4, “Settings for the Quartz Table Prefix,” on page 63 Setting Properties in the default_master.properties File You can modify the default_master.properties file to configure JasperReports Server functionality. Uncomment the properties you want to have them take effect upon installation. The properties are documented directly in the default_master.properties file: /buildomatic/default_master.properties You'll find a sample master.properties here (in the case of PostgreSQL): /buildomatic/sample_conf/postgresql_master.properties When you execute the js-install.sh/bat script (or the underlying deploy-webapp-pro ant target), these properties will be set in the deployed JasperReports Server in the js.quartz.properties file. TIBCO Software Inc. 63 TIBCO JasperReports Server Installation Guide 4.5.6.1 Report Scheduler Email Properties You can set the following properties to configure the Report Scheduler email (default values are shown): quartz.mail.sender.host=mail.localhost.com quartz.mail.sender.port=25 quartz.mail.sender.protocol=smtp quartz.mail.sender.username=admin quartz.mail.sender.password=password quartz.mail.sender.from=admin@localhost.com quartz.web.deployment.uri=http://localhost:8080/jasperserver-pro 4.5.6.2 Diagnostic Properties The following properties configure the Diagnostic functionality: diagnostic.jmx.usePlatformServer = false diagnostic.jmx.port = 10990 diagnostic.jmx.name = jasperserver diagnostic.jmx.rmiHost = localhost Look at the descriptions of the properties in the default_master.properties file and also refer to the JasperReports Server Administrator Guide for more information on these settings. 4.6 Updating XML/A Connection Definitions Sample XML/A connections are included with the JasperReports Server sample data. If you plan to use XML/A Web Services in your environment, you may want to update the hard coded values in the sample connections. If you have Jaspersoft OLAP enabled (via your license), JasperReports Server can make XML/A connections over the Web Services interface. These connections need a user account for authentication. You may have different usernames and passwords than the defaults in the sample data. Additionally, your application server hostnames and port may be different than the default values. In such cases, the connections and resources that rely on them will fail. The sample connections are: • • Foodmart Sample XML/A connection SugarCRM Sample XML/A connection To validate and update these resources: 64 1. Log into JasperReports Server as an administrator (like jasperadmin). 2. 3. 4. Navigate to the Repository Management page (View> Repository). Click to expand the Analysis Components folder, then the Analysis Connections folder. Click to highlight Foodmart XML/A Connection, then click Edit. Edit the following fields: 5. • URI (hostname and port) • Login Username • Login Password Click Next, then Save. 6. Make the same updates for SugarCRM XML/A Connection. TIBCO Software Inc. CHAPTER 5 INSTALLING THE WAR FILE FOR WEBSPHERE JasperReports Server supports deployment on the IBM WebSphere Application Server, but requires its own database to store information such as users, organizations, and the repository. WebSphere users must use the WAR file distribution to install JasperReports Server. Download the WAR file distribution from TIBCO Jaspersoft Technical Support (http://support.tibco.com) or contact your sales representative. The WAR file distribution comes in a file named TIB_js-jrs_6.4.0_bin.zip. The WAR file distribution also includes two sample databases containing data for optional demos. For evaluation, Jaspersoft recommends installing the sample databases. In a production environment, you typically don’t install the sample databases. You create and initialize the required repository database and the optional sample databases before JasperReports Server is deployed in WebSphere. The WebSphere administrator uses the WebSphere Administrative Console to deploy JasperReports Server. This chapter contains the following sections: • • • • • 5.1 Procedure for Installing and Deploying the WAR File in WebSphere Logging into the Server Configuring Report Scheduling Updating XML/A Connection Definitions (Optional) Troubleshooting your Configuration Procedure for Installing and Deploying the WAR File in WebSphere Perform the procedures in this section to install and deploy the JasperReports Server WAR file in WebSphere. 5.1.1 Installing WebSphere and a Database To install WebSphere and a database: 1. Make sure you're using a supported version of WebSphere. See the TIBCO JasperReports Server Supported Platform Datasheet for more information. 2. Check that the WebSphere installation created a JAVA_HOME system environment variable. The variable needs to be set to the JAVA directory in the WebSphere installation. 3. Install the database (PostgreSQL, MySQL, Oracle, SQL Server, or DB2). TIBCO Software Inc. 65 TIBCO JasperReports Server Installation Guide The target database can be on a remote server. WebSphere should reside on the local machine. 5.1.2 Preparing Server Files To prepare JasperReports Server files: 1. Unpack TIB_js-jrs_6.4.0_bin.zip to a top-level directory. Unpacking the ZIP file creates the directory TIB_ js-jrs_6.4.0_bin. 2. (Required) Manually create and load the JasperReports Server database. 3. (Optional) Manually create and load the sample databases. See Appendix B, “Manually Creating the JasperReports Server Database,” on page 123 for instructions. 4. (Required) Manually import the default users and organization. a. Copy the _master.properties file for your database from sample_conf and paste it to buildomatic: • cd /buildomatic • Copy from — /buildomatic/sample_conf • Paste to — /buildomatic For example, copy sample_conf/postgresql_master.properties to buildomatic. b. Rename the file you copied to default_master.properties. c. Edit the default_master.properties file: • • • Set appServerType to skipAppServerCheck. Change dbUsername, dbPassword, and dbHost to the appropriate settings for your database. If you're using a port other than the default for your database, or if you've installed the database on a remote machine, change the dbPort field under Custom Properties to the appropriate settings. Each sample_conf/ _master.properties file contains appropriate sample values. d. Start your database server. e. Open a Command Prompt as Administrator and run these commands: Table 5-1 Buildomatic Targets to Execute Commands Description cd /buildomatic Go to the buildomatic directory js-ant create-js-db Create the jasperserver repository database js-ant init-js-db-pro Initializes database, loads core application data js-ant import-minimal-pro 66 js-ant create-sugarcrm-db js-ant create-foodmart-db (Optional) Creates sample databases js-ant load-sugarcrm-db js-ant load-foodmart-db (Optional) Loads sample data into the sample databases js-ant import-sample-data-pro (Optional) Loads the demos that use the sample data TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere 5. 5.1.3 Set up your license file. For information, refer to 4.2, “Setting Up the JasperReports Server License,” on page 48. Configuring CSRFGuard, Hibernate, and Quartz Settings Before deploying the JasperReports Server WAR file, update the CSRFGuard, Hibernate, Quartz, and settings as described here. Configure CSRFGuard, Hibernate and Quartz settings in the WAR file: 1. The WAR file is an archive format in a single file. a. Extract the Websphere.jrs.csrfguard.properties file using the following command: cd "%JAVA_HOME%/bin/jar" xf jasperserver-pro.war WEB-INF/csrf/Websphere.jrs.csrfguard.properties This creates the WEB-INF/csrf folder in the current location and places the extracted file there. b. Rename the file from Websphere.jrs.csrfguard.properties to jrs.csrfguard.properties using the following command: mv ./WEB-INF/csrf/Websphere.jrs.csrfguard.properties ./WEB-INF/csrf/jrs.csrfguard.properties 2. Extract the web.xml file using the commands below: cd "%JAVA_HOME%/bin/jar" xf jasperserver-pro.war WEB-INF/web.xml The jar command creates the WEB-INF folder in the current location and places the extracted file there. Open the WEB-INF/web.xml file for editing and replace every occurrence of javax.sql.ConnectionPoolDataSource withjavax.sql.DataSource For example, change the following:to: JasperServer Metadata repository jdbc/jasperserver javax.sql.ConnectionPoolDataSource Container Do the same for the Supermart and Foodmart databases. TIBCO Software Inc. 67 TIBCO JasperReports Server Installation Guide 3. Copy the already configured files for hibernate.properties and js.quartz.properties to the WEBINF folder. (Buildomatic configured these files for your database type in the steps above.) From: JasperServer Metadata repository jdbc/jasperserver javax.sql.DataSource Container /buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties /buildomatic/build_conf/default/webapp/WEB-INF/js.quartz.properties To: /WEB-INF 4. Edit the scheduler URI port value for WebSphere in the js.quartz.properties: Edit js.quartz.properties: Set : report.scheduler.web.deployment.uri=http://localhost:8080/jasperserver-pro To: report.scheduler.web.deployment.uri=http://localhost:9080/jasperserver-pro 5. If you want to configure JasperReports Server to automatically schedule and email reports, enter your mail server information in the js.quartz.properties file. Modify all report.scheduler.mail.sender.* properties for your mail server. 6. Now that you have modified/updated the individual configuration files, you must replace them in the WAR file archive using the following commands. cd "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/hibernate.properties "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/js.quartz.properties "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/csrf/jrs.csrfguard.properties 7. If you have modified the web.xml file, replace that file in the WAR file archive using the following additional commands. cd "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/web.xml 8. (WebSphere 8 only) If you're using WebSphere 8, enter the following additional commands: cd zip -d jasperserver-pro.war WEB-INF/lib/stax-api-1.0.2.jar zip -d jasperserver-pro.war WEB-INF/lib/jta-1.1.jar 9. 5.1.4 Delete the WEB-INF directory you created, along with the edited files it contains. Configuring a JDBC Provider in WebSphere To configure a JDBC Provider in WebSphere: 1. Launch the WebSphere Administrative Console and navigate to Resources > JDBC > JDBC Providers. 2. On the JDBC providers page, click the Guided Activity link at the top of the JDBC Providers page and follow the Integrated Solutions Console instructions: a. Configure credentials for a secure database: • 68 Use the J2C authentication aliases panel to create a new authenticated user. TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere • In Global Security, click New and enter the user alias, user ID, and password. The following table shows the credentials that WebSphere uses to access the database. Table 5-2 J2C Authentication Alias Settings Alias Example User ID Example Password PostgreSQL postgresql_jasperdb postgres postgres MySQL mysql_jasperdb root password Oracle jasperserver_user jasperserver password DB2 db2admin_user db2admin password SQL Server jasperserver_user sa sa b. Connect to a database panel. From the Scope drop-down, choose Node: ,Server= c. d. Click the New button to create a new JDBC Provider. Select your database type: • • e. If you're using PostgreSQL, MySQL, or a TIBCO JDBC driver — select User-defined. If you want to use the JDBC driver built and distributed by the MySQL project, see 4.3.1.2, “MySQL Example,” on page 51 • If you're using a vendor-supplied driver for DB2, Oracle, or SQL Server — select your database. Select or enter these options. Your options depend on your database type. Database type Implementation class name or type Name User-defined (PostgreSQL) org.postgresql.jdbc2.optional.ConnectionPool PostgreSQL JDBC Provider MySQL com.mysql.jdbc.jdbc2.optional. MysqlConnectionPoolDataSource MySQL JDBC Provider User-defined (MySQL) com.mysql.jdbc.jdbc2.optional. MysqlConnectionPoolDataSource MySQL JDBC Provider User-defined (TIBCO JDBC Oracle) tibcosoftware.jdbcx.oracle.OracleDataSource TIBCO JDBC Provider Oracle User-defined (TIBCO JDBC SQL Server) tibcosoftware.jdbcx.sqlserver.SQLServerDataSource TIBCO JDBC Provider SQL Server User-defined (TIBCO JDBC DB2) tibcosoftware.jdbcx.db2.DB2DataSource TIBCO JDBC Provider DB2 DB2 Universal JDBC Driver Provider Connection pool data source DB2 Universal JDBC Driver Provider TIBCO Software Inc. 69 TIBCO JasperReports Server Installation Guide Database type Implementation class name or type Name Oracle Connection pool data source Oracle JDBC Driver SQL Server Connection pool data source Microsoft SQL Server JDBC Driver 3. Click Next and enter the database classpath information for the JDBC provider. a. For TIBCO JDBC drivers for Oracle, SQL Server, or DB2, locate the correct JAR in \buildomatic\conf_source\db\ \jdbc: • Oracle — \buildomatic\conf_source\db\oracle\jdbc\TIoracle-X.X.jar • SQL Server — \buildomatic\conf_source\db\sqlserver\jdbc\TIsqlserver-X.X.jar • DB2 — \buildomatic\conf_source\db\db2\jdbc\TIdb2-X.X.jar Copy the JAR file to a location in your WebSphere deployment and specify that location for the JDBC driver path. If JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts: /SQLLIB/java/db2jcc.jar b. For PostgreSQL, MySQL, and vendor drivers for Oracle, SQL Server, and DB2, enter the following: \buildomatic\conf_source\db\ \jdbc\ For example, enter: C:\TIB_js-jrs_6.4.0_bin\buildomatic\conf_source\db\postgresql\jdbc\postgresql-9.2-1002.jdbc4.jar Alternatively, you can copy the jar to a location in your WebSphere deployment and specify that location for the JDBC driver path. If JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts: /SQLLIB/java/db2jcc.jar 4. Click Next to proceed to the next step. 5. Review the JDBC provider information you entered and click Finish. To define the JDBC data source and expose it through JNDI: 1. Click the name of the JDBC provider that you just created. For example, for PostgreSQL, click PostgreSQL JDBC Provider. To use a database other than PostgreSQL, configure the database connections and custom properties as described in 5.2, “Configuring Other Database Connections,” on page 74. 70 2. Click Data sources in the Additional Properties of the JDBC provider details panel. 3. 4. To create a new data source, click New. The new data source wizard appears. Enter the data source name: jasperserver 5. Enter the JNDI name: jdbc/jasperserver 6. Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider from the drop-down list. 7. Click Next and accept the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the check box to use this data source in container managed persistence (CMP). 8. Click Next and select the Setup security aliases, as shown in the following table. TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere Field Name PostgreSQL Value Component-managed authentication alias /postgresql_jasperdb Mapping configuration alias DefaultPrincipalMapping Container-managed authentication alias /postgresql_jasperdb 9. Click Next, review the summary information, and click Finish. To set the connection pool size: 1. In the list of JDBC data sources, click the newly created jasperserver data source to edit it. 2. Click Additional Properties > Connection Pool Properties. You'll see that Maximum Connections is set to 10 by default. 3. Set Maximum Connections to 50. You may want to set it to a higher value if necessary. 4. Click Save. To define custom properties: 1. In the list of JDBC data sources, select the check box for the newly created jasperserver data source and click Test Connection. In the Messages area a success or failure message appears. The failure message gives you information about which custom properties you need to define. For example, in the case of PostgreSQL 9.0, a message indicates that the error is related to a null database name. If you are using the TIBCO JDBC driver with SQL Server, and you see an error such as the following: Could not find stored procedure 'master..xp_jdbc_open2' DSRA0010E: SQL State = HY000, Error Code=2,812 Add the following variable to Custom properties: enable2Phase = false 2. Navigate to the jasperserver data sources General Properties page. 3. In Additional Properties on the right side of the General Properties page, click Custom properties. 4. Scroll down the list of properties and select databaseName. Set the value to jasperserver. 5. Set serverName to the correct value for your server. To create optional sugarcrm and foodmart data sources: 1. If you plan to run the sample reports, use the values in the following table to create the foodmart and sugarcrm JNDI data sources. Field Name Value Data source name foodmart sugarcrm JNDI name jdbc/foodmart jdbc/sugarcrm 2. Click Save directly to the master configuration. TIBCO Software Inc. 71 TIBCO JasperReports Server Installation Guide Next, deploy the WAR file in WebSphere as described in 5.1.5, “Deploying the WAR File in WebSphere,” on page 72. 5.1.5 Deploying the WAR File in WebSphere To deploy the JasperReports Server WAR file in WebSphere: 1. In the Administrative Console, navigate to Applications > New Application and select New Enterprise Application. JasperReports Server is a modern application, based on Java Servlet version 2.4, so you do not select the older, WebSphere V4-compliant application type. 2. Browse to /jasperserver-pro.war on the local file system. Keep the default setting (Fast path) selected and click Next. 3. 4. On the Select installation options page, accept all the default settings and click Next. On the Map modules to servers page, make sure the JasperReports Server module is mapped to the cell, node, and server that you want. Click Next. 5. 6. On the Map modules to servers page, select jasperserver. Click Next. On the Map resource references to resources page, map the resources you want: a. First, select the Browse button under the jdbc/jasperserver resource. In the page that opens, select the jdbc/jasperserver radio button, and click Apply. Then select the check box next to the jdbc/jasperserver resource. b. If you plan to run the sample reports, follow the same steps for jdbc/surgarcrm and jdbc/foodmart, making sure to select the correct radio button for each one. c. When you have mapped all resources, select the check boxes next to every resource have mapped. d. Click Next. 7. 8. On the Map virtual hosts page, choose the JasperServer UI application module. Click Next. In the Map context roots for Web modules, enter jasperserver-pro. 9. Click Next, review the summary information and start the installation process. (The installation process may take a while.) 10. Click Save directly to the master configuration. 5.1.6 Setting JVM Options To set the Java JVM Options: For the JasperReports Server XML/A functionality to work, special Java JVM options need to be set to resolve class conflicts between the WebSphere and JasperReports Server web services implementation. JVM options also provide the optimal resources for running JasperReports Server. To configure your Java JVM options: 1. Select Enterprise Applications > jasperserver-pro_war > Target specific application status > (server name). 2. 72 Expand Java and Process Management > Process Definition > Java Virtual Machine > Generic JVM arguments. TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere 3. In the Generic JVM Options text box, paste in the following JVM options that explicitly specify JasperReports Server classes for AXIS and Xalan, as well as optimize JVM resources: Generic JVM Options on Windows Options for all databases -Dclient.encoding.override=UTF-8 -Xms1024m -Xmx2048m -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl Additional for JDK 1.7 set JAVA_OPTS=%JAVA_OPTS% -XX:PermSize=32m -XX:MaxPermSize=512m Additional for JDK 1.8 set JAVA_OPTS=%JAVA_OPTS% -XX:MetaspaceSize=128 Additional for Oracle set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true Generic JVM Options on Linux Options for all databases -Dclient.encoding.override=UTF-8 -Xms1024m -Xmx2048m -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl Additional for JDK 1.7 export JAVA_OPTS="-XX:PermSize=32m -XX:MaxPermSize=512m" Additional for JDK 1.8 export JAVA_OPTS="-XX:MetaspaceSize=128" Additional for Oracle export JAVA_OPTS="$JAVA_OPTS -Doracle.jdbc.defaultNChar=true" Setting the Oracle localization option, defaultNChar, can substantially impact the performance of JDBC queries. If you don't need to support UTF-8 for your Oracle database, you can omit this setting. 4. Click Save on the console task bar. To configure class loading: 1. Select Enterprise Applications > jasperserver-pro_war > Class loading and update detection. 2. In the section Class loader order, select Classes loaded with local class loader first (parent last). 3. 4. (WebSphere 8.x only) In the WAR class loader policy section select Single class loader for application. Save directly to your master configuration. 5. Restart WebSphere. TIBCO Software Inc. 73 TIBCO JasperReports Server Installation Guide Next, start JasperReports Server as described in 5.3, “Starting and Restarting JasperReports Server,” on page 81. 5.2 Configuring Other Database Connections 5.2.1 Defining a JNDI Name and Sample Data Sources for MySQL To define the JDBC data source and expose it through JNDI: 1. Click the name of the JDBC provider that you just created. For example, PostgreSQL JDBC Provider. 2. Click Data sources in the Additional Properties of the JDBC provider details panel. 3. 4. To create a new data source, click New. The new data source wizard appears. Enter the data source name: jasperserver 5. Enter the JNDI name: jdbc/jasperserver 6. Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider or MySQL JDBC Provider from the drop-down list. 7. Click Next and accept the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the check box to use this data source in container managed persistence (CMP). 8. Click Next and select the Setup security aliases: Field Name PostgreSQL Value MySQL Value Component-managed authentication alias /postgresql_jasperdb /mysql_jasperdb Mapping configuration alias DefaultPrincipalMapping DefaultPrincipalMapping Container-managed authentication alias /postgresql_jasperdb /mysql_jasperdb 9. Click Next, review the summary information, and click Finish. To set the connection pool size: 1. In the list of JDBC data sources, click the newly created jasperserver data source to edit it. 2. Click Additional Properties > Connection Pool Properties. You'll see that Maximum Connections is set to 10 by default. 3. Set Maximum Connections to 50. You may want to set it to a higher value if necessary. 4. Click Save. To define custom properties: 1. In the list of JDBC data sources, select the check box for the newly created jasperserver data source and click Test Connection. In the Messages area a success or failure message appears. The failure message gives you information about which custom properties you need to define. For example, in the case of PostgreSQL 9.0 and MySQL, a message indicates that the error is related to a null database name. 74 TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere 2. Navigate to the jasperserver data sources General Properties page. 3. In Additional Properties on the right side of the General Properties page, click Custom properties. 4. Scroll down the list of properties and select databaseName. Set the value to jasperserver. 5. Create a new property called url. Enter the following value and save the change: jdbc:mysql://localhost/jasperserver?useUnicode=true&characterEncoding=UTF-8 6. Click Save directly to the master configuration. To create optional sugarcrm and foodmart data sources: 1. If you plan to run the sample reports, use the values in the following table to create the foodmart and sugarcrm JNDI data sources. Field Name Value Data source name foodmart sugarcrm JNDI name jdbc/foodmart jdbc/sugarcrm 2. 3. Click Save directly to the master configuration. Set the connection pool size as described in “To set the connection pool size” on page 74. Next, deploy the WAR file in WebSphere as described in 5.1.5, “Deploying the WAR File in WebSphere,” on page 72. 5.2.2 Defining a JNDI Name and Sample Data Sources for DB2 To define the JDBC data source and expose it through JNDI: 1. Click the name of the JDBC provider you just created. For example, TIBCO JDBC Provider - DB2 or DB2 Universal JDBC Provider. 2. Click Data sources under the Additional Properties of the JDBC provider details panel. 3. To create a new data source, click New. The new data source wizard appears. 4. Enter the data source name: jasperserver 5. Enter the JNDI name: jdbc/jasperserver 6. 7. Click Next. (If you're using the TIBCO JDBC Provider, skip to step 9.) If you're using the vendor's DB2 driver, choose Select an existing JDBC provider, then select DB2 Universal JDBC Provider from the drop-down list. 8. Click Next and enter these values: Field Name Value Driver type 4 Database name jsprsrvr Server name localhost TIBCO Software Inc. 75 TIBCO JasperReports Server Installation Guide Field Name Value Port number 50000 9. Select Use this data source in CMP and click Next. 10. On the Setup security aliases page, enter the following value for Component-managed authentication alias: /db2admin_user 11. Click Next, review the summary information, and click Finish. To set the connection pool size: 1. In the list of JDBC data sources, click the newly created jasperserver data source to edit it. 2. Click Additional Properties > Connection Pool Properties. You'll see that Maximum Connections is set to 10 by default. 3. Set Maximum Connections to 50. You may want to set it to a higher value if necessary. 4. Click Save. To define custom properties: 1. In the list of JDBC data sources, select the check box for the newly created jasperserver data source, and click Test Connection. 2. In the Messages area a success or failure message appears. The failure message gives you information about which custom properties you need to define. 3. Edit the following properties, adding any that are missing, then save the changes: Table 5-3 Properties for TIBCO JDBC Driver for DB2 Property Name Value alternateID JSPRSRVR batchPerformanceWorkaround true databaseName JSPRSRVR serverName localhost portNumber 50000 To see a list of all properties available for the TIBCO JDBC driver for DB2, see the Progress DataDirect documentation at http://media.datadirect.com/download/docs/jdbc/alljdbc/help.html and navigate to User's Guide > DataDirect Connect Drivers > DB2 Driver > Connection Properties. Table 5-4 Properties for Vendor JDBC Driver for DB2 76 Property Name Value currentSchema JSPRSRVR TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere Property Name Value fullyMaterializeLobData true fullyMaterializeInputStreams true progressiveStreaming 2 progressiveLocators 2 4. Go back to the list of JDBC data sources, select the check box for the jasperserver data source, and click Test Connection. To create optional sugarcrm and foodmart data sources: 1. If you plan to run the sample reports, use the following values to create the foodmart and sugarcrm JNDI data sources. Table 5-5 Field Values for Optional Data Sources for Vendor DB2 Drivers with WebSphere Field Name Value Data source name foodmart sugarcrm JNDI name jdbc/foodmart jdbc/sugarcrm /db2admin_user Component-managed authentication alias Database name foodmart sugarcrm 4 Driver type Server name localhost Port number 50000 selected Use this data source in CMP Table 5-6 Custom Properties for TIBCO JDBC Driver for DB2 with WebSphere Property Name alternateID Value FOODMART batchPerformanceWorkaround databaseName serverName TIBCO Software Inc. SUGARCRM true FOODMART SUGARCRM localhost 77 TIBCO JasperReports Server Installation Guide Table 5-7 Custom Properties for Vendor's Driver for DB2 with WebSphere Property Name currentSchema Value FOODMART 1 resultSetHoldability 2. 3. SUGARCRM Click Save directly to the master configuration. Set the connection pool size as described in “To set the connection pool size” on page 76. Next, deploy the WAR file in WebSphere as described in 5.1.5, “Deploying the WAR File in WebSphere,” on page 72. 5.2.3 Defining a JNDI Name and Sample Data Sources for Oracle To define the JDBC data source and expose it through JNDI: 1. Click the name of the JDBC provider you just created. For example, TIBCO JDBC Provider - Oracle or Oracle JDBC Driver. 2. Click Data sources in the Additional Properties of the JDBC provider details panel. 3. To create a new data source, click New. The new data source wizard appears. 4. Enter the data source name: jasperserver 5. Enter the JNDI name: jdbc/jasperserver 6. 7. Click Next. (If you're using the TIBCO JDBC Provider, skip to step 9.) If you are using the vendor's Oracle driver, choose Select an existing JDBC provider, then select Oracle JDBC Driver from the drop-down list. 8. Click Next and enter the following values: Field Name Value URL jdbc:oracle:thin:@localhost:1521:orcl Data store helper class name Oracle11g data store helper Use this data source in CMP selected 9. Click Next and in Setup security alias, set Component-managed authentication alias to the following value: /jasperserver_user 10. Click Next, review the summary information and click Finish. To set the connection pool size: 1. In the list of JDBC data sources, click the newly created jasperserver data source to edit it. 2. Click Additional Properties > Connection Pool Properties. You'll see that Maximum Connections is set to 10 by default. 78 3. Set Maximum Connections to 50. You may want to set it to a higher value if necessary. 4. Click Save. TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere To define custom properties: 1. In the list of JDBC data sources, select the check box for the newly created jasperserver data source and click Test Connection. In the Messages area a success or failure message appears. The failure message gives you information about which custom properties you need to define. 2. Navigate to the jasperserver data sources General Properties page. 3. 4. In Additional Properties on the right side, click Custom properties. Edit the following properties, adding any that are missing, then save the changes. The following table shows how to set the custom properties if you're using the TIBCO JDBC driver for Oracle: Table 5-8 Custom Properties for TIBCO JDBC Driver for Oracle Property Name Value serverName localhost SID ORCL portNumber 1521 CatalogOptions 0 batchPerformanceWorkaround true To see a list of all properties available for the TIBCO JDBC driver for Oracle, see the Progress DataDirect documentation at http://media.datadirect.com/download/docs/jdbc/alljdbc/help.html and navigate to User's Guide > DataDirect Connect Drivers > Oracle Driver > Connection Properties. 5. Go back to the list of JDBC data sources, select the check box for the jasperserver data source, and click Test Connection. To create optional sugarcrm and foodmart data sources: 1. If you plan to run the sample reports, use the following values to create the foodmart and sugarcrm JNDI data sources: Field Name Value Data source name foodmart sugarcrm JNDI name jdbc/foodmart jdbc/sugarcrm Component-managed authentication alias /foodmart_user /sugarcrm_user Property Name Value portNumber 1521 serverName localhost TIBCO Software Inc. 79 TIBCO JasperReports Server Installation Guide 2. 3. Click Save directly to the master configuration. Set the connection pool size as described in “To set the connection pool size” on page 78. Next, deploy the WAR file in WebSphere as described in 5.1.5, “Deploying the WAR File in WebSphere,” on page 72. 5.2.4 Defining a JNDI Name and Sample Data Sources for SQL Server To define a JDBC provider: 1. Click the name of the JDBC provider you just created. For example, Microsoft SQL Server JDBC Driver. 2. Click Data sources under the Additional Properties of the JDBC provider details panel. 3. To create a new data source, click New. The new data source wizard appears. 4. Enter the data source name: jasperserver 5. Enter the JNDI name: jdbc/jasperserver 6. 7. Click Next. (If you're using the TIBCO JDBC Provider, skip this step.) If you're using the vendor's SQL Server driver, choose Select an existing JDBC provider, then select Microsoft SQL Server JDBC Driver from the drop-down list. 8. Click Next and in Setup security alias, set Component-managed authentication alias to the following value: jasperserver_user 9. Click Next, review the summary information and click Finish. To set the connection pool size: 1. In the list of JDBC data sources, click the newly created jasperserver data source to edit it. 2. Click Additional Properties > Connection Pool Properties. You'll see that Maximum Connections is set to 10 by default. 3. Set Maximum Connections to 50. You may want to set it to a higher value if necessary. 4. Click Save. To define custom properties: 1. In the list of JDBC data sources, select the check box for the newly created jasperserver data source, and click Test Connection. In the Messages area a success or failure message appears. The failure message gives you information about which custom properties you need to define. 2. Navigate to the jasperserver data sources General Properties page. 3. In Additional Properties on the right side of the page, click Custom properties and define properties. The following table shows how to set properties if you are using the TIBCO JDBC driver for SQL Server Table 5-9 Custom Properties for TIBCO JDBC Driver for SQL Server 80 Property Name Value batchPerformanceWorkaround true databaseName jasperserver TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere Property Name Value serverName localhost portNumber 1433 To see a list of all properties available for the TIBCO JDBC driver for SQL Server, see the Progress DataDirect documentation at http://media.datadirect.com/download/docs/jdbc/alljdbc/help.html and navigate to User's Guide > DataDirect Connect Drivers > Microsoft SQL Server Driver > Connection Properties. To create optional sugarcrm and foodmart data sources: If you plan to run the sample reports, use the following values to create the foodmart and sugarcrm JNDI data sources: 1. In the list of JDBC data sources, click the link for the newly created jasperserver data source. 2. 3. Click Save directly to the master configuration. Set the connection pool size as described in “To set the connection pool size” on page 80. Next, deploy the WAR file in WebSphere as described in 5.1.5, “Deploying the WAR File in WebSphere,” on page 72. 5.3 Starting and Restarting JasperReports Server To start the jasperserver-pro application: 1. Restart WebSphere. 5.4 2. In the Administrative Console, navigate to: Applications > Application Types > WebSphere Enterprise Application. 3. Select the check box next to the jasperserver-pro application and click Start. If you make configuration changes to your JasperReports Server instance, restart it. 4. Log into JasperReports Server. Logging into the Server 1. Go to the following URL to log in: http:// :9080/jasperserver-pro Where is localhost, a machine name, or an IP address. The login page should appear after some time to compile the necessary JSP files. 2. Log in with administrative credentials: User ID Password Description superuser superuser System-wide administrator jasperadmin jasperadmin Administrator for the default organization TIBCO Software Inc. 81 TIBCO JasperReports Server Installation Guide If you have trouble logging in and get the following error message, you may be running at a WebSphere patch level that needs further configuration: Page cannot be found, HTTP 404 error Refer to the troubleshooting section A.9.8, “WebSphere Modifications,” on page 117. The first time you log into JasperReports Server, you'll be prompted to opt-in to the JasperReports Server Heartbeat. For more information, refer to 3.6.1, “JasperReports Server Heartbeat,” on page 37. Refer to the JasperReports Server User Guide to begin adding reports and other resources to JasperReports Server. 5.5 Configuring Report Scheduling Scheduled reporting in JasperReports Server allows you to run reports at specified times and gives you the option to send an email notification to users when a new report is available. 5.5.1 Additional Fix for Scheduled Report with JNDI Data Source On the WebSphere application server, reports using a JNDI data source require additional configuration to correctly resolve the JNDI lookup. The jasperserver-pro.war archive includes WebSphere-specific configuration files. These files are generated during the installation process. To enable this fix, you'll need to remove the webSphere prefix from the names of these files. Two of the file rename operations will overwrite the existing configuration file names. Rename: WEB-INF/webSphere-applicationContext-report-scheduling-wm.xml To: WEB-INF/applicationContext-report-scheduling-wm.xml Rename: WEB-INF/webSphere-js.quartz.base.properties To: WEB-INF/js.quartz.base.properties (overwrite existing file) Rename: WEB-INF/webSphere-js.scheduling.properties To: WEB-INF/js.scheduling.properties (overwrite existing file) A work manager class is used to run scheduled report jobs on WebSphere. The JNDI name of the work manager and its default value (wm/default) are configured in js.scheduling.properties. The number of threads that run report jobs is provided by the work manager configuration. 5.5.2 Additional Change for Mail Server Authentication If your mail server requires authentication, edit the applicationContext-report-scheduling.xml file after applying the changes above. 1. Extract the file from the WAR archive: "%JAVA_HOME%\bin\jar" xf jasperserver-pro.war WEB-INF/applicationContext-reportscheduling.xml 82 2. Open the file for editing and locate the reportSchedulerMailSender bean. 3. Set the javaMailProperties key="mail.smtp.auth" value to true. TIBCO Software Inc. Chapter 5 Installing the WAR File for WebSphere 4. Save the file and replace it in the archive: "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/applicationContext-reportscheduling.xml 5. Delete the WEB-INF directory that was created, along with the file it contains. For more information about setting up report scheduling, refer to 4.5, “Configuring Report Scheduling,” on page 60. 5.6 Updating XML/A Connection Definitions (Optional) If you loaded the sample data, and you want to run the Analysis XML/A examples, you'll need to update the XML/A connection resources to use the correct web port. The typical port used by WebSphere is 9080. Follow the procedure in 4.6, “Updating XML/A Connection Definitions,” on page 64. 5.7 Troubleshooting your Configuration 5.7.1 Startup Problems The most common problems are errors in the database configuration. These are typically errors in the database configuration files or in the application server configuration files. For information about resolving these errors, refer to troubleshooting section Appendix A, “Troubleshooting,” on page 101. 5.7.2 Error Running Report If you have trouble running reports in your new JasperReports Server instance, refer to troubleshooting section A.8.12, “Error Running a Report,” on page 111. If you're having trouble running the MDX example Topic or SugarCRM OLAP view, you need to update the port for XML/A connections. See 5.6, “Updating XML/A Connection Definitions (Optional),” on page 83. 5.7.3 Filter Error Using MySQL The following error could be caused by an incorrect ampersand setting on your data source configuration: Error 500: Filter [characterEncodingProxyFilter]: cold not be initialized The data source line needs to have & and not & to be evaluated correctly. That is, the URL you enter in the procedure to define the JDBC data source and expose it through JNDI should look like this: jdbc:mysql://localhost/jasperserver?useUnicode=true&characterEncoding=UTF-8 5.7.4 Error Creating Internationalized Name If you encounter errors when creating resources with internationalized names, and you have an Oracle database, configure your Oracle JDBC driver. Set the Oracle-specific option listed in the tables of 5.1.6, “Setting JVM Options,” on page 72. TIBCO Software Inc. 83 TIBCO JasperReports Server Installation Guide 5.7.5 Xerces Error In earlier releases of JasperReports Server it was possible to find the following error in the WebSphere log: SRVE0068E: Uncaught exception thrown in one of the service methods of the servlet: jasperserver. Exception thrown: org.springframework.web.util.NestedServletException: javax.xml.validation.SchemaFactoryFinder$ConfigurationError: Provider org.apache.xerces.jaxp.validation.XMLSchemaFactory could not be instantiated: org.apache.xerces.impl.dv.DVFactoryException: DTD factory class org.apache.xerces.impl.dv.dtd.DTDDVFactoryImpl does not extend from DTDDVFactory. Since around release 4.0, the xercesImpl jar used is version 2.7.1 and more recently 2.10.0. The error shown above is caused by a conflict between the IBM JDK used by WebSphere and the xercesImpl2.6.2 library bundled with older versions of JasperReports Server. There are two solutions: • Remove the xercesImpl library from the following location: \profiles\AppSrv \installedApps\ \jasperserver-pro_war.ear\ jasperserver-pro.war\WEB-INF\lib • 5.7.6 Update the xercesImpl library to a new version (if it's an old version). OLAP View Fails With Exception The following error may occur because AspectJ needs class loaders to be tried out in a specific order: java.lang.NoSuchMethodError: org/aspectj/runtime/reflect/Factory.makeMethodSig( java/lang/String; ...) org/aspectj/lang/reflect/MethodSignature; Change the default class loader policy: 1. 2. 84 In the WebSphere Administrative Console, navigate to Applications > (app-name) > Manage Modules > JasperServer UI application. Change the following setting: Property Name Value Class loader order Class loaded with local class loader first (parent last) 3. 4. Click OK. Save the master configuration. 5. Restart the WebSphere server. TIBCO Software Inc. CHAPTER 6 INSTALLING THE WAR FILE FOR WEBLOGIC JasperReports Server supports deployment on the WebLogic Application Server, but requires its own database to store information such as users, organizations, and the repository. WebLogic users need the WAR file distribution to install JasperReports Server. Download the WAR file distribution from TIBCO Jaspersoft Technical Support (http://support.tibco.com) or contact your sales representative. The WAR file distribution comes in a file named TIB_js-jrs_6.4.0_bin.zip. The WAR file distribution includes two sample databases containing data for optional demos. For evaluation, Jaspersoft recommends you install the sample databases. In a production environment, you typically don’t install the sample databases. You create and initialize the required repository database and the optional sample databases before deploying JasperReports Server in WebLogic. The WebLogic administrator uses the WebLogic Administrative Console or domain config.xml to deploy JasperReports Server. This chapter contains the following sections: • • • • • • • • • 6.1 Procedure for Installing the WAR File for WebLogic Setting Java Properties Configuring Other Database Connections Starting the Server Logging into the Server Configuring Report Scheduling Restarting the Server Updating XML/A Connection Definitions (Optional) Troubleshooting Your JasperReports Server Configuration Procedure for Installing the WAR File for WebLogic To meet prerequisites for installing the WAR file for WebLogic: 1. Check that a supported version of the Oracle/Sun Java JDK is installed. 2. Check that the JAVA_HOME system environment variable points to the JDK. 3. Install the PostgreSQL, MySQL, Oracle, SQL Server, or DB2 database. The target database can be on a remote server. TIBCO Software Inc. 85 TIBCO JasperReports Server Installation Guide To install the WAR file for WebLogic: 1. Extract all files in TIB_js-jrs_6.4.0_bin.zip into a top-level directory, such as C:\Jaspersoft on Windows or /home/ on Linux. Unpacking the ZIP file creates the directory TIB_js-jrs_6.4.0_bin. 2. Check that WebLogic is installed in the default location on your local machine. If WebLogic is not installed in the default location, or if you encounter problems using the buildomatic scripts, set up the database manually as described in Appendix B, “Manually Creating the JasperReports Server Database,” on page 123. After setting up the database manually, skip step 5 through step 8, and proceed to step 9. 3. (If you're using MySQL, you can skip this step.) Copy your JDBC driver to WebLogic. a. PostgreSQL example: Copy the JDBC jar from /buildomatic/conf_source/db/postgresql/jdbc to /server/lib b. TIBCO JDBC Oracle driver example: Copy the following two jars /buildomatic/conf_source/db/oracle/jdbc/TIoracle-X.X.jar and /buildomatic/install_resources/extra-jars/jswlstc-1.0.jar to /server/lib/ Note that the MySQL JDBC driver is included in recent versions of WebLogic. 4. (If you're using PostgreSQL or MySQL, you can skip this step). If you are using the TIBCO JDBC driver for Oracle, SQL Server, or DB2, you need to add the driver to the WebLogic jdbcdrivers.xml file. To do this: a. Open the file /server/lib/jdbcdrivers.xml in a text editor. b. Add the correct settings for your database. The following example shows the settings for the TIBCO JDBC driver for Oracle. For DB2 or SQL Server, see 6.3.1, “Configuring TIBCO JDBC Driver Connections,” on page 93. 86 c. Save the file. d. Restart WebLogic using the startWebLogic.cmd/sh. TIBCO Software Inc. Chapter 6 Installing the WAR File for WebLogic 5. Copy the .properties file for your database: From — /buildomatic/sample_conf/ To — /buildomatic 6. Rename the file you copied to default_master.properties file. 7. Edit the default_master.properties file to add settings specific to your database and your application server. Table 6-1 shows sample property values. When appServerType = skipAppServerCheck, buildomatic skips the application server type validation. Use this setting when installing JasperReports Server with WebLogic. Backslashes in appServerDir must be doubled, for example C:\\WL\\Application_Server. Make sure there are no spaces in the appServerDir path. Table 6-1 Sample Values for the default_master.properties File Database Sample Property Values PostgreSQL appServerType=skipAppServerCheck appServerDir=[path to WebLogic application server] dbUsername=postgres dbPassword=postgres dbHost=localhost DB2 appServerType=skipAppServerCheck appServerDir=[path to WebLogic application server] dbUsername=db2admin dbPassword=password dbHost=localhost For DB2 8.x, change your deployed JDBC driver as described in4.4, “Locating and Changing Buildomatic Configuration Files,” on page 56. MySQL appServerType=skipAppServerCheck appServerDir=[path to WebLogic application server] dbUsername=root dbPassword=password dbHost=localhost Oracle appServerType=skipAppServerCheck appServerDir=[path to WebLogic application server] sysUsername=system sysPassword=password dbUsername=jasperserver dbPassword=password dbHost=hostname Note that dbUsername must be the same as the Oracle user name. SQL Server appServerType=skipAppServerCheck appServerDir=[path to WebLogic application server] dbUsername=sa dbPassword=sa dbHost=localhost If your application server runs on Java 1.5, change your deployed JDBC driver as described in 4.4, “Locating and Changing Buildomatic Configuration Files,” on page 56. TIBCO Software Inc. 87 TIBCO JasperReports Server Installation Guide 8. Set up the database and optional sample databases using the buildomatic Ant scripts. Enter commands in the table below to call buildomatic Ant scripts: Exception: For DB2, skip this step and perform step 1 to step 3 in B.4, “DB2,” on page 127, then go to the next step (step 9) of this procedure. You call buildomatic Ant scripts from the command line using the following syntax: Windows — js-ant Linux — ./js-ant Commands Description cd /buildomatic Goes to the buildomatic directory. js-ant create-js-db Creates the jasperserver repository database js-ant init-js-db-pro Initializes database, loads core application data js-ant import-minimal-pro js-ant create-sugarcrm-db (Optional) Creates sample databases js-ant create-foodmart-db js-ant load-sugarcrm-db (Optional) Loads sample data into the sample databases js-ant load-foodmart-db js-ant import-sample-data-pro (Optional) Loads the demos that use the sample data On non-Linux Unix platforms, the js-ant commands may not be compatible with all shells. If you have errors, use the bash shell explicitly. For more information, see A.4, “Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD,” on page 103. 9. Add the database driver to your classpath. 10. In WebLogic, open an Administrative Console window and navigate to Services > Data Sources or Domain Configurations > Services > Data Sources. 11. Click New and then Generic Data Source for each of the data source columns in the following table, and enter the following values for a PostgreSQL database. You'll need to click Next after entering the database driver and after One-Phase Commit. To use a database other than PostgreSQL, configure the database connections using settings shown in 6.3.1, “Configuring TIBCO JDBC Driver Connections,” on page 93 or 6.3.2, “Configuring Databases Using the Vendor's Driver,” on page 96. If you plan to use the sample databases (Foodmart and Sugar CRM), perform this step and the following step for each database. 88 TIBCO Software Inc. Chapter 6 Installing the WAR File for WebLogic Parameter Name JasperReports Server Foodmart Example Sugar CRM Example Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase JNDI Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase Database Type PostgreSQL Database Driver PostgreSQL Driver Versions: using org.postgresql.Driver Supports Global Transactions Selected One-Phase Commit Selected 12. Set connection properties. Sample properties for a PostgreSQL database are: Parameter Name JasperReports Server Foodmart Example Sugar CRM Example Database Name jasperserver foodmart sugarcrm Host Name localhost 5432 Port Database User Name postgres Password postgres Confirm Password postgres 13. Test the database connection: a. For SugarCRM and Foodmart, use the default connections: jdbc:postgresql://localhost:5432/sugarcrm jdbc:postgresql://localhost:5432/foodmart b. Change the URL for the jasperserver database to: jdbc:postgresql://localhost:5432/jasperserver 14. Select targets and ensure that AdminServer is set for all data sources. 15. In WebLogic, open an Administrative Console window and navigate to Services > Data Sources or Domain Configurations > Services > Data Sources 16. Select each created data source (JasperServerDataBase, FoodmartDataBase, SugarcrmDataBase) 17. Select the Connection Pool tab and increase the Maximum Capacity setting, depending on load. For most installations, a Maximum Capacity in the range 50 – 100 should be sufficient. If you receive connection pool errors, increase this setting; see the documentation for WebLogic for more information. 18. Click Save. TIBCO Software Inc. 89 TIBCO JasperReports Server Installation Guide 19. Use the Java jar tool or an unzip tool to unpack the jasperserver-pro.war file. For example, using the Java jar tool, enter these commands to unpack the jasperserver-pro.war file to a folder: cd mkdir jasperserver-pro cd jasperserver-pro "%JAVA_HOME%/bin/jar" xvf ../jasperserver-pro.war 20. (If you're using WebLogic 12c, skip this step.) Search for conflicting JARs and delete them from the WAR file. If the following JARs are present in your WebLogic installation, you need to delete them from your JasperReports Server installation to avoid conflicts. To do this: a. Search your WebLogic installation for these files: jaxb-api- .jar jaxb-impl- .jar serializer- .jar stax-api- .jar xalan- .jar xercesImpl- .jar xml-apis- .jar b. Change to the JasperReports Server WEB-INF/lib directory: cd /jasperserver-pro/WEB-INF/lib c. Delete any conflicting JARs. . 21. Update your Hibernate, Quartz, and Mail Server configuration: a. The buildomatic logic has already configured the hibernate.properties and js.quartz.properties files for your database type. So you can copy these files to the jasperserver-pro file as shown below. Copy from: /buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties /buildomatic/build_conf/default/webapp/WEB-INF/js.quartz.properties To: jasperserver-pro/WEB-INF b. Edit the scheduler URI port value for WebLogic in the js.quartz.properties: Edit js.quartz.properties: Set : report.scheduler.web.deployment.uri=http://localhost:8080/jasperserver-pro To: report.scheduler.web.deployment.uri=http://localhost:7001/jasperserver-pro c. If you want to configure JasperReports Server to automatically schedule and email reports, enter your mail server information in the js.quartz.properties file. Modify all report.scheduler.mail.sender.* properties as necessary for your mail server. 22. If your mail server requires authentication, edit the applicationContext-report-scheduling.xml file: 90 a. Open the jasperserver-pro/WEB-INF/applicationContext-report-scheduling.xml file for editing and locate the reportSchedulerMailSender bean. b. Set the javaMailProperties key="mail.smtp.auth" value to true. TIBCO Software Inc. Chapter 6 Installing the WAR File for WebLogic 23. Now you can change to the jasperserver-pro folder and re-archive the jasperserver-pro.war file, using commands such as the following: Commands Description cd ../.. Changes to the jasperserver-pro folder mv ../jasperserver-pro.war ../BAK-jasperserver-pro.war Renames the original jasperserver-pro.war file. "%JAVA_HOME%/bin/jar" cvf ../jasperserver-pro.war * Re-archives the jasperserverpro.war file. cd .. Renames the unneeded working folder to a backup location. mv jasperserver-pro BAK-jasperserver-pro You now have a jasperserver-pro.war file you can use for deploying to WebLogic. 24. Edit your WebLogic domain configuration file /config/config.xml: is the path of the domain within WebLogic that contains your JasperReports Server deployment. For example /samples/domains/wl_server. a. Locate the server and security-configuration elements, and insert the following parameters: ... 1200 ... b. Check that the stuck-thread-max-time element appears above the listen-address element before the closing tag. In some cases, setting the stuck-thread-max-time may cause a schema validation error. In this case, you can try removing this line from the configuration file. 25. Set JVM options as described in 6.2, “Setting Java Properties,” on page 92. Deploy JasperReports Server to WebLogic: 1. Enable the Lock & Edit button: a. Select the Preferences link at the top of the Admin console b. Scroll to the bottom of the User Preferences screen and deselect Automatically Acquire Lock and Activate Changes. Save. c. TIBCO Software Inc. 91 TIBCO JasperReports Server Installation Guide 6.2 2. In the Administrative Console, click the Lock & Edit button and navigate to Deployments. 3. On the Deployments page click the Install button. 4. Select the path tofalse . Click Next. 5. 6. Leave the radio button selected for Install this deployment as an application. Click Next. When prompted, enter the following parameter values: Parameter Name Example Value Name jasperserver-pro Security Custom Roles and Policies Source accessibility Use the defaults defined by the deployment's targets 7. Review your choices and click Finish. 8. Click Save. Setting Java Properties Edit the WebLogic startup script for your platform to include the settings described in the following tables. Substitute the location of your JasperReports Server license file where necessary: WebLogic Startup Settings on Windows Filename \bin\startWebLogic.cmd Settings set JAVA_OPTIONS=%JAVA_OPTIONS% -Djs.license.directory=C:\ \ -Dfile.encoding=UTF-8 -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0 -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl -Xms1024m -Xmx2048m -Xss2m Additional for JDK 1.7 set JAVA_OPTIONS=%JAVA_OPTIONS% -XX:PermSize=128m -XX:MaxPermSize=512m Additional for JDK 1.8 set JAVA_OPTIONS=%JAVA_OPTIONS% -XX:MetaspaceSize=128m Additional for Oracle set JAVA_OPTIONS=%JAVA_OPTIONS% -Doracle.jdbc.defaultNChar=true Setting the Oracle localization option, defaultNChar, can substantially impact the performance of JDBC queries. If you don't need to support UTF-8 for your Oracle database, you can omit this setting. 92 TIBCO Software Inc. Chapter 6 Installing the WAR File for WebLogic WebLogic Startup Settings on Linux Filename /bin/startWebLogic.sh Settings export JAVA_OPTIONS="$JAVA_OPTIONS -Djs.license.directory=/home/ /weblogic/jasperlicense/ -Dfile.encoding=UTF-8 -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0 -Djavax.xml.soap.SOAPConnectionFactory=org.apache.axis.soap.SOAPConnectionFactoryImpl -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl -Djavax.xml.soap.SOAPFactory=org.apache.axis.soap.SOAPFactoryImpl -Xms1024m -Xmx2048m -Xss2m" Additional for JDK 1.7 export JAVA_OPTIONS="$JAVA_OPTIONS -XX:PermSize=128m -XX:MaxPermSize=512m " Additional for JDK 1.8 export JAVA_OPTIONS="$JAVA_OPTIONS -XX:MetaspaceSize=128m " For Oracle export JAVA_OPTIONS="$JAVA_OPTIONS -Doracle.jdbc.defaultNChar=true" Setting the Oracle localization option, defaultNChar, can substantially impact the performance of JDBC queries. If you don't need to support UTF-8 for your Oracle database, you can omit this setting. 6.3 Configuring Other Database Connections 6.3.1 Configuring TIBCO JDBC Driver Connections 6.3.1.1 Configuring a TIBCO JDBC Oracle Connection If you're using the TIBCO JDBC driver for Oracle, add the driver to the WebLogic jdbcdrivers.xml file as described in step 4in 6.1, “Procedure for Installing the WAR File for WebLogic,” on page 85 To use the driver, select DataDirect's Oracle Driver (Type4) from the menu after step 10 in 6.1, “Procedure for Installing the WAR File for WebLogic,” on page 85 and enter the following properties: Parameter Name JasperReports Server Foodmart Example Sugar CRM Example Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase JNDI Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase TIBCO Software Inc. 93 TIBCO JasperReports Server Installation Guide Parameter Name JasperReports Server URL Sugar CRM Example jdbc:tibcosoftware:oracle://localhost:1521;SID=ORCL tibcosoftware.jdbc.oracle.OracleDriver Driver Class Name Properties Foodmart Example SID=ORCL SID=ORCL SID=ORCL user=jasperserver user=foodmart user=sugarcrm CatalogOptions=0 CatalogOptions=0 CatalogOptions=0 Make sure Test Table Name is blank. If it says SQL Null, delete this. 6.3.1.2 Configuring a TIBCO JDBC DB2 Connection If you're using the TIBCO JDBC driver for DB2, add the following information to the WebLogic jdbcdrivers.xml file, as described in step 4 in 6.1, “Procedure for Installing the WAR File for WebLogic,” on page 85 To use the driver, select the TIBCO driver for DB2 from the menu after step 10 in 6.1, “Procedure for Installing the WAR File for WebLogic,” on page 85 and enter the following properties. For the URL, enter the value of the databaseName lower in the table. For example, for the jasperserver database, the URL is jdbc:tibcosoftware:db2://localhost:50000;databaseName=jsprsrvr;AlternateID=jsprsrvr Parameter Name JasperReports Server Foodmart Example Sugar CRM Example Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase JNDI Name JasperServerDataBase FoodmartDataBase SugarcrmDataBase URL jdbc:tibcosoftware:db2://localhost:50000;databaseName= ;AlternateId= Driver Class Name 94 tibcosoftware.jdbc.db2.DB2Driver TIBCO Software Inc. Chapter 6 Installing the WAR File for WebLogic Parameter Name JasperReports Server Foodmart Example Sugar CRM Example Properties user=db2admin user=db2admin user=db2admin alternateID=JSPRSRVR alternateID=FOODMART alternateID=SUGARCRM portNumber 50000 databaseName jsprsrvr foodmart sugarcrm alternateId jsprsrvr foodmart sugarcrm serverName localhost batchPerformance Workaround true Make sure Test Table Name is blank. If it says SQL Null, delete this. 6.3.1.3 Configuring a TIBCO JDBC SQL Server Connection If you're using the TIBCO JDBC driver for SQL Server, add the following information to the WebLogic jdbcdrivers.xml file, as described in step 4 in 6.1, “Procedure for Installing the WAR File for WebLogic,” on page 85