JasperReports Server Installation Guide<>

Installation

System Requirements

Table 3 lists the system requirements, which are taken from the JasperReports Server Installation Guide and are reproduced here for your convenience. It is recommended that you read the installation guide prior to installation of JasperReports Server.

Table 3: System Requirements

Resource

Footprint

Minimum

Recommended

Disk

Approximately 1.3 GB

10 GB Free

40 GB plus

RAM

4GB

8 GB plus

Processor

Two core minimum

2.5GHz and multi-core Pentium for Windows, Mac and Linux

Installation Procedure

Bundled Installer

The JasperReports Server Installation Guide is an excellent resource for this type of installation, which you should read carefully when choosing it.

At a high-level, the installation can be broken down into:

Pre-installation steps

Starting the installer

Accepting the license agreement

Choosing an installation type

Selecting the Apache Tomcat configuration

Selecting a PostgreSQL configuration

Installing sample data

Completing the installation

Post-Installation Steps

Starting and stopping the JasperReports Server

Logging into the JasperReports Server.

See the Post-Installation Tasks section for further configuration tasks related to Ellucian Quercus.

WAR file distribution Installation

Please refer to “Chapter 3 – Installing the WAR File Distribution” of the JasperReports Server Installation Guide for detailed instructions and options for the deployment of the WAR file.

This section assumes that you will install the WAR distribution file in an Ellucian Quercus environment using:

Linux

Apache httpd version 2.4

Apache Tomcat 8

Oracle REST Data Services 2.0.10

JasperReports Server 6.1.1

It is assumed that you are familiar with the installation procedures for Ellucian Quercus using Apache httpd, Apache Tomcat, and Oracle REST Data Services. This section will focus on the JasperReports server installation specifics.

Ellucian Quercus Installation Procedure (Abbreviated)

1Ensure that a supported version of the JDK is installed on your server.

2Download, install, and configure Apache httpd – if possible Ellucian recommends using a yum repository as it makes upgrades much easier.

1Configure the virtual hosts that you intend to use.

2Configure the document root and images directory for APEX and QUERCUS.

3Copy the APEX and QUERCUS images to the designated directory.

4In your virtual hosts file, configure a location for all Ellucian Quercus applications, for example “/app” and then configure a proxypass from this location to Tomcat using the AJP protocol.

3Download, install and configure Apache Tomcat.

1If web-facing, harden your Tomcat server by removing the Manager, Admin and Security Applications from the../webapps/ directory.

4Download, install, and configure Oracle Rest Data Services.

1Rename ords.war to app.war and deploy the WAR file to the webapps directory.

2Configure ORDS to connect to the Ellucian Quercus database (see the Oracle REST Data Services Installation and Configuration Guide for details).

3Configure ORDS url-mapping as per the configuration section of the Oracle REST Data Services Guide.

JasperReports Server Procedure

1Set-up the HTTP configuration.

1Configure a new Location called /jaspersoft in the vhosts file on your httpd installation and configure it to proxyPass to the jasperserver-pro application on Tomcat.

Note: Remember that jasperserver-pro is the default name, you may decide to change it but it needs to be reflected in your vhosts configuration file.

Here is a sample configuration.

      <VirtualHost *:443>
ServerName server.domain.com
ServerAlias server.domain.com
DocumentRoot "/var/www/html/assets"
      #Quercus Configuration
      <Location /app>
# Reverse proxy
# switch over to tomcat
ProxyPass ajp://localhost:8009/app
</Location>
      #Location for JasperSoft Reporting
<Location /jasperserver-pro>
# Reverse proxy
# switch over to tomcat
ProxyPass ajp://localhost:8009/jasperserver-pro
</Location>
      </VirtualHost>

2Configure a Repository Database for JasperReports Server.

1The supported databases are PostgreSQL, MySQL, DB2, Oracle, and SQL Server.

2Stand-up an empty database instance and ensure that it can be accessed from the web server where JasperReports Server will be deployed.

3DBA access to the database instance is required during JasperReports Server deployment, so ensure that you record any system administrator passwords, as they will be required.

