Jaspersoft Reports Server Troubleshooting Tips

The following information can help you with the implementation, management, and troubleshooting of your JasperReports Server installation.
ccppmop152
The following information can help you with the implementation, management, and troubleshooting of your JasperReports Server installation.
2
2
Poor Performance with Tomcat 8.5.31
In our certification tests with all supported releases of CA PPM 15.x and Jaspersoft 7.1, Tomcat 8.5.31 consumed higher CPU and memory utilization. As stated in the release notes, use Tomcat 8.5.30 for better resource utilization and response times.
Configure Scheduler and Non-Scheduler Instances for Jaspersoft
The JasperReports Server can be deployed as a standalone application or in a cluster for high-concurrency. Clustered JasperReports Server instances use thread-safe access to their private repository database. As a result, any number of JasperReports Server instances can share the same repository and present the same environment to users.
  • When the JasperReports Server is deployed in a 
    cluster
    , we advise you to dedicate one or more JasperReports Server instances in the cluster to process the execution of scheduled reports. The dedicated instances share the same repository. However, they are not part of the load balancer to serve web requests such as executing reports through the user interface and exploring data through ad hoc views.
  • For a 
    standalone deployment
     where only a single instance of the JasperReports Server is available, the instance processes report scheduling. The instance also serves normal web requests such as report execution through the user interface and exploring data through ad hoc views.
CA PPM
 provides a mechanism to set dedicated JasperReports Server instances as scheduler instances. The instances are part of the load balancer to serve web requests for non-scheduler instances.
During the 
CA PPM
 installation of Jaspersoft 6.x or 7.1, you are asked if you want a separate scheduler instance. If you answer
yes
, you are asked if you want to make the current instance on which the installer is being applied a scheduler instance. Choose
yes
or
no
.
  • Yes:
     The installer performs all of the necessary configuration changes to make the current instance a
    scheduler
    instance.
  • No:
     The installer performs all of the necessary configuration changes to make the current instance a
    non-scheduler
    instance. To take full advantage of this configuration, ensure that the non-scheduler instances are part of the load balancer.
Select the appropriate option during the installation to make the instance a scheduler or a non-scheduler instance. If you are running only a single instance of the JasperReports Server, choose
no
when you are asked about separating the scheduler instance as a dedicated instance.
Page Limits
When you have a
non-scheduler
instance in a clustered environment (standalone node), the maximum number of pages, by default, that can appear on the user interface is limited to 500 pages. When the limit is exceeded, you receive an error. If you need more than 500 pages to appear, you can schedule a report. When you have a Scheduler node, the maximum page limit is 1000.
Set JVM Options for Jaspersoft
The JasperReports Server is supported on Java 1.8 Java Virtual Machine (JVM). Runtime parameters typically need to be explicitly set so that the memory settings have values that are larger than the default settings. The options and values that you should set depend on your version of Java and the application server that you use.
Windows
  1. Using Notepad or a similar application, open <tomcat>/bin/setenv.bat for editing.
  2. Find the line – “Set JAVA_OPTS=%JAVA_OPTS% -Xms1024m -Xmx2048m -XX:MetaspaceSize=32m”.
  3. Update the line to increase the maximum heap size from 2048 (2 GB) to 4096 (4 GB). For example: -Xmx4096m.
Linux/Unix
  1. Using Notepad or a similar application, open vim <tomcat>/bin/setenv.sh for editing.
  2. Find the line – “export JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m -XX:MetaspaceSize=32m".
  3. Update the line to increase the maximum heap size from 2048 (2 GB) to 4096 (4 GB). For example: -Xmx4096m.
  4. You might experience the following error while importing or exporting content, or while starting Tomcat:
    2018-07-09 18:39:40,225 ERROR Digester,pool-14-thread-1:1366 [root|superuser] - Begin event threw errorjava.lang.UnsatisfiedLinkError: /usr/java/jdk1.8.0_152/jre/lib/amd64/libawt_xawt.so: libXtst.so.6: cannot open shared object file: No such file or directoryat java.lang.ClassLoader$NativeLibrary.load(Native Method)
    To prevent these errors, add this parameter for JVM for Jaspersoft:
    -Djava.awt.headless=true
