Install and Configure Advanced Reporting with Jaspersoft

Complete the following steps to set up Advanced Reporting with Jaspersoft. Also, configure Jaspersoft to restrict email notifications to trusted domains and set up a dedicated JasperReports server for scheduled reports.
ccppmop143
Complete the following steps to set up Advanced Reporting with Jaspersoft. Also, configure Jaspersoft to restrict email notifications to trusted domains and set up a dedicated JasperReports server for scheduled reports.
2
 
Review the Prerequisites
  • Verify that 
    Clarity Project and Portfolio Management (PPM)
     is installed or upgraded. For more information, see
    Installing and Upgrading
  • Download the latest JDK8 and Tomcat7 software from the vendors. Set JAVA_HOME and JRE_HOME and ensure that the correct Java 8 and JRE 8 executables are referenced in the PATH environment variable.
    For example: (Windows)
    set PATH=%JAVA_HOME%\bin;%PATH% 
    (Linux)
    export PATH=$PATH:$JAVA_HOME/bin
  • Create a JasperReports Server Database/Schema. For more information and sample queries for supported vendors, see Create a Jaspersoft Schema and Set Permissions.
For more information about the correct software versions that are compatible with
Clarity Project and Portfolio Management (PPM)
, see the 
Clarity Project and Portfolio Management (PPM)
 Release Notes
.
  • Extract the contents of the installer, preferably into the root drive (for example, C:\jsftinstall  or /<directory/jsftinstall ) to avoid the “file name is too long" exceptions during the upgrade process.
  • If this is the second attempt at an installation, perform the following actions before starting the install process:
Post-Installation Options
  • While the Tomcat service on the JasperReports Server is being started or shut down, you may receive the following warning messages, which you can safely ignore. The PermSize and MaxPermSize parameters are not supported in JDK 1.8. The MetaspaceSize parameter is used instead.
    Java HotSpot(TM) 64-Bit Server VM warning: ignoring option PermSize=32m; support was removed in 8.0
    Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=512m; support was removed in 8.0
  • If you use Oracle, run the following query after the JasperReports Server installation to improve the overall performance of the system.
    exec DBMS_STATS.GATHER_SCHEMA_STATS (ownname => USER, degree => DBMS_STATS.AUTO_DEGREE, estimate_percent => 100, cascade => true, method_opt=> 'FOR ALL COLUMNS SIZE 1');
    We recommend that you run this query frequently.
  • The Output to Host File System option saves the report output to a specified folder on the JasperReports Server host server. This option is disabled by default. For information about enabling this option, see the Jaspersoft documentation.
  • The governor limit on the JasperReports Server database connection has a timeout set to 15 minutes (900000 milliseconds). Report queries running longer than 15 minutes close and an error appears indicating the timeout. For better performance and to relieve stress on the database, do not change this setting.
    You can change the setting in the following location:
    webapps/<jasperwebcontext>/WEB-INF/classes/jasperreports.properties
    net.sf.jasperreports.governor.timeout.enabled= true
    net.sf.jasperreports.governor.timeout=900000
  • The governor limit on the JasperReports Server pages is set to 500. This limit applies to all output formats. You can change this setting in the following location: 
    <tomcatDirectory>/webapps/<jasperwebcontext>/WEB-INF/classes/jasperreport.properties
    net.sf.jasperreports.governor.max.pages.enabled=true
    net.sf.jasperreports.governor.max.pages=500
    Setting this limit requires a restart of the JasperReports Server.
Create the JasperReports Server Schema and Set Permissions
The following procedures explain how to create a database user for JasperReports Server.
Oracle
Follow these steps:
  1. Create a Tablespace for JasperReports Server.
    CREATE TABLESPACE "[JS User]_PPMJAS" DATAFILE '<ORACLE_BASE>\ORADATA\<SID>\PPM_JASPER_TS.DBF' SIZE 500M REUSE AUTOEXTEND ON NEXT 25M MAXSIZE 10G LOGGING EXTENT MANAGEMENT LOCAL SEGMENT SPACE MANAGEMENT AUTO;
  2. Create a database user and set the required permissions. 
    CREATE USER [JS User] IDENTIFIED BY [JS Password] DEFAULT TABLESPACE [JS User]_PPMJAS TEMPORARY TABLESPACE TEMP; GRANT CONNECT, RESOURCE, CREATE SESSION TO [JS User]; GRANT UNLIMITED TABLESPACE, QUERY REWRITE TO [JS User];
