Jaspersoft Reports Server Troubleshooting Tips (On-Premise Only)

ccppmop1571
The following information can help you with the implementation, management, and troubleshooting of your JasperReports Server installation.
2
2
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.
Clarity 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
Clarity 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 error java.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 directory at java.lang.ClassLoader$NativeLibrary.load(Native Method)
    To prevent these errors, add this parameter for JVM for Jaspersoft:
    -Djava.awt.headless=true
Consult Broadcom Service partners for help in sizing your JVM heap size based on your implementation.
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 notifications are sent out.
You can configure the notification restrictions at the organization level specified for a particular
Clarity PPM
instance.
Follow these steps:
Invoke the following commands from the
Clarity PPM
command-line interface on the system where
Clarity 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
    Clarity 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
    Clarity 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
Clarity 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
    Clarity 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
    Clarity 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)
java.nio.BufferUnderflowException
Oracle Version 12.1.0.2.0 to 12.2.0.0.0 has a known issue that causes this error. Please review this Knowledge Base article to resolve this issue.
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
    Clarity 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.