: Consult CA Services for help in sizing your JVM heap size based on your implementation.
Jaspersoft Installation in a Clustered Setup
To provide scalability and high availability of your business intelligence infrastructure, you can deploy a cluster of JasperReports Server instances behind a Load Balancer. The JasperReports Server supports cluster deployments using thread-safe access to its private repository database. As a result, any number of JasperReports Server instances can share the same repository and present the same environment to users. Your repository database must be properly sized to handle the number of server instances. The Load Balancer makes sure that user load is spread evenly, and when needed, you can add new instances of the JasperReports Server to the cluster.
In a clustered setup of the Jaspersoft Server, a distributed cache is useful and you want these Jaspersoft Servers to share the data in the cache. You want the other Jaspersoft Servers to know if elements from the cache have been changed by one of the processes. To provide cache replication across Jaspersoft Server nodes, 
EhCache
 is used. EhCache holds a local copy of the data, and replication messages (adding elements, removing, and so forth) are sent from one Jaspersoft Server node to the others when a modification in the cache occurs.
The Jaspersoft Server Ehcache implementation uses the following two mechanisms for replicating a cache across multiple nodes:
RMI Replication Caching: 
Ehcache provides replicated caching using RMI. To set up RMI replicated caching, do the following:
  1. Configure the CacheManager with a PeerProvider and a CacheManagerPeerListener.
  2. For each cache that will be replicated, add one of the RMI cacheEventListener types to propagate messages.
  3. (Optional) Configure a cache to bootstrap from other caches in the cluster.
JMS Replication Caching: 
JMS can be used as the underlying mechanism for replication operations in Ehcache. The Ehcache jmsreplication module lets enterprises with a message queue investment leverage it for caching. Replication between cache nodes using a replication topic is provided, pushing of data directly to cache nodes from external topic publishers, and a JMSCacheLoader, which sends cache load requests to a queue.
Multicasting and Cache Distributing over RMI
Multicast is a method of sending IP packets to a group of interested receivers. These packets are only sent to the members of a multicast group with the help of a multicast router. A multicast group is assigned Class D addresses (224.0.0.0 - 239.255.255.255). The first 4 bits of a multicast address should be 1110 and the remaining 28 bits represent different groups.
All of the Jaspersoft Server nodes should be in the same network subnet to enable multicasting.
In some cases, Linux distributions do not have multicast enabled by default and the /etc/hosts file does not include the IP address that is associated with the server host name. As a result, you may encounter the 
hostname associated with the localhost in /etc/hosts
 error. Associate the host name in /etc/hosts with the IP address that is set to the server network interface or to the external static NAT IP address of the server.
Verify that the /etc/hosts has the IP address together with the IP 127.0.0.1 and does not contain the entry for loopback address 127.0.1.1.
  $ cat /etc/hosts
127.0.0.1 localhosthost.localdomain localhost
Configure Multicasting (Linux)
Follow these steps:
  1. Enable multicast on the eth0 interface.
    1. Log in as a root user on all the instances in the cluster where JasperReports Server is installed.
    2. Run the following command to enable multicasting on eth0:
      $ /sbin/ifconfig eth0 multicast
      All the instances should be in the same network subnet.
    3. Run the following command to verify that your network interface supports multicast:
      $ /sbin/ifconfig - a
      The Multicast attribute is present in the fourth line of the eth0 properties only if the kernel complies with the multicast support.
  2. To configure the map network interface to send multicast traffic, add a default route for multicast traffic to the specific NIC. For example, the following command allows eth0 to send multicast traffic:
    $ route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
    To check if multicast routing is configured, run the following command:
    $ /sbin/route - n
  3. Run the following command to display the multicast group membership information:
    netstat - g
    Once the route add command is run on all servers, ping the multicast IP with the following command: 
    Ping 
    -c <host ip address>