SQL Server
Follow these steps:
  1. Create a database (for example, PPM_JASPERSOFT).
  2. Alter database ppm_jaspersoft to set arithabort on.
  3. Alter database ppm_jaspersoft to set ansi_nulls on. 
  4. Alter database ppm_jaspersoft to set quoted_identifier on.
    IF (SELECT (CAST(LEFT(CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR(20)), CHARINDEX('.', CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR(20)), 1) - 1) AS INTEGER))) = 10 BEGIN exec sp_dbcmptlevel 'PPM_JASPERSOFT', @new_cmptlevel=100 END IF (SELECT (CAST(LEFT(CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR(20)), CHARINDEX('.', CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR(20)), 1) - 1) AS INTEGER))) = 11 BEGIN exec sp_dbcmptlevel 'PPM_JASPERSOFT', @new_cmptlevel=110 END IF NOT EXISTS (SELECT 'yes' FROM syslogins WHERE LOWER(name) = LOWER('PPM_JASPERSOFT') ) BEGIN exec sp_addlogin 'PPM_JASPERSOFT','my_password','PPM_JASPERSOFT','us_english' END
  5. Set the isolation level to 
    read committed snapshot
     for SQL Server 2005. 
    Make sure that the user can access the system views (such as syslockinfo, sysindexes).
    begin exec ('alter database PPM_JASPERSOFT set read_committed_snapshot on') exec ('grant VIEW SERVER STATE to PPM_JASPERSOFT') exec ('ALTER LOGIN PPM_JASPERSOFT WITH CHECK_POLICY=OFF') end
    USE PPM_JASPERSOFT
    The schema owner is referenced in the code when executing functions in SQL Server and is hard-coded to PPM_JASPERSOFT. The login name can differ.
    -- Schema owner is referenced in code when executing functions in MSSQL, -- so we intentionally hard-code it here to PPM_JASPERSOFT. Login name can differ. exec sp_grantdbaccess 'PPM_JASPERSOFT','PPM_JASPERSOFT' exec sp_defaultdb 'PPM_JASPERSOFT', 'PPM_JASPERSOFT' exec sp_addrolemember 'db_owner', 'PPM_JASPERSOFT'
