This appendix contains the following sections:

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:

Running Out of Database Connections

JasperReports Server manages a pool of connections for each JDBC data source. The default number of connections is 20, but if you run many reports concurrently against the same data source you may reach the connection limit and see degraded performance. In particular, using the web service APIs, REST clients can easily launch many report executions at the same time and reach the limit.

The connection pool size is limited to avoid having too much memory permanently allocated to connections. But if you need more concurrent connections on a regular basis, you can increase the limit with the following configuration:

If you are using JNDI data sources, you can configure the number of connections in your application server. For more information, see the sections on JNDI service in “Troubleshooting” on page 1.

Fields Do Not Appear in Ad Hoc Editor

The Ad Hoc editor only supports certain data types. If a Topic contains a field with an unsupported type, the field does not appear when you open the Topic in the Ad Hoc editor. The following data types are supported in the Ad Hoc editor:

Unsupported data types may occur when editing Topics manually, and sometimes with data sources for big data, in particular MongoDB. The connector for MongoDB uses the data type of a given value in the last document containing that value, and errors in input files may cause unexpected types. For example, omitting the single quotes in the JSON format causes a string type to be interpreted as a numeric type.

If your Topic or Domain fields do not appear in the Ad Hoc editor, you can enable logging on the following class to see details of fields with unsupported data types:

com.jaspersoft.ji.adhoc.metadata.AdhocTopicMetadata

For information about enabling logging, see Configuring System Logs.

Field Names Disappear in Ad Hoc Canvas

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:

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:

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.

Ad Hoc Dimensions Too Large

A column or row dimension in an Ad Hoc crosstab is the equivalent of a row group in an Ad Hoc table. The members of a dimension or group are the unique values used to aggregate the data. Some dimensions and groups can have hundreds or thousands of members. Even if the dimensions are collapsed, the internal engine must calculate and store the values for all dimension members and all cells.

Some datasets contain fields that make huge dimensions on the order of tens of thousands or hundreds of thousands of members. These fields are usually meant to be filtered, but if they are inserted into the crosstab before filtering or by accident, they will trigger a large database operation and a large processing load in the Ad Hoc editor. To limit this impact, you can configure a limit to the number of members in any dimension.

The internal process that calculates groups, dimension, and members is called the categorizer. Change the following setting to reduce this limit and avoid performance issues with large cardinality dimensions.

In addition, dimensions and groups may be nested on several levels, for example Country, Province, and City. If your row data has 100 countries, and each country has 10 provinces, and each province has 10 cities or towns, there will be 100 x 10 x 10 = 10,000 rows in your full crosstab. If you also have two column dimension, each with 10 members, there will be 100 columns in your crosstab and one million cells when all dimensions are fully expanded. This scenario has several implications:

For example, it's unlikely that a user can read the expanded data for more than one country at a time. The large report in this example can be replaced with two reports, one that only has the country dimension and allows the user to compare aggregate values from all countries, and another that displays all provinces and cities for a single country selected by a drop-down filter list. Both reports will run much faster than the single large report, and the user will not be blocked waiting for the report to refresh.

Custom URLs Not Loading in Dashboards

Dashboards allow you to specify frames that contain web pages loaded from custom URLs specified when designing the dashboard. These URLs can even include parameters from input controls. However, if the URL takes too long to load, JasperReports Server will display an error message instead of the content.

If you expect the custom URL to take longer than 10 seconds, you can change the default timeout as follows:

Print View Not Displaying in Dashboards

If you cannot display the Print view for a dashboard, there might be an issue with the size of the input control values. Input control values are passed as URL parameters on this page, and the application server can limit the length of the URL that includes the parameters.

To avoid this limit and allow large numbers of input control values in dashboard print view, edit the following configuration file, or the equivalent in your application server.

<Connector port="8080" protocol="HTTP/1.1"            connectionTimeout="20000"            redirectPort="8443"            URIEncoding="UTF-8"           maxPostSize="0"           maxHttpHeaderSize=65535 />[/code]                    

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/js.quartz.base.properties:

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:

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 accidentally imported orphan jobs, make configuration change shown below and restart your server.

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 net.sf.jasperreports.export.xls.ignore.graphics 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:

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:

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 SQuirreL 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/log4j.properties file:

JDBC Drivers

As of JasperReports Server 5.1, JDBC driver management is automated and simplified. JasperReports Server ships with drivers for some 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 Data Sources For instructions on adding JDBC drivers when using JBoss, see the next section.

JDBC Drivers on JBoss

For modularity reasons, the JBoss application server does not allow web applications such as JasperReports Server to change executable files, such as JDBC drivers, on the fly. In order for JDBC drivers to appear in the list of available drivers and be selectable, you must configure JBoss before you use the drivers to create a JDBC data source.

To add JDBC drivers on JBoss:

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.

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:

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:

Also check the following points:

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:

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

JNDI Services on WebLogic

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

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.

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

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

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

;integratedSecurity=true

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:

Reverting to the Old Home Page

JasperReports Server 5.5 introduces a new home page with more functionality 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.