3JasperReports Server Deployment.

1Download the WAR archive (generic) ZIP file for JasperReports Server v6.1.1 from the Jaspersoft support centre.

2Make a new directory on the web server in a location of your choice. In this document, this directory is referred to as JS-STAGE.

1So for example, JS-STAGE is /tmp/jasperserver.

2After installation, do not delete this directory as it will be needed for post-installation tasks.

3Unzip the downloaded file to the JS-STAGE directory

4Copy the file JS-STAGE/jasperreports-server-6.1.1-bin/buildomatic/sample_conf/db_choice_master.properties to JS-STAGE/jasperreports-server-6.1.1-bin/buildomatic (the string db_choice will depend on the database technology used for the repository database).

5Rename the file that you have copied in the previous step to default_master.properties.

6Edit the default_master.properties file and add the settings that are relevant to your database repository and application server.

Table 4 provides sample settings that are defined in the default_master.properties file for an Oracle database instance.

Table 4: Sample defaults_master.properties Settings

Setting

Value

Comment

appServerType

Tomcat8

appServerDir

/etc/tomcat8

CATALINA_HOME

/usr/share/tomcat8

CATALINA_BASE

/usr//share/tomcat8

dbType

oracle

dbUsername

jasperserver

A schema will be created in your repository database with this name.

dbPassword

********

Specify the password for the user name defined using dbUsername.

sysUsername

sys

Specify a user that has system admin access to your repository database.

sysPassword

********

Specify the password for the user defined using sysUsername.

dbHost

Some.domain.com

The host name or IP address of your database server.

dbPort

1521

sid

ORCL

encrypt

TRUE

The TRUE value encrypts the passwords in the installation files and deployment files.

This is the recommended value for production instances.

propsToEncrypt

dbPassword, sysPassword

Set this when using Oracle and you want to encrypt the password.

7Run the js-install scripts.

1Ensure that the repository database instance is running and accessible.

2Stop your application server, for example, using this command:

         sudo service tomcat8 stop
          

3Go to the JS-STAGE/jasperreports-server-6.1.1-bin/buildomatic directory.

4Run the.sh executable file js-install.sh, for example:

         sudo./js-install.sh minimal
          

Use the minimal option if you do not want the sample data installed. This is preferable for production environments and speeds up the installation.

You also have the option of running the install command in test mode to check that the values in default_master.properties are correct and validate the application server location and connection to the repository database.

To run in test mode, include the test option, for example:

         sudo./js-install.sh test
          

The installation process takes some time to complete. In some test cases where sample data was installed, the process took up to 30 minutes.

Once the installation has completed successfully you will see a message like this:

         BUILD SUCCESSFUL
         Total Time: 29 minutes 37 seconds
         Checking Ant return code: OK
         ------------------------------------------------------
         [user1@host1 buildomatic]$

High Availability