Install JasperReports Server
Perform the following steps to install JasperReports Server and verify that the installation was successful.
Install JasperReports Server
Note:
Install JasperReports Server in the JasperReports Server Tomcat folder.
Follow these steps:
  1. Complete the following steps to download the Jaspersoft zip file.
    1. Log in to CA Support Online and navigate to the
      Clarity Project and Portfolio Management (PPM)
       product support page.
    2. Under Quick Access, click Download Center and complete the search information to locate the 
      ca_ppm_jaspersoft_6.1.0_5.1.0.26.zip
      file.
  2. Save the zip file to a local directory.
  3. Unzip the contents of the file to a new folder (for example, /opt/jasperreports for UNIX or C:\Jasperreports for Windows).
    Unzip the installer into the root drive to avoid the file name is too long exception (for example, C:\jaspersoft or /fs0/).
  4. Open the command prompt and complete the following steps:
    1. Run the following commands: 
      Linux:
      chmod u+x install.sh 
      install.sh
      Windows:
      install.bat
    2. Select the Installation Type.
      • New
        This option installs the new JasperReports Server version that you downloaded in an earlier step.
    3. Enter the Apache Tomcat7 directory (the location where JasperReports Server is deployed and Tomcat is installed).
    4. Enter the following information:
      • Enter Jaspersoft web app name
        . Specifies the folder name where the JasperReports Server is deployed. For example, if reportservice is the JasperReports Server web context, the URL to access the JasperReports Server is
        http://<domain_name>:<portnumber>/reportservice
        .
      • Enter Jaspersoft web app port
        . Specifies the port on which JaspersoftReports Server runs (for example, 8080).
    5. (Optional) Enter the following information to configure the mail settings: 
      • Do you want to configure Email (y/n)?
        Select Y to configure the mail server.
      • Enter Mail Server Hostname
        Specifies the hostname of the mail server (for example, mail.localhost.com).
      • Enter Mail Server Port
        Specifies the port number of the mail server (for example, 25).
      • Enter Sender Email Protocol
        Specifies the protocol that the mail server supports. Currently, JaspersoftReports Server supports smtp and smtps (for example, exchange).
      • Enter Sender Email Username
        Specifies the user name of the mail sender (for example, test).
      • Enter Sender Email Password
        Specifies the password of the mail sender (for example, password123).
      • Enter Sender Email Address
        Specifies the mail address of the sender (for example, [email protected]). For more information, see JasperReports Server Sender Email Address.
    6. Select the Installation Mode.
      • Standalone (for standalone servers)
      • Cluster (for Cluster-based deployments)
        • Primary Node
        • Additional Node (Web-app deployment only): Deploys the web app only using the Primary Node Database/Schema. 
          If you are deploying an additional node, provide the database details for the Primary Node.
    7. Select the Database Server Type and provide the required information.
      • MSSQL
        SQL Server Hostname
        : Hostname of the server where SQL Server is installed (for example, HOSTNAME).
        SQL Server Port Number
        : Database port on which SQL Server is running (for example, 1433).
        Jaspersoft Database Name
        : JasperReports Server database name (default=PPM_JASPERSOFT).
        Jaspersoft Database Username
        : JasperReports Server user name (for example, PPM_JASPERSOFT).
        Jaspersoft Database Password
        : JasperReports Server password if Oracle is selected.
      • ORACLE
        • Oracle Standalone
          Oracle Database Hostname
          : Hostname of the server where Oracle is installed (for example, localhost).
          Oracle Database Port Number
          : Database port on which Oracle is running (for example, 1521).
          Jaspersoft Database Username
          : JasperReports Server database user name (for example, PPM_JASPERSOFT).
          Jaspersoft Database Password
          : JasperReports Server password.
          Oracle version
          11.2.0.4 or higher
          12.1.0.2 or higher
          Oracle SID Name
          : Oracle SID (for example, <ORACLESID>)
        • Oracle Cluster (RAC)
          Oracle Database Hostname
          : Hostname of the server where Oracle is installed (for example, localhost).
          Oracle Database Port Number
          : Database port on which Oracle is running (for example, 1521).
          Jaspersoft Database Username
          : JasperReports Server database user name (for example, PPM_JASPERSOFT).
          Jaspersoft Database Password
          : JasperReports Server password.
          Oracle Service Name
          : Oracle service name (for example, <SERVICENAME>).
  5. Verify the properties that you entered and wait until the installation completes.
Verify the JasperReports Server Installation
Complete the following steps to verify that the installation was successful.
Follow these steps:
  1. Start the JasperReports Server if it has not already started.
  2. Open 
    http://<domain_name>:<portnumber>/<jasperwebcontext>/
    .
  3. Verify that you can open the JasperReports Server login page.
  4. Log in to the JasperReports Server using the superuser credentials.
  5. Review the install.log for any errors. 
    This file is available in the folder where you unzipped the contents of the JasperReports Server installation file.
