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.

This appendix contains the following sections:

Number of Users Exceeded
Field Names Disappear in Ad Hoc Editor
Ad Hoc Filter With All Values Causing Error
Scheduler Sending Multiple Emails
Scheduler Running Deleted Jobs
Charts Not Appearing in Excel Export
Adding Data Sources
Hadoop-Hive Reports Not Running
Reverting to the Old Home Page

Number of Users Exceeded

When there are more users defined in the server than your license allows, the login page displays a warning; users can still log in. After a 24-hour grace period, an email is sent to the administrator and users can no longer log in. Most server functionality is disabled. To re-enable server functionality:

Contact Jaspersoft sales to purchase additional user licenses. When you install the new license, the server becomes fully functional for all users.
Remove users until the number of user accounts on the server is in accord with your license. When server functionality is disabled, administrators can still log on and select Manage > Users to delete user accounts. For more information see Managing Users.

Field Names Disappear in Ad Hoc Editor

Some fields with international characters in their display names disappear when the field is dragged into the canvas of the Ad Hoc Editor. This is caused by non-Unicode characters used in the field name in the JRXML underlying the selected Topic.

To make the international characters appear in Ad Hoc view field labels, use the resource bundle mechanism:

1. Create a resource bundle (*.properties) and associate each of your field label with a unique key. Use unicode escape sequences such as \u0153 for the œ character to insert international characters in your label values.
2. Use the $R syntax in the Topic to specify the appropriate key for the label of each desired field.
3. Upload the resource bundle as a resource of the Topic.

When you open the Topic in the Ad Hoc Editor, the labels are displayed correctly from the resource bundle.

This method has the advantage that you can create a resource bundle for each language that the Topic needs to support, and users see the labels for the locale they set in their browser.

For more information about localizing JasperReports Server, see Localization.

Ad Hoc Filter With All Values Causing Error

When using filters in the Ad Hoc editor, your browser sends lists of values to the server with a POST operation. If you filter a field with tens or hundreds of thousands of distinct values, and then select all values, your browser will send megabytes of data in the POST operation. Some application servers are configured to reject such large input by default.

For example, if you select 100 000 values in an Ad Hoc filter on a default installation on Tomcat, Tomcat will log an error and redirect the user to the JasperReports Server home page. The Tomcat error log may contain the following entry:

2013-09-30 15:12:33,847 ERROR errorPage_jsp,http-8080-6:559 - stack trace of
exception that redirected to errorPage.jsp

If you apply filters to fields with large numbers of distinct values, make sure your app server is configured to accept large input. The following table shows how to configure Apache Tomcat. For other app servers, refer to your app server's documentation about POST operations.

Configure Apache Tomcat to Accept Large Filter Values

Configuration File




<Connector port="8080" protocol="HTTP/1.1" 
           maxPostSize="0" />

Add the maxPostSize parameter to set the number of bytes accepted by the app server; "0" indicates there is no limit. For more information, see the Tomcat documentation.

Scheduler Sending Multiple Emails

In cases where you have a cluster of JasperReports Server instances accessing the same repository, the schedulers in each instance can sometimes conflict and send multiple emails. The behavior depends on the run-time of the reports that are scheduled, because a long report may cause the scheduler on another node to attempt to run the same report before the first node finishes.

To change this behavior, set the following parameter in <WAR-file>/WEB-INF/

org.quartz.jobStore.clusterCheckinInterval = 900000

In case a job fails on the first node, the check-in interval is meant to ensure that the job runs on a second node after this delay. Because the schedulers do not communicate directly, the second scheduler cannot distinguish between a node that had a failure and a node that is still running a job. The default value corresponds to 15 minutes.

This parameter can be adjusted as follows:

If you have scheduled reports that take a long time to run, longer than 15 minutes, you may see multiple emails. Increase this parameter to an interval longer than your longest report’s expected run-time.
On the other hand, if you have small reports that finish quickly, the default value means that any scheduler or node problem isn’t detected by the other scheduler before 15 minutes. If you have time-critical reports scheduled, you can lower this parameter, but the value should still exceed your longest expected report run-time.

Restart all of your server instances after changing this parameter.

Scheduler Running Deleted Jobs