If you want to install JasperReports Server in a high availability environment, please review the document Sample Cluster Architecture authored by the Jaspersoft Community (http://community.jaspersoft.com/).

See the Post-Installation Tasks section for further configuration tasks related to Ellucian Quercus.

Starting the JasperReports Server

Once the build is successful, you can start the server.

1Start the application server by issuing the standard start-up command, the build will have deployed the required files to the appropriate directories so the application will start-up on server start. For example:

   sudo service tomcat8 start
    

2Monitor the standard log files for any error during start-up:

   sudo tail /var/log/tomcat8/catalina.out -f -n40
    

3Once started, the JasperReports server will be accessible via a browser, for example:

   https://server.domain.com/jasperserver-pro/login.html
    

By default, JasperReports Server sets a superuser user with a password of superuser for first login. It is strongly recommended that this password is changed at the earliest possible opportunity.

Upon login, you might encounter a message relating to an out of date license. If you do, obtain the appropriate license key. Once you have the license key simply replace the existing jasperserver.license file with the new file.

Post-Installation Tasks

Decorator JSP Files

The following JSP files are available in Ellucian Quercus Version 8.5.0 (SU4628):

decorator.jsp

minimalDecorator.jsp

decoratorMinimalComponents.jsp

decoratorCommonComponents.jsp

These files must be copied to the web server into the directory../webapps/jasperserver-pro/WEB-INF/decorators, overwriting the existing files.

Installing Oracle JDBC Drivers

Before you can create a connection to your Ellucian Quercus database, you will need to install the latest Oracle JDBC driver to the JasperReports Server.

1Download the latest Oracle JDBC driver from Oracle.

2Log into the JasperReports server as superuser.

3Under Data Sources, click Create.

4Select JDBC Data Source from the Type drop-down list.

5Select 'NOT INSTALLED: Oracle (oracle.jdbc.OracleDriver) from the JDBC Driver list, and then click the Select Driver button.

6You will be prompted to select the JDBC driver that you downloaded in Step 1.

7Click Upload.

8The driver will be uploaded and registered.

9The JDBC Driver for Oracle is now available for use.

Import Ellucian Quercus Related Resources

Bundled with Ellucian Quercus 8.5.0 (SU4628) is a collection of resources that are designed to facilitate seamless integration between JasperReports server and Ellucian Quercus. These resources include:

a public data source definition

pixel perfect reports

themes for JasperReports Server

You must import these resources into the JasperReports server.

1Copy the directory../embedded_reports/jaspersoft from SU4628 to a location on the JasperReports Server.

2Go to the JS-STAGE/jasperreports-server-6.1.1-bin/buildomatic directory.

3Import the zipped files from the../embedded_reports/jaspersoft directory using the js-import utility in the buildomatic directory.

1There are a number of sub-directories in this directory, five of which contain ZIP files.

2The order in which they should be imported is:

1data_sources

2domains

3adhoc_views

4documents

5themes

3Use the following command to import each ZIP file separately, replacing the terms as appropriate:

      js-import --input-zip /path/jaspersoft/directory/zip-file.zip
       

For example:

      js-import.sh --input-zip /tmp/jaspersoft/documents/student_transcipt.zip

Enabling Single Sign-on between Ellucian Quercus and JasperReports Server

Overview

The following steps summarize how token based authentication is achieved when accessing JasperReports server reports from Ellucian Quercus, thus allowing single sign-on:

Ellucian Quercus creates a URL which includes an encrypted token.

An organisation ID is appended to the end of this token, in plain text.

The JasperReports server is already configured to decrypt the token by retrieving a key from a key store on the web server, for the given organisation ID.

If the token is successfully decrypted, and the organisation ID is valid, an attempt is made to log into the JasperReports server with the credentials included in the token.

Figure 1: Jaspersoft Token Based Authentication Set-up

Configuration

There are a number of configuration steps that you must complete to enable single sign-on between Ellucian Quercus and JasperReports Server. These are:

1Configure the keystore that will contain the organisation's credentials.

2Add new environment variables to the CONTEXT.XML file in Tomcat.

3Copy the ellucian-1.1.0.jar JAR file to the JasperReports server

4Copy the applicationContext-externalAuth-preAuth-mt.xml file to the JasperReports server.

Each step is described in more detail in the subsequent sections.

Step 1: Configure the Keystore

Ellucian Quercus Version 8.5.0 (SU4628) includes a Java application that will generate a keystore.

This application is located in the directory../su4628/embedded_reports/jaspersoft/config/, which contains the following files:

ellucianKeyStore.jar – a Java executable file.

customers.lst

To create the keystore:

1Edit the customers.lst file and add an organisation ID of your choice. (For example, for test database connection TEST and for production PROD).

2Double-click the Java executable file ellucianKeyStore.jar.

1You will be prompted for a password.

2Add a password (and take note of it) as it is required for the configuration of CONTEXT.XML.

3The executable will create two files:

ellucian.ks – this is the keystore that is copied to the web server.

set-js-org-id-and-key-org-id.sql – this file is found under../sql/org-id in the directory where you ran the Java executable, where org-id is the organization ID. You must run this SQL file as the Ellucian Quercus user against the nominated database instance. Ensure that you “commit” after running this script.

4Copy the ellucian.ks file to the application server and add it to the WEB-INF directory of the JasperReports server application, for example $CATALINA_HOME/webapps/jasperserver-pro/WEB-INF. If using Linux, ensure that the owner of the file is the same owner as the other files in this directory.

Step 2: Add New Environment to CONTEXT.XML

There are two new environment variables that you need to add to the CONTEXT.XML file. These environment variables give the details of the keystore to the JasperReports server.

1Locate the file CONTEXT.XML; which is usually found in the $CATALINA_HOME/conf directory.

2Create a backup copy of the file.

3Edit the file and add the following entries (bold) at the bottom of the file

   <Context>
   …...
   <Environment name="ellucianKeyStorePath" value="../ellucian.ks" type="java.lang.String"       override="false" />
   <Environment name="ellucianKeyStorePwd" value="KeyStorePasswordHere" type="java.lang.String"       override="false" />
   …...
   </Context>

4Replace the location of the keystore with the correct directory path and file name.

5Replace the password value with the correct password. This is the password that you entered when creating the keystore.

6Save and exit the file.

Step 3: Copy JAR File to Web Server

1Locate the file ellucian-1.1.0.jar in the../SU4628/embedded_reports/jaspersoft/config/lib directory.

2Copy this file to the.../jasperserver-pro /WEB-INF/lib directory on the web server.

3Ensure that the ownership of the file is the same as the other files in that directory.

Step 4: Copy applicationContext-externalAuth-preAuth-mt.xml to the Web Server

1Locate the file applicationContext-externalAuth-preAuth-mt.xml in the../SU4628/embedded_reports/config/web-inf directory.

2Copy this file to the …/jasperserver-pro/WEB-INF directory on the web server.

3Ensure that the ownership of the file is the same as the other files in that directory.

Setup Organisation and Initial User in JasperReports Server

Setup Organisation

1Connect to the JasperReports Server as the superuser.

2Select Manage | Organisations from the menu bar.

3Click the Add Organisation button.

4Add the required fields:

1Organisation Name – your preferred organisation name

2Organisation ID – this must match an Organisation ID that you used when creating the keystore

3Organisation Alias – your preferred alias

5Click Add Organisation.

Set-up the Initial User

The initial user is the user that is used to connect to your data source, for example the Ellucian Quercus database instance.

1Select the organisation that you just created and click the Edit button.

2Select the Attributes tab in the right-hand pane.

3Add the attributes listed in Table 5 and provide a value for each attribute. You can encrypt the values listed in this table by selecting the corresponding Encrypted check box in the UI.

Table 5: Initial User Attributes

Attribute Name

Comment (for Value field)

host

Add the IP address or host name of the database server for Ellucian Quercus.

port

Add the port used to communicate with the database, the default Oracle port is 1521.

db

Add the service name of the database instance.

db_username

Add a user name with access to all tables and views in the Ellucian Quercus schema.

db_password

Add the password for the user defined with the db_username attribute.

4Click Save and Exit JasperReports Server.

Set the Theme in JasperReports Server

1Connect to the JasperReports Server as superuser.

2Go to Admin and click View Options.

3Select Repository and click View.

4Expand the Themes folder on the left-hand side.

5Right click the Quercus folder.

6From the context menu select Set as Active Theme.

7The theme will automatically change.

Ellucian Quercus Configuration

There are two configuration items in Ellucian Quercus that must be completed before using JasperReports from within Ellucian Quercus.

1Set the Jaspersoft URL.

2Switch the embedded reporting on.

Set the Jaspersoft URL

1Log in to Ellucian Quercus.

2Go to the Control Centre and select Parameters.

3Search for the JASPERSOFT_URL parameter

4Add the URL for JasperReports Server. This URL should be the base URL of your web server followed by /jasperserver-pro/flow.html?_flowId. For example:

   https://your.server.com/jasperserver-pro/flow.html?_flowId
    

5Click Save.

Switch Embedded Reporting On

1Log in to Ellucian Quercus.

2Go to the Control Centre and select Parameters.

3Search for the parameter GENERATE_DOCUMENT_IN_USE.

4Set the value to TRUE.

5Click Save.