Apply the JasperReports Server Cumulative Patch
Application of the JasperReports Server cumulative patch is mandatory for 
Clarity Project and Portfolio Management (PPM)
fresh installations and upgrades.
Apply the JasperReports Server cumulative patch after you have completed a successful JasperReports Server installation. This patch and the CA JDBC Adapter allow you to access Jaspersoft Studio without using a virtual private network (VPN). You can then build reports with Jaspersoft Studio without the need for VPN access to the database servers. In addition, this patch provides the following benefits:
  • Fixes for issues that previously occurred with the JasperReports Server.
  • Extra database indexes for the JasperReports Server repository database for improved performance.
  • The generation of access events is disabled for improved performance. 
  • The capability to configure a dedicated JasperReports Server for scheduled reports in a typical multi-node cluster deployment. For details, see Configure a Dedicated JasperReports Server for Running Scheduled Reports.
  • The ability to define trusted email domains to restrict report emails and job status notifications to trusted users only. Also, allow the
    Clarity Project and Portfolio Management (PPM)
    administrator to disable Advanced Reporting notifications. See Restrict Advanced Reporting Notifications to Trusted Email Domains for details.
 You might observe the following changes on the UI after applying the patch:
  • The Recently Viewed Items section on the Advanced Reporting home page no longer displays any items after the application of the patch.
  • You might encounter the following error when running an unscheduled report in an environment running a dedicated JasperReports Server instance:    
    "Report '<Report Name>' exceeded the limit of 500 maximum pages".              
To avoid the error, apply proper filters when running unscheduled reports. To run reports larger than 500 pages, schedule these reports. The maximum limit for scheduled reports is 1000 pages.
In a standalone deployment with a single JasperReports Server instance running, the maximum page limit is still 500 pages for both scheduled and unsheduled reports.
For more information about the corrected issues and other important notes, see the README.txt file for the patch.
Follow these steps:
  1. Shut down the Tomcat service (where JasperReports Server is deployed).
  2. Back up the JasperReports Server database schema.
  3. Zip the JasperReports Server webapp folder in the Tomcat webapp folder. When you zip the folder, provide a meaningful name for the zip file, identifying the purpose of the backup. Move the zip file to a different location in the file system (for example,
    /fs0/reportservice-backups
    for UNIX or
    C:\Jasperreports\reportservice-backups
    for Windows).
  4. Complete the following steps to download the JasperReports Server cumulative patch zip file.
    1. Log in to CA Support Online and navigate to the CA PPM Product Support Page.
    2. Under Quick Access, click Download Center. Search to locate the 
      ca_ppm_jaspersoft_patch_6.1.0_5.1.0.2.31.zip
      file and save the zip file to a local directory.
  5. Unzip the contents of the zip file to a new patch folder (for example,
    /opt/jasperreports/patch
    for UNIX or
    C:\Jasperreports\Patch
    for Windows).
  6. Open a command prompt and complete the following steps:
    1. Go to the bin folder under the folder where you extracted the patch (for example,
      /opt/jasperreports/patch/bin
      for UNIX or
      C:\Jasperreports\Patch\bin
      for Windows).
    2. Provide execute permission to the installation scripts.
                     UNIX/Linux
–Run the following command:
                           [[email protected] bin]#chmod u+x *
                     Windows
–Not applicable
     
4. Run the following commands to start the patch installation in interactive mode.
                    UNIX/Linux
–Run the following command:
                        [[email protected] bin]#sh ./install.sh interactive
                    Windows
–Run the following command:
                        C:\Jasperreports\Patch\bin>install.bat interactive
     5. Enter the requested information.
    • Enter Tomcat Home Directory
      . The location where JasperReports Server is deployed and Tomcat is installed.
    • Enter Jaspersoft Server web-application Name
      . The folder name where the JasperReports Server is deployed. For example, if
      reportservice
      is the JasperReports Server web context, the URL to access the JasperReports Server is 
      http://<domain_name>:<portnumber>/reportservice
      . The default value is “reportservice”. To use the default value, press the Enter key.
    • Select Installation Mode
      .
      The default value is “Standalone”. To use the default value, press the Enter key. The modes include the following options:
      • Standalone for a standalone server or for a primary node in a cluster.
      • Cluster for secondary nodes in a cluster.