All the IP addresses that are available in the current configured multicast environment appear.
Configure Multicasting (Windows)
Prerequisite
: When setting up a clustered Jaspersoft environment on Windows, use Windows Server 2008 R1 and R2, and Windows Server 2012.
Reference the following Microsoft TechNet articles and learn how to set up multicast on Windows:
Configure Cache Distribution over RMI on JasperReport Servers
Follow these steps:
  1. Stop the Tomcat server, where Jaspersoft is deployed.
  2. Go to the installer in the root drive (C:\jaspersoft or /fs0/).
  3. Go to the folder - <jaspersoft-installer-folder>\overlay\ehcache\rmi.
  4. Copy the WEB-INF folder to <tomcat>/webapps/<jaspersoftwebcontext-folder>. The operating system will prompt you if it can override the existing files. Click Yes.
  5. Repeat the steps for all of the instances of Jaspersoft that are available in the cluster.
  6. Before you start Jaspersoft Tomcat, delete the Tomcat temp directory and the work/Catalina/localhost directory.
Configure Cache Distribution with JMS on JasperReport Servers
Two open source message queues are available: Open MQ and Active MQ. This example uses Active MQ.
Follow these steps:
  1. Use these steps to configure Active MQ:
    1. Set up Active MQ by downloading the Active MQ server: Apache ActiveMQ. We recommend that you use Active MQ 4.1.2 (apache-activemq-4.1.2).
    2. Extract Active MQ.
    3. Go to the following path: apache-activemq-<x.x.x>-incubator\bin
    4. Log in using the admin credentials for active MQ server. 
      The default port for Active MQ is 61616. You can access the ApacheMQ admin panel through port 8161 by using an /admin URL similar to the following:
      URL
      : http://<activemq-machine-name>:8161/admin
      Login Username
      : admin
      Login Password
      : admin
  2. Stop the Jaspersoft Tomcat server.
  3. Go to the root drive of the installer (C:\jaspersoft or /fs0/).
  4. Go to the folder: <jaspersoft-installer-folder>\overlay\ehcache\jms
  5. Copy the WEB-INF folder to <tomcat>/webapps/<jaspersoftwebcontext-folder>. When the operating system asks you if it can override the existing files, click Yes.
  6. Go to: <tomcat>/webapps/<jaspersoftwebcontext-folder>/WEB-INF.
  7. Open the file: ehcache_hibernate.xml in edit mode.
  8. Search for the text: providerURL=tcp://localhost:61616. When found, replace the localhost with the actual IP or hostname of the ActiveMQ server.
  9. Go to: <tomcat>/webapps/<jaspersoftwebcontext-folder>/WEB-INF/classes.
  10. Open the file: ehcache_hibernate.xml in edit mode.
  11. Search for the text: providerURL=tcp://localhost:61616. When found, replace the localhost with the actual IP or hostname of the ActiveMQ server.
  12. Repeat the steps for all of the Jaspersoft instances that are available in the cluster.
  13. Before you start Jaspersoft Tomcat, do the following:
  • Delete the Tomcat temp directory.
  • Delete the work/Catalina/localhost directory.
Restrict Advanced Reporting Notifications to Trusted Email Domains
In Advanced Reporting, users can email reports either as hyperlinks to the report page or as attachments. When scheduling the reports, they can specify the email addresses for sending the reports and job status notifications. Sometimes, reports contain confidential information and users may want to validate the email addresses before sending the notifications. As an administrator, you can specify trusted email domains (for example, ca.com) so that notifications do not go out to email addresses outside these domains. The user can still specify any email address for notification when scheduling a report. However, before sending the emails, the system filters out the email addresses that do not match the trusted domains.
: If you do not specify a list of trusted email domains, then report emails and job status notifications are sent to all email addresses that the user specifies when scheduling reports.
Alternatively, you can disable the email notifications capability so no report or job status notification are sent out.
You can configure the notification restrictions at the organization level specified for a particular 
CA PPM
 instance.
Follow these steps:
Invoke the following commands from the 
CA PPM
 command-line interface on the system where 
CA PPM
 is installed:
  • Run the following command to add trusted email domains. The list of trusted domains cannot exceed 1200 characters.
    admin jaspersoft email -addDomains 
    <comma_separated_list_of_trusted_domains>
    A message appears indicating that the list of trusted domains were added successfully.
  • Run the following command to display the list of existing trusted email domains:
    admin jaspersoft email listDomains
  • Run the following command to remove email domains from the existing list of trusted email domains:
    admin jaspersoft email -removeDomains 
    <comma_separated_list_of_domains_to_remove>
  • Run the following command to disable report emails and job status notifications, regardless of the configuration of trusted domains:
    admin jaspersoft email disableNotifications
    A message appears indicating that email and job notifications are disabled.
  • Run the following command to re enable report emails and job status notifications:
    admin jaspersoft email enableNotifications
    A message appears indicating that email and job notifications are now enabled.
