Procedure for Installing and Deploying the WAR File in WebSphere¶
Perform the procedures in this section to install and deploy the JasperReports Server WAR file in WebSphere.
Installing WebSphere and a Database¶
To install WebSphere and a database
- Make sure you are using a supported version of WebSphere. See the TIBCO JasperReports Server Supported Platform Datasheet for more information.
- Check that the WebSphere installation created a JAVA_HOME system environment variable. The variable needs to be set to the JAVA directory in the WebSphere installation.
- Install the database (PostgreSQL, MySQL, Oracle, SQL Server, or DB2).
Note
The target database can be on a remote server. WebSphere should reside on the local machine.
Preparing Server Files¶
To prepare JasperReports Server files
-
Unpack
js-jrs``_10.1.0_bin.zip to a top-level directory. Unpacking the ZIP file creates the directory
js-jrs_``pro`` _10.1.0_bin.zip.
-
(Required) Manually create and load the JasperReports Server database.
-
(Optional) Manually create and load the sample databases. See Manually Creating the JasperReports Server Database for instructions.
-
(Required) Manually import the default users and organization.
-
Copy the
<dbType>_master.propertiesfile for your database fromsample_confand paste it tobuildomatic:cd <js-install>/buildomatic- Copy from:
<js-install>/buildomatic/sample_conf - Paste to:
<js-install>/buildomatic
For example, copysample_conf/postgresql_master.propertiestobuildomatic.
-
Rename the file that you copied to
default_master.properties. -
Edit the
default_master.propertiesfile:- Set
appServerTypetoskipAppServerCheck. - Change
dbUsername,dbPassword, anddbHostto the appropriate settings for your database. - If you are using a port other than the default for your database, or if you have installed the database on a remote machine, change the
dbPortfield under Custom Properties to the appropriate settings.
For the Split installation, configure the additional settings in the
default_master.propertiesfile as described in Additional Buildomatic Configuration for Split Installation Upgrade.For the JNDI restricted access installation, configure the additional settings in the
default_master.propertiesfile as described in Installation Types.Each
sample_conf/<dbType>_master.propertiesfile contains appropriate sample values. - Set
-
Start your database server.
-
Open a Command Prompt as Administrator and run these commands:
Buildomatic Targets to Execute
Commands
Description
cd <js-install>/buildomaticGo to the buildomatic directory.
js-ant create-js-dbCreate the jasperserver repository database. js-ant init-js-db-projs-ant import-minimal-proInitializes database, loads core application data.
js-ant create-sugarcrm-dbjs-ant create-foodmart-db(Optional) Creates sample databases. js-ant load-sugarcrm-dbjs-ant load-foodmart-db(Optional) Loads sample data into the sample databases. js-ant import-sample-data-pro(Optional) Loads the demos that use the sample data.
js-ant create-audit-db(Optional) Creates the audit database. Required only for the Split installation.
js-ant init-audit-db-pro(Optional) Initializes the audit database. Required only for the Split installation.
-
-
Set up your license file. For more information, refer to Setting Up the JasperReports Server License.
Note
Installing JasperReports Server automatically generates encryption keys that reside on the file system. These keys are stored in a dedicated Jaspersoft keystore. Make sure that this keystore is properly secured and backed up, as described in the JasperReports Server Security Guide.
Configuring CSRFGuard, Hibernate, Quartz, and WebSphere Settings¶
Before deploying the JasperReports Server WAR file, update the CSRFGuard, Hibernate, Quartz, and settings as described here.
Configure CSRFGuard, Hibernate, and Quartz settings in the WAR file
-
The WAR file is an archive format in a single file.
-
Extract the
Websphere.jrs.csrfguard.propertiesfile using the following command:cd <js-install> "%JAVA_HOME%/bin/jar" xf jasperserver-pro.war WEB-INF/csrf/Websphere.jrs.csrfguard.propertiesThis creates the
WEB-INF/csrffolder in the current location and places the extracted file there. -
Rename the file from
Websphere.jrs.csrfguard.propertiestojrs.csrfguard.propertiesusing the following command:
-
-
Extract and rename the
web-version24.xmlfile using the commands below:cd <js-install> "%JAVA_HOME%/bin/jar" xf jasperserver-pro.war WEB-INF/web-version24.xml mv ./WEB-INF/web-version24.xml ./WEB-INF/web.xmlThe
jarcommand creates theWEB-INFfolder in the current location and places the extracted file there.Open the
WEB-INF/web.xmlfile for editing and replace every occurrence of<res-type>javax.sql.ConnectionPoolDataSource</res-type>With
<res-type>javax.sql.DataSource</res-type>For example, change the following:
<resource-ref> <description>JasperServer Metadata repository</description> <res-ref-name>jdbc/jasperserver</res-ref-name> <res-type>javax.sql.ConnectionPoolDataSource</res-type> <res-auth>Container</res-auth> </resource-ref>To:
<resource-ref> <description>JasperServer Metadata repository</description> <res-ref-name>jdbc/jasperserver</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref>Do the same for the Supermart, Foodmart, Audit, System Analytics and Audit Analytics databases.
-
Enable Hibernate persistence:
-
Extract the
applicationContext.xmlfile using the commands below: -
Uncomment the following line:
-
In the same file, find the
profileAttributesResolverbean:<bean id="profileAttributesResolver" class="com.jaspersoft.jasperserver.api.metadata.user.service.impl.ProfileAttributesResolverImpl">Add
depends-on="HibernatePersistenceResolverWebsphereFixto it:
-
-
Copy the already configured files for
hibernate.propertiesandjs.quartz.propertiesto theWEB-INFfolder.(Buildomatic configured these files for your database type in the steps above.)
From:
<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/classes/hibernate.properties<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/js.quartz.propertiesTo:
<js-install>/WEB-INF/classesCopy the
../buildomatic/keystore.init.propertiesfile needs to the../WEB-INF/classesdirectory. -
Edit the scheduler URI port value for WebSphere in the
js.quartz.properties:Edit
js.quartz.properties:Set:
report.scheduler.web.deployment.uri=http://localhost:8080/jasperserver-proTo:
report.scheduler.web.deployment.uri=http://localhost:9080/jasperserver-pro -
If you want to configure JasperReports Server to automatically schedule and email reports, enter your mail server information in the
js.quartz.propertiesfile. Modify allreport.scheduler.mail.sender.*properties for your mail server. -
Now that you have modified/updated the individual configuration files, you must replace them in the WAR file archive using the following commands.
cd <js-install> "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/classes/hibernate.properties "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/js.quartz.properties "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/csrf/jrs.csrfguard.properties "%JAVA_HOME%\bin\jar" uf jasperserver-pro.war WEB-INF/applicationContext.xml -
If you have modified the
web.xmlfile, replace that file in the WAR file archive using the following additional commands. -
Enter the following additional commands:
cd <js-install> zip -d jasperserver-pro.war WEB-INF/lib/stax-api-1.0.2.jar zip -d jasperserver-pro.war WEB-INF/lib/xercesImpl-2.12.0.jar zip -d jasperserver-pro.war WEB-INF/lib/jta-1.1.jar zip -d jasperserver-pro.war WEB-INF/lib/xml-apis-1.4.01.jar zip -d jasperserver-pro.war WEB-INF/lib/javax.el-2.2.4.jar zip -d jasperserver-pro.war WEB-INF/lib/javax.el-api-2.2.4.jar zip -d jasperserver-pro.war WEB-INF/lib/batik\* -
Add the latest
batik-all.jarfrom Websphere:-
Find the jar using the following command:
-
Copy the file into a lib directory in the
jasperserver-pro.warfile, for example:
-
-
Clean up your file system by deleting the
WEB-INFdirectory that you created along with the edited files it contains.
Configuring a JDBC Provider in WebSphere¶
To configure a JDBC Provider in WebSphere
-
Launch the WebSphere Administrative Console and navigate to Resources > JDBC > JDBC Providers.
-
On the JDBC providers page, click the Guided Activity link at the top of the JDBC Providers page and follow the Integrated Solutions Console instructions:
- Configure credentials for a secure database:
-
Use the J2C authentication aliases panel to create a new authenticated user.
-
In Global Security, click New and enter the user alias, user ID, and password. The following table shows the credentials that WebSphere uses to access the database.
J2C Authentication Alias Settings
Alias Example User ID Example Password PostgreSQL postgresql_jasperdb postgres postgres MySQL mysql_jasperdb root password Oracle jasperserver_user jasperserver password DB2 db2admin_user db2inst1 password SQL Server jasperserver_user sa sa -
Connect to a database panel. From the Scope drop-down, choose
Node:<node_name>,Server=<server_name>- Click the New button to create a new JDBC Provider.
- Select your database type:
-
If you are using PostgreSQL or MySQL — select User-defined.
-
If you want to use the JDBC driver built and distributed by the MySQL project, see MySQL Example
-
If you are using the DB2, Oracle, or SQL Server — select the appropriate database.
-
Select or enter these options. Your options depend on your database type.
Database type Implementation class name or type Name User-defined (PostgreSQL)
org.postgresql.jdbc2.optional.ConnectionPoolPostgreSQL JDBC Provider
User-defined
(MySQL)org.mariadb.jdbc.MySQLDataSourceMySQL JDBC Provider
User-defined
(MySQL)com.mysql.jdbc.jdbc2.optional.
MysqlConnectionPoolDataSourceMySQL JDBC Provider
DB2 Universal JDBC Driver Provider
Connection pool data source
DB2 Universal JDBC Driver Provider
Oracle
Connection pool data source
Oracle JDBC Driver
SQL Server
Connection pool data source
Microsoft SQL Server JDBC Driver
-
Click
Nextand enter the database classpath information for the JDBC provider.-
For PostgreSQL, MySQL, Oracle, SQL Server, and DB2, enter the following:
<js-install>\buildomatic\conf_source\db\<your_database>\jdbc\For example, enter:
C:\js-jrs``_10.1.0_bin\buildomatic\conf_source\db\postgresql\jdbc\postgresql-42.2.5.jar
Alternatively, you can copy the jar to a location in your WebSphere deployment and specify that location for the JDBC driver path.
Note
If JasperReports Server is deployed on the same host as DB2, delete the following file to avoid conflicts:
<db2>/SQLLIB/java/db2jcc.jar
-
-
To ensure you have full support for import/export from the command line, copy your JDBC driver to the following location. If you are not using the command line for import/export, you can skip this step:
from: <js-install>\buildomatic\conf_source\db\<your_database>\jdbc\to: <js-install>\buildomatic\conf_source\iePro\lib -
Click Next to proceed to the next step.
-
Review the JDBC provider information that you entered and click Finish.
To define the jasperserver JDBC data source and expose it through JNDI
-
Click the name of the JDBC provider that you just created. For example, for PostgreSQL, click PostgreSQL JDBC Provider.
Note
To use a database other than PostgreSQL, configure the database connections and custom properties as described in Configuring Other Database Connections .
-
Click Data sources in the Additional Properties of the JDBC provider details panel.
-
To create a new data source, click New. The New Data Source wizard appears.
-
Enter the data source name:
jasperserver -
Enter the JNDI name:
jdbc/jasperserver -
Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider from the drop-down list.
-
Click Next and accept the default helper class (
com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the checkbox to use this data source in container managed persistence (CMP). -
Click Next and select the Setup security aliases, as shown in the following table.
Field Name PostgreSQL Value Component-managed authentication alias postgresql_jasperdbMapping configuration alias DefaultPrincipalMapping Container-managed authentication alias postgresql_jasperdb -
Click Next, review the summary information, and click Finish.
To set the connection pool size
- In the list of JDBC data sources, click the newly created jasperserver data source to edit it.
- Click Additional Properties > Connection Pool Properties. You can see that Maximum Connections is set to 10 by default.
- Set Maximum Connections to 50. You may want to set it to a higher value if necessary.
- Click Save.
To define custom properties
-
In the list of JDBC data sources, select the check box for the newly created jasperserver data source and click Test Connection.
In the Messages area, a success or failure message appears. The failure message gives you information about which custom properties you need to define.
-
Navigate to the jasperserver data sources General Properties page.
-
In Additional Properties, on the right side of the General Properties page, click Custom properties.
-
Scroll down the list of properties and select databaseName. Set the value to
jasperserver. -
Set serverName to the correct value for your server.
To define the jsSystemAnalytics JDBC data source and expose it through JNDI
-
Click the name of the JDBC provider that you just created. For example, for PostgreSQL, click PostgreSQL JDBC Provider.
Note
To use a database other than PostgreSQL, configure the database connections and custom properties as described in Configuring Other Database Connections.
-
Click Data sources in the Additional Properties of the JDBC provider details panel.
-
To create a new data source, click New. The New Data Source Wizard appears.
-
Enter the data source name:
jsSystemAnalytics -
Enter the JNDI name:
jdbc/jasperserverSystemAnalytics -
Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider from the drop-down list.
-
Click Next and accept the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the checkbox to use this data source in container managed persistence (CMP).
-
Click Next and select the Setup security aliases, as shown in the following table.
Field Name PostgreSQL Value Component-managed authentication alias postgresql_jasperdbMapping configuration alias DefaultPrincipalMapping Container-managed authentication alias postgresql_jasperdb -
Click Next, review the summary information, and click Finish.
To set the connection pool size
- In the list of JDBC data sources, click the newly created jsSystemAnalytics data source to edit it.
- Click Additional Properties > Connection Pool Properties. You can see that Maximum Connections is set to 10 by default.
- Set Maximum Connections to 50. You may want to set it to a higher value if necessary.
- Click Save.
To define custom properties
-
In the list of JDBC data sources, select the check box for the newly created jsSystemAnalytics data source and click Test Connection.
In the Messages area, a success or failure message appears. The failure message gives you information about which custom properties you need to define.
-
Navigate to the jasperserver data sources General Properties page.
-
In Additional Properties, on the right side of the General Properties page, click Custom properties.
-
Scroll down the list of properties and select databaseName. Set the value to
jsSystemAnalytics. -
Set serverName to the correct value for your server.
To define the jsaudit JDBC data source and expose it through JNDI
-
Click the name of the JDBC provider that you just created. For example, for PostgreSQL, click PostgreSQL JDBC Provider.
Note
To use a database other than PostgreSQL, configure the database connections and custom properties as described in Configuring Other Database Connections.
-
Click Data sources in the Additional Properties of the JDBC provider details panel.
-
To create a new data source, click New. The New Data Source Wizard appears.
-
Enter the data source name:
jsaudit -
Enter the JNDI name:
jdbc/jasperserverAudit -
Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider from the drop-down list.
-
Click Next and accept the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the check box to use this data source in container managed persistence (CMP).
-
Click Next and select the Setup security aliases, as shown in the following table.
Field Name PostgreSQL Value Component-managed authentication alias postgresql_jasperdbMapping configuration alias DefaultPrincipalMapping Container-managed authentication alias postgresql_jasperdb -
Click Next, review the summary information, and click Finish.
To set the connection pool size
- In the list of JDBC data sources, click the newly created jsaudit data source to edit it.
- Click Additional Properties > Connection Pool Properties. You can see that Maximum Connections is set to 10 by default.
- Set Maximum Connections to 50. You may want to set it to a higher value if necessary.
- Click Save.
To define custom properties
-
In the list of JDBC data sources, select the check box for the newly created jsaudit data source and click Test Connection.
In the Messages area, a success or failure message appears. The failure message gives you information about which custom properties you need to define.
Note
If you are using the TIBCO JDBC driver with SQL Server, and you see an error such as the following:
Could not find stored procedure 'master..xp_jdbc_open2' DSRA0010E: SQL State = HY000, Error Code=2,812Add the following variable to Custom properties:
enable2Phase = false -
Navigate to the jsaudit data sources General Properties page.
-
In Additional Properties, on the right side of the General Properties page, click Custom properties.
-
Scroll down the list of properties and select databaseName. Set the value to:
-
-
-
For Compact installation:
jasperserver -
For Split installation:
jsaudit- Set serverName to the correct value for your server.
To create optional sugarcrm and foodmart data sources
-
If you plan to run the sample reports, use the values in the following table to create the foodmart and sugarcrm JNDI data sources.
Field Name Value Data source name
foodmartsugarcrmJNDI name
jdbc/foodmartjdbc/sugarcrm -
Click Save directly to the master configuration.
Next, deploy the WAR file in WebSphere as described in Deploying the WAR File in WebSphere.
To define the jsAuditAnalytics JDBC data source and expose it through JNDI
-
Click the name of the JDBC provider that you just created. For example, for PostgreSQL, click PostgreSQL JDBC Provider.
Note
To use a database other than PostgreSQL, configure the database connections and custom properties as described in Configuring Other Database Connections.
-
Click Data sources in the Additional Properties of the JDBC provider details panel.
-
To create a new data source, click New. The New Data Source Wizard appears.
-
Enter the data source name:
jsAuditAnalytics -
Enter the JNDI name:
jdbc/jasperserverAuditAnalytics -
Click Next, choose Select an existing JDBC provider, then select PostgreSQL JDBC Provider from the drop-down list.
-
Click Next and accept the default helper class (com.ibm.websphere.rsadapter.GenericDataStoreHelper). Select the check box to use this data source in container managed persistence (CMP).
-
Click Next and select the Setup security aliases, as shown in the following table.
Field Name PostgreSQL Value Component-managed authentication alias postgresql_jasperdbMapping configuration alias DefaultPrincipalMapping Container-managed authentication alias postgresql_jasperdb -
Click Next, review the summary information, and click Finish.
To set the connection pool size
- In the list of JDBC data sources, click the newly created jsaudit data source to edit it.
- Click Additional Properties > Connection Pool Properties. You can see that Maximum Connections is set to 10 by default.
- Set Maximum Connections to 50. You may want to set it to a higher value if necessary.
- Click Save.
To define custom properties
-
In the list of JDBC data sources, select the check box for the newly created jsAuditAnalytics data source and click Test Connection.
In the Messages area, a success or failure message appears. The failure message gives you information about which custom properties you need to define.
-
Navigate to the jsaudit data sources General Properties page.
-
In Additional Properties, on the right side of the General Properties page, click Custom properties.
-
Scroll down the list of properties and select databaseName. Set the value to:
-
For Compact installation:
jasperserver -
For Split installation:
jsaudit
-
-
Set serverName to the correct value for your server.
Deploying the WAR File in WebSphere¶
To deploy the JasperReports Server WAR file in WebSphere
-
In the Administrative Console, navigate to *Applications > New Application* and select New Enterprise Application.
JasperReports Server is a modern application, based on Java Servlet version 2.4, so you do not select the older, WebSphere V4‑compliant application type.
-
Browse to
<js-install>/jasperserver-pro.waron the local file system. Keep the default setting (Fast path) selected and click Next. -
On the Select installation options page, accept all the default settings and click Next.
-
On the Map modules to servers page, make sure the JasperReports Server module is mapped to the cell, node, and server that you want. Click Next.
-
On the Map modules to servers page, select jasperserver. Click Next.
-
On the Map resource references to resources page, map the resources you want:
- First, select the Browse button under the
jdbc/jasperserverresource. In the page that opens, select the jdbc/jasperserver radio button, and click Apply. Then select the check box next to the jdbc/jasperserver resource. - Select the Browse button under the
jdbc/jasperserverAuditresource. In the page that opens, select the jdbc/jasperserverAudit radio button, and click Apply. Then select the check box next to the jdbc/jasperserverAudit resource. - Select the Browse button under the
jdbc/jasperserverSystemAnalyticsresource. In the page that opens, select the jdbc/jasperserverSystemAnalytics radio button, and click Apply. Then select the check box next to the jdbc/jasperserverSystemAnalytics resource. - Select the Browse button under the
jdbc/jasperserverAuditAnalyticsresource. In the page that opens, select the jdbc/jasperserverAuditAnalytics radio button, and click Apply. Then select the check box next to the jdbc/jasperserverAuditAnalytics resource. - If you plan to run the sample reports, follow the same steps for
jdbc/surgarcrmandjdbc/foodmart, making sure to select the correct radio button for each one. - When you have mapped all resources, select the check boxes next to every resource have mapped.
- Click Next.
- First, select the Browse button under the
-
On the Map virtual hosts page, choose the JasperServer UI application module. Click Next.
-
In the Map context roots for Web modules, enter
jasperserver-pro. -
Click Next, review the summary information and start the installation process. (The installation process may take a while.)
-
Click Save directly to the master configuration.
Setting JVM Options¶
To set the Java JVM Options
For the JasperReports Server XML/A functionality to work, special Java JVM options need to be set to resolve class conflicts between the WebSphere and JasperReports Server web services implementation. JVM options also provide the optimal resources for running JasperReports Server.
To configure your Java JVM options
-
Select *Enterprise Applications > jasperserver-pro_war > Target specific application status > (server name)*.
-
Expand *Java and Process Management* > Process Definition > Java Virtual Machine > Generic JVM arguments.
-
In the Generic JVM Options text box, paste in the following JVM options that explicitly specify JasperReports Server classes for Xalan, as well as optimize JVM resources. The memory settings are a recommended minimum; you may need to increase the memory assigned to the JVM according to your usage:
Generic JVM Options on Windows
Options for all databases
-Dclient.encoding.override=UTF-8 -Xms2048m -Xmx4096m -Xss2m -XX:+UseG1GC -Dlog4j.configurationFile=WEB-INF/log4j2.propertiesAdditional option for Oracle
-Doracle.jdbc.defaultNChar=trueAdditional option for FTPS connections -Dcom.ibm.jsse2.overrideDefaultTLS=trueGeneric JVM Options on Linux
Options for all databases
-Dclient.encoding.override=UTF-8 -Xms2048m -Xmx4096m -Xss2m -XX:+UseG1GC -Dlog4j.configurationFile=WEB-INF/log4j2.propertiesAdditional option for Oracle
-Doracle.jdbc.defaultNChar=trueAdditional option for FTPS connections -Dcom.ibm.jsse2.overrideDefaultTLS=trueNote
Setting the Oracle localization option,
defaultNChar, can substantially impact the performance of JDBC queries. If you don't need to support UTF-8 for your Oracle database, you can omit this setting. -
Click Save on the console task bar.
To configure class loading
- Select Enterprise Applications > jasperserver-pro_war > Class loading and update detection.
- In the section Class loader order, select Classes loaded with local class loader first (parent last).
- In the WAR class loader policy section select Single class loader for application.
- Save directly to your master configuration.
- Restart WebSphere.
Next, start JasperReports Server as described in Starting and Restarting JasperReports Server.