Post-Patch Installation
Complete the following actions after installing the JasperReports Server cumulative patch:
  • Clear the application server (Apache Tomcat Server)
    temp
    directory.
  • Clear the application server (Apache Tomcat Server)
    work
    directory.
  • Start the Apache Tomcat Server where JasperReports Server is deployed.
  • Clear the browser cache on the client.
Verify the JasperReports Server Cumulative Patch Installation
Complete the following steps to verify that the JasperReports Server cumulative patch installation was successful.
Follow these steps:
  1. Start the JasperReports Server, if it is not already started.
  2. Open the following URL:
    http://<domain_name>:<portnumber>/<jasperwebcontext>/
  3. Verify that you can open the JasperReports Server login page.
  4. Log in to the JasperReports Server using valid credentials.
  5. Open the following URL:
    http://<domain_name>:<portnumber>/<jasperwebcontext>/version.htm
  6. Verify the installed patch version:
    CA PPM Jaspersoft Release Patch Version = 5.1.0.2
JasperReports Server Post-Installation Configuration
After you complete and verify the JasperReports Server installation, perform the following tasks to configure JasperReports Server to work with 
Clarity Project and Portfolio Management (PPM)
.
Set Up the Data Warehouse
The Advanced Reporting content that includes out-of-the-box domains uses the Data Warehouse. After installing and configuring the JaspeReports server, run the Load Data Warehouse job to update the domains with custom attributes. We recommend that you set up the Data Warehouse before installing the JasperReports server. Later you only run the Load Data Warehouse job to update the domains.
Configure the JasperReports Server Properties
Set the server properties for the JasperReports Server in
Clarity Project and Portfolio Management (PPM)
System Administration (CSA).
Follow these steps:
  1. Log in to CSA.
    The default login URL for CSA depends on the application server that is running 
    Clarity Project and Portfolio Management (PPM)
    :
    • Apache Tomcat
      http://<
      hostname
      >:8090/niku/app
    • IBM Websphere
      http://<
      hostname
      >:9080/nsa/app
  2. Click Servers in the left navigation pane, and click the name of the local server in the list.
  3. With the Properties tab selected, click the Reporting subtab.
  4. In the Report Server: Jaspersoft section, complete the requested information. The following fields require an explanation:
    • Vendor
      Specifies the report vendor. For this section, only Jaspersoft is available.
    • Status
      Indicates whether the JasperReports Server is available.
    • Web URL
      Specifies the web URL for the JasperReports Server (for example,
      http://<jaspersoft-hostname>:8080/<jasperwebcontext>
      ).
    • User
      Specifies the JasperReports Server user name who performs system tasks that require administration access. The default user is ppmjasperadmin. You can change the default user name before you import Advanced Reporting content. The import creates the user.
      Do not
      change the user name after you import the Advanced Reporting content.
    • Database ID
      Not applicable.
    • Organization Name
      Specifies the organization name (tenant) that is created on the JasperReports Server.
    • Organization ID
      Specifies the organization ID (tenant) that is created on the JasperReports Server.
    Note:
     If the Report Server: Jaspersoft section is not available, configure the following tag in the <clarityInstallFolder>/properties.xml file:
    <reportServer id="jaspersoft" webUrl="http://<serverName>:<portnumber>/<jaspersoftwebcontext>" context="/<jaspersoftwebcontext>" home="" serviceUrl="http://<serverName>:<portnumber>" volumeName="" username="ppmJasperAdmin" vendor="jaspersoft" databaseId="Niku" jndiName="jdbc/clarity" dwJndiName="jdbc/dwh" orgName="<orgname>" orgId="<orgID>" />
  5. Click Save.
Generate the Key Store File
To authenticate 
Clarity Project and Portfolio Management (PPM)
 and JasperReports Server, generate a trusted key store for each organization.