In some cases, old versions of JasperReports Server did not delete the scheduled jobs when deleting a report. These jobs cause errors when the scheduler tries to run them, but you can’t remove the jobs through the user interface. The server no longer creates such “orphan” jobs, but they may appear again when you upgrade or import a catalog that contains them.

If you accidently imported orphan jobs, make configuration change shown below and restart your server.

Automatically Deleting Orphan Jobs

Configuration File







If your repository has orphan jobs that cause errors, change this property from false (the default) to true. Orphan jobs are detected and deleted just before they run, so all orphan jobs will be deleted gradually over time.

Charts Not Appearing in Excel Export

When exporting a report to Excel, JasperReports Server usually removes images that decorate the report and that do not fit in the Excel data-centric layout. However, JasperReports Server also converts any charts to images and uses the special property set to false to make the image appear. If your report does not set this property explicitly, the chart images do no appear in your reports when they are exported to Excel.

If you have a lot of reports with this issue, you can set the property on the server:

Charts Images in Excel Export

Configuration File





By default, this property is set to true; in this case, images and chart images from the report do not appear when exported to Excel. Set this property to false to make chart images appear in Excel exports.

Adding Data Sources

When adding a data source to JasperReports Server, there are several areas that can cause errors. Start by looking at the following general connectivity issues:

Check that your database server is available and accepting TCP/IP connections from the host where JasperReports Server is installed.
Check in your DBMS that the username and password you are using are correct and have access to the selected database.
Check for firewalls or network connectivity errors.

Many databases, including MySQL, also require the user grants to include the specific host from which connections are allowed. Otherwise, when testing the JDBC connection, a connection may not be allowed even though the username and password are correct. For more information, refer to the MySQL documentation for setting up users.

An easy way to test connectivity from the server to the database with a particular user is to use a tool such as SquirrelSQL or another DB query tool to connect to the database from the same host as your JasperReports Server instance.

Finally, you can enable additional logging to help you find the cause of the error. Set any or all of the following loggers in the server settings interface or in the ...\WEB-INF\ file:

JDBC Drivers

As of JasperReports Server 5.1, JDBC driver management is automated and simplified. JasperReports Server ships with drivers for most databases, as listed in the dialog for creating data sources. If the JDBC driver for your database is not included, the system administrator can easily upload the driver and use it immediately in a data source.

For instructions on updating JDBC drivers without restarting the server, see Managing JDBC Drivers

Database Permissions

When creating database users, you must ensure that they have the appropriate privileges to access data, as well as permission to connect from the server that JasperReports Server is running on.

The database user that you specify in your data source definition should have the appropriate select permissions to query the tables within your database for the reports you want to generate.
If you accept the defaults during installation of JasperReports Server on Linux from an RPM using apt-get, rpm, or yum, the bundled PostgreSQL only allows the user who owns PostgreSQL to connect. Enter the following commands to connect:
su - postgres
psql -U postgres
Many databases, including MySQL, also require that the user permissions name the specific host from which connections are allowed. Otherwise, when testing the JDBC connection, a connection may not be allowed even though the user name and password are correct. For example, see the MySQL documentation for setting up users.

A fairly easy way to test permissions and connectivity is to use a tool such as SquirrelSQL or another DB query tool to connect to the database from the same host as JasperReports Server and to run typical queries against your database.

JDBC Database URLs

When you choose a JDBC driver, the data source creation wizard prompts you for the elements of the URL that are required for your database. In some cases, you may need to add certain arguments to the JDBC URL. Ensure that the database URL you entered when defining your JDBC data source is consistent with what is required for your specific database and database driver. The following table gives the default URLs and port numbers, as well as examples of optional arguments supported by the most common databases:


Default JDBC Database URL



MySQL and MariaDB






SQL Server


SQL Server jTDS driver










JNDI Services on Apache Tomcat

If you have trouble with a JNDI connection, you need to look at the JNDI definition for your database on your application server. This section gives common issues with JNDI definitions on Apache Tomcat connecting to MySQL. If you use a different application server or database server, refer to its documentation.

A JNDI connection on Tomcat is defined in two different files. Make sure both have the following information:

<Resource name="jdbc/<db-name>" auth="Container" type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="10000"
username="<db-user>" password="<db-user-password>"
validationQuery="SELECT 1" testOnBorrow="true"
<description>JNDI Example</description>

Also check the following points:

Ensure the driver for your database connection is in the <tomcat>/lib folder.
If you installed JasperServer from a WAR file, Tomcat may have created a separate copy of context.xml in <tomcat>/conf/Catalina/Localhost/jasperserver-pro.xml. See the corresponding section in the troubleshooting appendix of the JasperReports Server Installation Guide.
See the Apache Tomcat documentation for JNDI datasources.

JNDI Services on JBoss

After defining JNDI Services on the JBoss application server, JasperReports Server does not automatically detect the new services. In order to use the new JNDI services as data sources in the server, follow these steps:

1. Define and deploy a JNDI data source in the JBoss administrator console.
2. Modify the file <jboss>/webapps/jasperserver-pro/WEB-INF/web.xml to include a data source reference to this new JNDI service.
3. Modify jboss-web.xml to include a reference to this data source.
4. Because the deployment configuration files such as web.xml were modified, redeploy the JasperReports Server application.

Now you can define JNDI data source in the repository, as described in JNDI Data Sources.

JNDI Services on WebLogic

Follow these steps to configure JasperReports Server to use JNDI data sources with WebLogic:

1. Append the following definition to the <reference-descriptor> node of WEB-INF/weblogic.xml:
2. Append the following definition to WEB-INF/web.xml:
    <description>TestDatabase database</description>
3. In the WebLogic Admin Console, add a datasource with TestDatabase as the JNDI name.
4. Restart the jasperserver-pro instance using the WebLogic Admin Console.

Creating a Data Source on SQL Server Using Windows Authentication

If your database is Microsoft SQL Server and you use Windows Authentication (also called Integrated Security), use the following procedure to create a data source.

1. Go to the download page for Microsoft SQL Server JDBC Driver 3.0.

Do not use version 4.0 of this driver because it will not work.

2. Download and run the self-extracting executable: 1033\sqljdbc_3.0.1301.101_enu.exe
3. Open the extracted folder sqljdbc_3.0\enu\auth, and then either the x64 or the x86 subfolder, depending on whether your version of Windows is 64-bit or 32-bit, respectively.
4. Copy the file sqljdbc_auth.dll to the folder that your app server automatically searches for DLLs.

For Tomcat, this is the <tomcat>\bin folder.

5. Restart your app server.
6. Log into JasperReports Server as and administrator.
7. Select Create > Data Source from the main menu.
8. In the Type field, select JDBC Data Source.

The page refreshes to show the fields necessary for a JDBC data source.

9. Enter a name and optional description for your data source.
10. From the dropdown field, select
11. Enter the database hostname and database name of your SQL Server instance.
12. In the URL field, add the following string to the end of the generated URL:


13. In the User Name field, enter any non-blank string you want, for example “none.”
14. In the Password field, enter any non-blank string you want, for example “none.”
15. Set the Time Zone and Save Location fields if necessary.
16. Click Test Connection and verify that the connection works.
17. Click Save to save the data source in the repository.

Hadoop-Hive Reports Not Running

If you created a Hadoop-Hive data source prior in JasperReports Server 4.5 or earlier, it may not run when imported to a more recent version of the server, for example after an upgrade. The reason is because the name of the package of the Hadoop-Hive connector class has changed.

To update Hadoop-Hive data sources:

1. Create a new Hadoop-Hive data source using the same URL as the old Hadoop-Hive data source used by your reports. This new data source will use the correct package name internally.
2. Update your Hadoop-Hive-based reports to use the new data source.
3. Delete the old, imported data source.

Reverting to the Old Home Page

JasperReports Server5.5 introduces a new home page with more fuctionality and access to more features in the server. If your installation or customizations require the old home page with the large buttons, you can specify that the server use the old home page.

1. Open the <js-webapp>/WEB-INF/flows/homeFlow.xml file.
2. Locate the following line:
<view-state id="homeView" view="modules/home/home">
3. Replace the view value as shown in the following sample:
<view-state id="homeView" view="modules/old_home/home">
4. Restart the server or redeploy the JasperReports Server web app.