Installing JasperReports Server manually on Windows

The steps you need to follow to install JasperReports Server (JRS) manually on Windows.

Before you begin

Make sure you have installed Microsoft SQL Management Studio (MSSQL DB) or Oracle SQL Developer (Oracle DB) on your local machine. You also need a working instance of WorldServer 11.x (with Java 17 and Tomcat 9).

If possible, place WorldServer and JRS on different Java virtual machines. If you already have an instance of Tomcat on your machine, make sure that it is stopped before you start to install JRS.

About this task

The following procedure applies to the configuration of the JasperReports Server engine for WorldServer 11.x. Only users with administrator permissions can install JasperReports Server. You can find the JasperReports Server installation kit on the WorldServer FTP, in the integrations\JasperSoft_<version> folder of the WorldServer distribution kit.

Procedure

  1. Go to the integrations\JasperSoft_<version> folder of the WorldServer distribution kit and extract the jasperreports-server-<version>-bin.zip package to a path of your choice, such as C:\Jasper\jasperreports-server-<version>-bin.
  2. The jasperreports-server-<version>-bin.zip package contains a folder called Reports, in which you can find Tomcat 9. Copy that folder to one of the following paths:
    • If you installed WorldServer 11.x by using the installer, copy the Reports folder to C:\Program Files\Idiom.
    • If you installed WorldServer 11.x by using Tomcat, copy the Reports folder to C:\Program Files\Apache Software Foundation.
    • A path of your choice for the Tomcat installation.
  3. Open a command prompt (CMD) as an administrator and enter the following commands in the order in which they are presented:
    CommandNotes
    set JAVA_HOME=<JDK_home_path>Replace <JDK_home_path> with the path of the Java installation directory up to the \bin folder.
    set Path=%JAVA_HOME%\bin;%Path%This is to set the Path variable.
    java -versionThis is to make sure that your system is now running on Java 17 (for WorldServer 11.8.2) or Java 11 (for WorldServer 11.8.0 and 11.8.1).
    cd C:\<js-install>\jasperreports-server-<version>-bin\buildomaticReplace <js-install> with the path where you extracted the jasperreports-server-<version>-bin.zip package.
    edit the js-install-service.bat scriptReplace <REPORTS_HOME> and <JAVA_HOME> with their actual paths; for example, C:\Program Files\...\Reports and C:\java17\jdk-17.0.6+10.
    @ECHO OFF
    set REPORTS_HOME=<path to Reports home ...\Reports>
    set JAVA_HOME=<path to JAVA home ...java17\jdk-17.0.6+10>
     
    echo Reports home:  %REPORTS_HOME%
    echo JAVA_HOME:  %JAVA_HOME%
     
    set "reply=y"
    set /p "reply=Are the paths above correct ? [y|n]: "
    if /i not "%reply%" == "y" goto :eof
     
    :install
    rem Install reports as service Worldserver reports
    rem To delete the service: "%REPORTS_HOME%\tomcat\bin\tomcat9.exe" //DS//WorldServerReports
    "%REPORTS_HOME%\tomcat\bin\tomcat9.exe" //IS//WorldServerReports --DisplayName="WorldServer Reports" ^
     --Install="%REPORTS_HOME%\tomcat\bin\tomcat9.exe" ^
     --Jvm="%JAVA_HOME%\bin\server\jvm.dll" ^
     --StartMode=jvm --StopMode=jvm ^
     --StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start ^
     --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop ^
     --Classpath "%REPORTS_HOME%\tomcat\bin\bootstrap.jar;%REPORTS_HOME%\tomcat\bin\tomcat-juli.jar" ^
     --JvmMs 512 ^
     --JvmMx 1024 ^
     --LogPath="%REPORTS_HOME%\tomcat\logs" ^
     --StdOutput=auto --StdError=auto ^
     ++JvmOptions="-Xmx1024m;-Xms512m;-XX:+UseConcMarkSweepGC;-XX:+CMSClassUnloadingEnabled;-Djs.license.directory=%REPORTS_HOME%"
    echo "Installed WorldServer Reports at %REPORTS_HOME%"
     
    :eof
    js.install-service.batInstalls Tomcat 9 as a service named WorldServer Reports. Make sure the correct paths for Tomcat, Java, and the JasperReports Server installation directory (<js-install>) are included.
  4. Run WorldServerReportsw.exe from the Reports\tomcat\bin directory to check the service configuration and make changes if necessary.
  5. If you are running both WorldServer and JasperReports Server on the same machine, go to <js-install>\Reports\tomcat\conf, open the server.xml file with a text editor, and make sure that the Tomcat ports in the following entries are different from the ports used by the WorldServer Tomcat server:
    Connector port="<port>" protocol="org.apache.coyote.http11.Http11Protocol"
    Server port="<port>" shutdown="SHUTDOWN"
    "Connector port="<port>" protocol="AJP/1.3" redirectPort="<port>"
  6. Go to <js-install>\buildomatic\sample_conf and copy the sqlserver_master.properties or oracle_master.properties file (depending on the type of relational database management system you use on your machine) to <js-install>\buildomatic, and then rename it to default_master.properties.
  7. Open the default_master.properties file and set the following properties:
    Property nameDescription
    appServerTypeThis should always be tomcat.
    appServerDirThis path should be <js-install>\\Reports\\tomcat (for example, C:\\Jasper\\jasperreports-server-9.0.0-bin\\Reports\\tomcat).
    dbTypeIf you copied and renamed the correct file in the previous step, do not change the value of this property.
    dbHostThe name of the database server or its IP address.
    dbPortThe database port (if it is different than the default one).
    sidThe SID for Oracle databases.
    dbUsernameThe username that will be used to log in to the JasperReports Server database.
    dbPasswordThe password that will be used to log in to the database. Do not encrypt it.
    sysUsernameOnly on Oracle databases. If you want to create and deploy the JasperReports Server database automatically, enter the username of the database administrator. If you want to create and deploy the database manually, enter the same value as for dbUsername.
    sysPasswordOnly on Oracle databases. If you want to create and deploy the JasperReports Server database automatically, enter the password of the database administrator. If you want to create and deploy the database manually, enter the same value as for dbPassword.
    js.dbNameUncomment this property and enter a name for the database on which you want your new JasperReports Server version to run. This database will be created automatically. This is particularly important if you are upgrading from a previous version of JasperReports Server, because using the same database on multiple versions will lead to an unsuccessful installation.
    webAppNameProOptional: If you want to change the folder name (thus, making it part of the URL), uncomment this property and enter a new name. The default name is jasperserver-pro.
    encryptSet this property to true for database passwords to be encrypted in configuration files. During the installation, this property creates certain encryption keys in the user's home folder.
  8. Optional: If you want to configure JasperReports Server to use encrypted communication with your database, go to <js-install>\buildomatic\conf_source\db\<database-type> (sqlserver or oracle) and open the db.template.properties file with a text editor. Then, modify lines 10-13 as follows:
    SQL Server
    admin.jdbcUrl=jdbc:tibcosoftware:sqlserver://<dbHost>;sendTimestampEscapeAsString=false;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/<certificate-name>.<certificate-extension>;TrustStorePassword=<truststore-password>
    js.jdbcUrl=jdbc:tibcosoftware:sqlserver://<dbHost>;databaseName=<js.dbName>;sendTimestampEscapeAsString=false;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/<certificate-name>.<certificate-extension>;TrustStorePassword=<truststore-password>
    sugarcrm.jdbcUrl=jdbc:tibcosoftware:sqlserver://<dbHost>;databaseName=<sugarcrm.dbName>;sendTimestampEscapeAsString=false;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/<certificate-name>.<certificate-extension>;TrustStorePassword=<truststore-password>
    foodmart.jdbcUrl=jdbc:tibcosoftware:sqlserver://<dbHost>;databaseName=<foodmart.dbName>;sendTimestampEscapeAsString=false;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/<certificate-name>.<certificate-extension>;TrustStorePassword=<truststore-password>
    Oracle
    admin.jdbcUrl=jdbc:tibcosoftware:oracle://<dbHost>:<dbPort>;<SID-or-service-name><additional-Admin-properties>;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/cwallet.sso;TrustStoreType=SSO;CryptoProtocolVersion=TLSv1.2;
    js.jdbcUrl=jdbc:tibcosoftware:oracle://<dbHost>:<dbPort>;<SID-or-service-name><additional-Admin-properties>;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/cwallet.sso;TrustStoreType=SSO;CryptoProtocolVersion=TLSv1.2;
    sugarcrm.jdbcUrl=jdbc:tibcosoftware:oracle://<dbHost>:<dbPort>;CatalogOptions=0;<SID-or-service-name>;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/cwallet.sso;TrustStoreType=SSO;CryptoProtocolVersion=TLSv1.2;
    foodmart.jdbcUrl=jdbc:tibcosoftware:oracle://<dbHost>:<dbPort>;CatalogOptions=0;<SID-or-service-name>;EncryptionMethod=SSL;TrustStore=<path-to-certificate>\/cwallet.sso;TrustStoreType=SSO;CryptoProtocolVersion=TLSv1.2;
    In this case:
    • <dbHost> is the fully qualified domain name of your database server.
    • <dbPort> (only for Oracle) is the port on which your database server is running.
    • <SID-or-service-name> (only for Oracle) is the SID or the service name of your Oracle database.
    • <js.dbName> (only for SQL Server) is the name of your JasperReports Server database.
    • <path-to-certificate> is the path to your TrustStore certificate; for example, C:\/WorldServer\/SQL_Certificate.
    • <certificate-name> (only for SQL Server) is the name of your certificate; for example, sql_cert.
    • <certificate-extension> (only for SQL Server) is the extension of your certificate file; for example, .pfx.
    • <truststore-password> (only for SQL Server) is the password used to access the certificate file.
  9. Install the JasperReports Server database and deploy the JasperReports Server web app: $ <js-install>/buildomatic /js-install.bat minimal
  10. Copy the following JasperReports Server repository files and key files from the WorldServer distribution kit (integrations\JasperSoft_<version>\jasperreports-server-repository) to the <js-install> directory:
    • Oracle: FullRepo_WorldServerOra.zip, FullRepo_WorldServerOra_Key.txt
    • SQL Server: FullRepo_WorldServerSql.zip, FullRepo_WorldServerSql_Key.txt
  11. Import the WorldServer repository resources:
    1. Open the appropriate FullRepo_WorldServer*_key.txt file (Sql or Ora) and copy the secret key.
    2. Run the full import command and make changes as appropriate:
      cd <js-install>\buildomatic
      
      js-import.bat  --update  --input-zip <js-install>\FullRepo_WorldServer(Sql_or_Ora).zip   --secret-key "<paste-key-here>"
      
  12. Go to <js-install>\Reports\tomcat\webapps\jasperserver-pro\WEB-INF and open the applicationContext-worldserver.xml file with a text editor. In the applicationContext-worldserver.xml file, configure the wsLoginUrl and wsRestAuthUrl properties as follows:
    <property name="wsLoginUrl">
        <value><ws-protocol>://<ws-host>:<ws-port>/ws-legacy/login</value>
    </property>
    <property name="wsRestAuthUrl">
        <value><ws-protocol>://<ws-host>:<ws-port>/ws-api/v2/login/checkToken</value>
    </property>
    In this case, <ws-protocol> is the protocol on which WorldServer is installed (http or https), <ws-host> is the name or the IP address of the machine on which WorldServer is installed, and <ws-port> is the number of the port on which WorldServer is installed. Save and close the applicationContext-worldserver.xml file when finished.
  13. Go to <js-install>\Reports\tomcat\webapps\jasperserver-pro\WEB-INF and open the applicationContext-security-pro-web.xml file with a text editor. In the applicationContext-security-pro-web.xml file, add the WorldServer domain as allowed to the additionalWhitelistAttributes property:
    <property name="additionalWhitelistAttributes">
    	...
    	<list>
    		<value><ws-protocol>://<ws-host>:<ws-port></value>
    	</list>
    </property>
    Save and close the applicationContext-security-pro-web.xml file when finished.
  14. On the WorldServer installation machine, go to the path where the WorldServer configuration files are stored and create a file called reports.properties. Add the following properties:
    • report_center_url=http://<jasper-host>:<jasper-port>/<webAppNamePro-value>/flow.html?_flowId=searchFlow&mode=search&filterId=resourceTypeFilter&filterOption=resourceTypeFilter-reports, where <jasper-host> is the name or the IP address of the machine on which JasperReports Server is installed, <jasper-port> is the number of the Tomcat port on which JasperReports Server is installed, and <webAppNamePro-value> is the value of the webAppNamePro property in the default_master.properties file (see step 7). By default, the value of this property is jasperserver-pro.
    • ws_dashboard_url=http://<jasper-host>:<jasper-port>/<webAppNamePro-value>/dashboard/viewer.html?viewAsDashboardFrame=true#/Dashboards/WSDashboard, where <jasper-host> is the name or the IP address of the machine on which JasperReports Server is installed, <jasper-port> is the number of the Tomcat port on which JasperReports Server is installed, and <webAppNamePro-value> is the value of the webAppNamePro property in the default_master.properties file (see step 7). By default, the value of this property is jasperserver-pro.
    • web_app_name=<webAppNamePro-value>, where <webAppNamePro-value> is the value of the webAppNamePro property in the default_master.properties file (see step 7). By default, the value of this property is jasperserver-pro.
    Save and close the reports.properties file when finished.
  15. Restart WorldServer.
  16. Restart the WorldServer Reports service.
  17. Configure the WorldServer data source in JasperReports Server:
    1. Log in to WorldServer and go to Tools > Report Center.
    2. In the WorldServer Report Center, select View > Repository, and then, in the Folders tree, go to <root> > Organizations > WorldServer > DataSources.
    3. Select WorldServerDB, and then select Edit.
    4. In the Set Data Source Type and Properties page, specify the following information:
      FieldValue
      JDBC Driver (required)One of the following:
      • Microsoft SQL Server (tibcosoftware.jdbc.sqlserver.SQLServerDriver)
      • Oracle (tibcosoftware.jdbc.oracle.OracleDriver)
      Host (required)The name or the IP address of the database server used by WorldServer.
      Port (required)The port on which WorldServer is installed.
      Database (required) (for Microsoft SQL Server) or Service (required) (for Oracle)The database name (for Microsoft SQL Server) or the cluster/SID (for Oracle).
      URL (required)The URL is generated automatically based on the values you entered in the previous fields. The structure of the URL is as follows:
      • Microsoft SQL Server: jdbc:tibcosoftware:sqlserver://<db-host-name>:<port>;DatabaseName=<ws-database-name>
      • Oracle: jdbc:tibcosoftware:oracle:@<db-host-name>:<port>:<SID>
      User NameThe user name that will be used to log in to the database.
      PasswordThe password that will be used to log in to the database.
    5. Select Test Connection, and then select Save.

Results

At this point, you should be able to see the reports from Tools > Report Center in WorldServer. Also, the dashboard should be displayed on the Home page in WorldServer Classic.