If you are upgrading your product release, use the following procedure to regenerate the keys and copy the key store files.
Follow these steps:
  1. Go to <clarity_home>/bin.
  2. Run the following command to generate a key store from the CSA:
    admin jaspersoft keystore
     
    To specify key and password, enter the following: 
    admin jaspersoft generate [-key <key> -password <password>]
    These commands generate the following files in <install>/config/ and <install>/META-INF/reporting/store. 
    • <orgname>.jks (key store file)
    • <orgname>.properties (information about the key)
  3. Copy these files to <Tomcat>/webapps/<jasperwebcontext>/WEB-INF/config where Jaspersoft is installed. 
    Example: <Tomcat>/webapps/reportservice/WEB-INF/config
    For clustered environments, copy these files in the same location on each of the nodes in the cluster.
  4. Start the Tomcat service where the JasperReports Server is deployed.
    The Advanced Reporting content cannot be imported without starting the reporting service.
  5. For WebSphere, perform the following steps:
    1. Set JAVA_HOME to IBM JDK. 
      For example, SET JAVA_HOME=C:\PROGRA~2\IBM\WebSphere\AppServer\java_1.7_64
    2. Run the following command:
      admin jaspersoft keystore
  6. (Optional) Repeat the steps to regenerate the key or change the organization.
Execute the Installation Commands
Before you run the installation commands, verify that you have completed the following tasks:
  • Data Warehouse status is set to Available.
  • The Data Warehouse database link is created.
  • The Organization Name and Web URL are defined.
Follow these steps:
  1. Open a command prompt and navigate to the 
    Clarity Project and Portfolio Management (PPM)
     runtime bin directory.
  2. Run the following command: 
    admin content csk
    The installation process begins and information displays on the screen. The information is captured and stored in the admin.log file that is located in the logs directory. The output files are stored in the logs/content/xog/csk directory.
  3. Navigate to the 
    Clarity Project and Portfolio Management (PPM)
     runtime bin directory.
  4. Run the following command to import the Advanced Reporting content: 
    admin content-jaspersoft csk -userName superuser -password <password> 
  5. Review the screen output and the logs for important information after the installation completes.
Configure Users for Advanced Reporting
To set up Advanced Reporting with Jaspersoft, configure users for Advanced Reporting.
Follow these steps:
  1. Assign one of the following access rights to users working on Advanced Reporting:
    • Advanced Reporting - Navigate
      Allows a user to navigate to Advanced Reporting and use the tools as a Jaspersoft user.
    • Advanced Reporting - Administer
      Allows a user to navigate to Advanced Reporting and use the tools as a Jaspersoft administrator.
    • Advanced Reporting - Ad Hoc Create
      Allows a user to navigate to the Advanced Reporting page and create Ad Hoc Views. The user is assigned the following Jaspersoft roles: ROLE_USER and ROLE_ADHOC_DESIGNER.
    • Advanced Reporting - Dashboard Create
      Allows a user to navigate to the Advanced Reporting page and create dashboards. The user is assigned the following Jaspersoft roles: ROLE_USER and ROLE_DASHBOARD_DESIGNER.
    • Advanced Reporting - Data Source Create
      Allows a user to navigate to the Advanced Reporting page and create data sources. The user is assigned the following Jaspersoft roles: ROLE_USER and ROLE_DATASOURCE_DESIGNER.
    • Advanced Reporting - Domain Create
      Allows a user to navigate to the Advanced Reporting page and create domains. The user is assigned the following Jaspersoft roles: ROLE_USER and ROLE_DOMAIN_DESIGNER.
    • Advanced Reporting - Report Create
      Allows a user to navigate to the Advanced Reporting page and create reports. The user is assigned the following Jaspersoft roles: ROLE_USER and ROLE_REPORT_DESIGNER.
  2. Run the Create and Update Jaspersoft Users job to synchronize the 
    Clarity Project and Portfolio Management (PPM)
     users with assigned access rights to their corresponding Jaspersoft users and roles.