Check the Installer Version
For information about the installer version, check the following files:
  • The installer README file
  • version.html file that is created after you install JasperReports Server. You can also check this file using the following example URL:
http://<servername>:<portNumber>/<reportservice>/version.htm
HTTPS Enabled Jaspersoft
Complete the following steps if the JasperReports Server is HTTPS enabled.
Follow these steps:
  1. Use a browser to download and save the certificate from the JasperReports Server URL. For example, save it as SETI_JAAS_CER.cer.
  2. From the command prompt, navigate to JDK_HOME on the server where 
    CA PPM
     is installed.
  3. Navigate to jre\lib\security. 
    Example:
     C:\jdks\jdk1.8.0_152\jre\lib\security>
  4. Run the following command:
    keytool -importcert -keystore cacerts -alias tomcat7 -storepass changeit -file SETI_JAAS_CER.cer -trustcacerts
  5. Restart 
    CA PPM
    .
    To delete an entry from the key store, run the following command:
    keytool -delete -keystore cacerts -alias tomcat7 -storepass changeit
    The downloaded certificate is deleted from the certificate store.
Jaspersoft Sender Email Address
The sender email address is the address that appears when JasperReports Server sends an email notification for a scheduled report. JasperReports Server lets you set the sender email address at the JasperReports Server level, but not at the tenant (organization) level.
The following address is the default sender email address value for the JasperReports Server for on-premise implementations:
[email protected]_domain.com
You can change this address during the installation.
To change the default address after the installation, follow these steps:
  1. Locate and open the js.quartz.properties file in a text editor.
  2. Edit the report.scheduler.mail.sender.from property to include your sender email address and save the file.
  3. Restart the JasperReports Server.
Failed to Update Properties on the Jaspersoft Server
While saving the Data Warehouse properties in 
CA PPM
 System Administration (CSA), you may receive the following error message:
Failed to update properties on the Jaspersoft server. Exception getting ClarityJasperAdmin: Unauthorized access to http://<servername>:<portnumber>/<JasperReportsServerContext> with username <ppmjasperadmin>
This error can be the result of one of the following reasons:
  • The key store file was deleted or the 
    CA PPM
     CSA Jaspersoft administrator user (ClarityJasperAdmin) was changed, which resulted in the key store expiration.
    Resolution:
     Regenerate the key store file and copy it to the <JasperReportsServerTomcat>/config folder. For more information, see Generate the Key Store File.
  • The Advanced Reporting content was reimported without first deleting the existing organization/tenant.
    Resolution:
     If you are planning to reimport the content, delete the tenant from the JasperReports Server UI directly or execute the following command from the 
    CA PPM
     install directory:
    jaspersoft delete [-properties propertiesFile] -userName username -orgName orgId[,<orgId>..] -url jsUrl -password password
    • orgName <orgId[,<orgId>..]> (JasperReports Server organization mappings)
    • password <password> (JasperReports Server user password)
    • properties <propertiesFile> (Properties file name)
    • url <jsUrl> (JasperReports Server URL)
    • userName <username> (JasperReports Server user name)
User Not Registered Error on the Advanced Reporting Page
When you access the Advanced Reporting page, you may receive the following error message:
Error 401 User Not Registered. User is not registered on the reporting server.
This error can be the result of one of the following reasons:
  • The key store file was not copied to the <JasperReportsServerTomcat>/config folder. Review the app.ca.log file for more information.
    Resolution:
     Locate the generated key store file and its information for organization Name:ca, organization Id:ca in the following location: 
    C:\ca\install\14.3.0.297\config\ 
    Copy the key store file and organization information to the following JasperReports Server installation directory: 
    <JasperReportsServerTomcat>\webapps\<jasperwebcontext>\WEB-INF\config\
  • The user does not exist on the JasperReports Server, but the 
    CA PPM
     database shows that the user status is synchronized to JasperReports Server. 
    This situation can occur, after the integration, when the user is deleted in JasperReports Server.
    Resolution:
     Execute the Create and Update Jaspersoft Users job with the Full Sync option.