The PMO Accelerator add-in includes additional roles (CSK roles) that set permissions for repository items (such as reports and domains). For additional information about configuring users for CSK roles, see the
Advanced Reporting Product Guide
on the Advanced Reporting and Database Schema Index page of CA Support Online.
Run the Data Warehouse Jobs
Run the following jobs in the order provided.
Synchronize the 
Clarity Project and Portfolio Management (PPM)
 users with assigned access rights to their corresponding Jaspersoft users and roles: 
  • Create and Update Jaspersoft Users
Populate the Data Warehouse with data from the 
Clarity Project and Portfolio Management (PPM)
 database:
  • Time Slicing
    This job splits time varying data into a relational format.
    The first run of this job can take a substantial amount of time.
Load Data Warehouse
This job extracts the data from the 
Clarity Project and Portfolio Management (PPM)
 database, transforms the data, and loads the data into the Data Warehouse.
This job is initially disabled. Enable this job before you run it.
Before you run this job, open the properties for any custom object or attribute that you want to include and select the 
Include in the Data Warehouse
 option. This option must be selected for custom objects or attributes to be populated in the Data Warehouse.
If you are running the job for the first time to populate the Data Warehouse, select the Full Load configuration in the job parameters.
The following actions require you to rerun the Load Data Warehouse job after the initial population:
  • Deleting an attribute or clearing the Include in the Data Warehouse option for the attribute in Studio.
  • Changing the data type of an attribute, adding a language to the Data Warehouse, and changing a timeslice date to include a larger timeframe.
 
  • Load Data Warehouse Access Rights
    This job loads the access privileges for resources and investments from the 
    Clarity Project and Portfolio Management (PPM)
     database to the Data Warehouse.
     This job is initially disabled. Enable this job before you run it.
When the Load Data Warehouse Access Rights and Load Data Warehouse jobs run, the jobs write standard messages to the Jobs logs and detailed messages to the Data Warehouse logs. The default Data Warehouse log files are bg-dwh.log and bg-ca.log. To review the detailed Data Warehouse log messages, navigate to the Data Warehouse logs (under the standard Jobs logs) in
Clarity Project and Portfolio Management (PPM)
System Administration. You can enable more logging by changing the Kettle Log Level in
Clarity Project and Portfolio Management (PPM)
System Administration (Logs, Edit Configuration). Use the detailed messages to monitor job progress and to analyze Data Warehouse load failures.
Follow these steps:
  1. Open Home and from Personal, click Jobs.
  2. Locate the job that you want to run and click the name.
  3. Complete the requested information for the job.
    You can start the job immediately, or you can schedule it to run at a later time. You can also indicate resources or groups that you want to notify.
  4. Click Submit.
Restart the 
Clarity Project and Portfolio Management (PPM)
Services
Follow these steps:
  1. Log in to
    Clarity Project and Portfolio Management (PPM)
    System Administration.
  2. Open Home, and click All Services.
  3. Select the check boxes next to the
    Clarity Project and Portfolio Management (PPM)
    Application (app) and
    Clarity Project and Portfolio Management (PPM)
    Background (bg) services.
  4. Click Start.
Tips for Implementing and Managing Your Jaspersoft Installation
The following information can help you with the implementation and management of your JasperReports Server installation.
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.
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 in 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 Cache Distribution over RMI on JasperReport Servers
Follow these steps:
  1. Stop the Tomcat server.
  2. Go to <tomcat>/webapps/reportservice/WEB-INF.
  3. Open the -ehcache.xml file in an editor.
  4. Uncomment and configure the following XML element sections in the file.
    • <cacheManagerPeerProviderFactory
      class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
      properties="hostName=10.131.112.249,peerDiscovery=automatic,multicastGroupAddress=228.0.0.1,multicastGroupPort=4446,timeToLive=1"/>
    • <cacheManagerPeerListenerFactory
      class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
      properties="hostName=10.131.112.249,port=40011,remoteObjectPort=40012,socketTimeoutMillis=120000"/>
  5. Uncomment the following XML element sections to allow distribution of this cache:
    • <cacheEventListenerFactory
      class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
      properties="replicateAsynchronously=true, replicatePuts=false, replicateUpdates=true,replicateUpdatesViaCopy=false, replicateRemovals=true "/>
    • <bootstrapCacheLoaderFactory
      class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"
      properties="bootstrapAsynchronously=true, maximumChunkSizeBytes=5000000"/>
  6. Save the file.
  7. Uncomment and configure the same XML sections in
    <tomcat>/webapps/reportservice/WEB-INF/ehcache_hibernate.xml
    and
    <tomcat>/webapps/reportservice/WEB-INF/classes/ehcache_hibernate.xml
    .
  8. Repeat the steps for all of the instances of Jaspersoft that are available in the cluster.
  9. Before you start Tomcat, delete the Tomcat temp directory and the work/Catalina/localhost directory.
Configure a Dedicated JasperReports Server for Running Scheduled Reports
You can deploy the JasperReports Server as a standalone application or in a cluster for high concurrency.
You can dedicate JasperReports Server instances to act as scheduler instances and JasperReports Server instances to serve web requests. The instances serving web requests are part of the load balancer and are non-scheduler instances.
When deploying the JasperReports Server in a cluster, we recommend that you dedicate one or more JasperReports Server instances for processing scheduled reports. The dedicated instances share the same repository. They are not part of the load balancer that serves web requests such as running unscheduled reports or using the ad hoc views.        
In a standalone deployment, only a single JasperReports server instance is available. The single instance acts as the scheduler instance and is responsible for the following items:
  • Processing scheduled reports
  • Serving normal web requests
During interactive installation of the patch, you can specify whether you want to go for a dedicated scheduler instance. Answer 'no' if you are running only a single JasperReports Server instance.
If you answer 'yes', then specify whether you want to make the current instance where you are applying the patch a scheduler instance.
  • If you answer 'yes', then the patch performs the necessary configuration to make the current instance a scheduler instance.
  • If you answer 'no' (for instances which are part of the load balancer), the patch performs the necessary configuration to make the current instance a non-scheduler instance.
: Apply the patch to all the JasperReports Server instances. Also, select the appropriate option during installation to make the instance where you are applying the patch a scheduler or a non-scheduler instance.
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
Clarity Project and Portfolio Management (PPM)
instance.
Follow these steps:
Invoke the following commands from the
Clarity Project and Portfolio Management (PPM)
command-line interface:
  • Run the following command to add trusted email domains.
    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:
  • Read me file (pre-installation)
  • version.html file that is created after you install JasperReports Server (post installation). 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 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 Project and Portfolio Management (PPM)
     is installed.
  3. Navigate to jre\lib\security. 
    Example:
    C:\jdks\jdk1.8.0_40\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 Project and Portfolio Management (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:
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.
Restart the JasperReports Server Tomcat Services
Complete the following steps to stop or start JasperReports Server.
Follow these steps:
  1. Navigate to the <tomcathome>/bin directory.
  2. To stop, run one of the following files:
    • shutdown.sh (Linux)
    • shutdown.bat (Windows)
  3. To restart, run one of the following files:
    • startup.sh (Linux)
    • startup.bat (Windows)
Uninstall JasperReports Server
Follow these steps:
  1. Stop the Tomcat service where the JasperReports Server is deployed.
  2. Rename the existing 
    <jasperwebcontext>
     folder.
  3. Back up the JasperReports Server database.
  4. Delete the JasperReports Server database from the database server.
Troubleshooting JasperReports Server
The following troubleshooting information includes issue descriptions and resolutions.
Failed to Update Properties on the Jaspersoft Server
While saving the Data Warehouse properties in
Clarity Project and Portfolio Management (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 Project and Portfolio Management (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 Project and Portfolio Management (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
    Clarity Project and Portfolio Management (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 be the result of the following reason:
  • 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\
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:
Follow these steps.
  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 Stuck on the Advanced Reporting Page
When you access the Advanced Reporting page, you may see the “Please Wait” message that does not go away. See KB article: TEC1237912 for details about workarounds to resolve the issue.