Internal Server Error on Advanced Reporting Page
When you access the Advanced Reporting page, you may receive the following error message:
Error 500 - Internal Server Error. The server could not retrieve the document due to server-configuration or technical problems. Contact your site administrator.
This error can occur if the key store file was not copied to the <JasperReportsServerTomcat>/config folder. Review the app.ca.log file for more information.
Resolution:
 
  1. Locate the generated key store file and its information for organization name: ca, organization Id: ca in the following location: 
    C:\ca\install\14.3.0.297\config\
  2. Copy the key store file and organization information to the following JasperReports Server installation directory:
    <JasperReportsServerTomcat>\webapps\<jasperwebcontext>\WEB-INF\config\
Memory Leak Errors May Appear in Tomcat Logs after Stopping or Starting the Server
Occasionally, you may see the following error messages in Tomcat, especially when restarting the JasperReports Servers as a result of maintenance. These errors have been reported on the Linux platform, although they may also be seen in Windows. Related to these errors, you may notice that the Tomcat process does not exit gracefully or that Advanced Reporting is not accessible even though the port is available.
org.apache.catalina.loader.WebappClassLoader checkThreadLocalMapForLeaks
SEVERE: The web application [/reportservice] created a ThreadLocal with key of type [org.apache.log4j.helpers.ThreadLocalMap] (value [[email protected]]) and a value of type [java.util.Hashtable] (value [{SESSION_ID=5C55FD9CCE7272C7FF20B2E6D122F97D, USER_ID=admin|abc123}]) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak.
org.apache.catalina.loader.WebappClassLoader checkThreadLocalMapForLeaks
SEVERE: The web application [/reportservice] created a ThreadLocal with key of type [net.sf.jasperreports.engine.fonts.FontUtil$1] (value [[email protected]]) and a value of type [java.util.HashSet] (value [[Arial]] ) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak.
SEVERE: The web application [/reportservice] created a ThreadLocal with key of type [java.lang.InheritableThreadLocal] (value [[email protected]]) and a value of type [org.springframework.security.authentication.UsernamePasswordAuthenticationToken] (value [org.springframew[email protected]cd0a3791: Principal: MetadataUserDetails: admin; Credentials: [PROTECTED]; Authenticated: true; Details: null; Granted Authorities:
Resolution:
  1. Verify that the JasperReports Server Tomcat process is not present after performing a shutdown (for example, 
    "ps -ef | grep tomcat"
    ).
  2. If the process is present, kill the process gracefully (for example, 
    kill -9 <ProcessID>
    ).
  3. Start up the Tomcat process again.
Please Wait Message on the Advanced Reporting Page
When you access the Advanced Reporting page, you may see the
Please Wait
message that does not go away.
  1. See KB article KB000004562 for details including workarounds to resolve the issue. 
  2. Advise users to clear their browser cookies and temporary cache files.
Project Storyboard Report Error
When publishing the Project Storyboard report for the first time after an upgrade to 15.x, you see the following error:
The server has encountered an error. Please excuse the inconvenience. Error Message: Error filling report.
Other reports might publish correctly.
The logs show:
java.sql.SQLSyntaxErrorException: ORA-00904: "SC51564DDWH"."DWH_INV_REMAINING_ALLOC_FCT": invalid identifier
Resolution:
After upgrading, run the following jobs in the listed order:
  1. Load Data Warehouse (select the Full Load option)
  2. Load Data Warehouse Access Rights
The Load Data Warehouse job is required to populate the Status Report object in the data warehouse for Advanced Reporting.
Custom Attributes Enabled for the Data Warehouse Do Not Appear in Jaspersoft Domains
After an upgrade, you might observe the following behavior. Custom fields checked for the data warehouse do not appear in Jaspersoft domains where users create their ad hoc queries. You try running the DB/DWH schema reports and can confirm those attributes exist in the database and data warehouse tables but do not appear in the domains.
Resolution:
  1. Run the following command: 
     admin content-jaspersoft csk restoreDomains -userName superuser -password superuser
  2. Wait for this command to finish.
  3. Run the Load Data Warehouse job in
    Full
    (not
    incremental
    ) mode.