====== JasperReports Systems Administrator Guide ======

===== Install Dependencies =====

==== Java Development Kit ====

Unless you want to not use the bundled Tomcat and PostgreSQL then the only dependency to install is the Java Development Kit (JDK). The JasperSoft Platform Support Guide is the best place to look to decide what version to install. The JDK version 8 is our preferred choice at more recent Java are still only use to runtime only and need version 8 compatibility for compiling reports.

==== Microsoft Visual C++ Redistributable ====

If installing on a fresh server with nothing else installed there is a likely chance you stumble upon the following error during installation without .

<code>
There has been an error.
Error running initdb.exe -U postgres -E UTF8 -D
C:/JASPER~2/JASPER~1.0/POSTGR~1/data: child killed: unknown
signal
The application will exit now.
</code>

The most likely cause for this is detailed in https://community.jaspersoft.com/wiki/windows-643-and-71-bundled-installers-crashes-upon-running-initdbexe-due-missing-msvcr100dll

In short, the system is missing the  [[https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170|Microsoft Visual C++ Redistributable]]. Which version will depend on which version of JasperServer you are trying to install. The most recent major versions of JasperServer are included here.

^ JasperServer Version      ^ Microsoft Visual C++ Redistributable Version ^
| 8.2.0    | [[https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022|Visual Studio 2015, 2017, 2019, and 2022]] |
| 7.1.1    | [[https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2010-vc-100-sp1-no-longer-supported|Visual Studio 2010 (VC++ 10.0) SP1 (no longer supported)]] |
| 6.4.3    | [[https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2010-vc-100-sp1-no-longer-supported|Visual Studio 2010 (VC++ 10.0) SP1 (no longer supported)]] |

===== Install JasperServer =====

Download the latest version of the JasperServer and run the executable. The bundled PostgreSQL and Tomcat is usually used to make installation a breeze.

===== Configuration Notes =====

Most default configuration settings are used. Some exceptions are detailed below.

In production some reports require the following configuration to be changed to run stored procedures. Locate the file C:\Jaspersoft\jasperreports-server-VERSION\apache-tomcat\webapps\jasperserver-pro\WEB-INF\classes\esapi\security-config.properties and set the following

<code>
security.validation.sql.on=false
</code>

===== Firewall =====

Tomcat bundled with the JasperServer is already configured to be able to listen on external interfaces. But the windows firewall would block it by default. The safest is to only open the port 8080 to those who will access the JasperServer directly. This usually means administrators and developers as all reports are made available directly in the Pacific EMIS web application.

===== Integration with Pacific EMIS =====

A powerful feature of the Pacific EMIS is its seamless integration with a high end enterprise grade reporting server called JasperReport Server (aka. JasperServer).

<note warning>JasperServer until recently (end of 2023) been developing and release JasperServer as open source. Unfortunately, they now only release their JasperSoft Studio to design the reports and no longer release the JasperServer without the enterprise license. But all previously released versions are extremely stable and will continue working for years.</note>
==== Configuration of the Web Application ====

To effectively integrate the JasperReport server with the Pacific EMIS you need to make sure the relevant part of the Web.Config is edited accordingly (i.e. jasperUrl, jasperUser, jasperPass). This would likely be different whether you are working in development or deploying to production.

<code xml>
  <appSettings>
    <add key="server" value="localhost" />
    <add key="database" value="fedemis-test" />
    <add key="context" value="fedemis" />
    <add key="title" value="FedEMIS Online" />
    <add key="ReportServerUrl" value="http://localhost:8080/reportserver" />
    <add key="jasperUrl" value="http://localhost:8082/jasperserver" /> <!-- Reports feature will not work unless JasperServer deployed correctly -->
    <add key="jasperUser" value="jasperadmin" />
    <add key="jasperPass" value="jasperadmin" />
    <add key="FileDb" value="c:\files\filedb" /> <!-- This must be set with folder created on filesystem or documents feature will not work -->
  </appSettings>
</code>
==== Folder Structure ====

The folders follow a simple convention to make integration with the Pacific EMIS easy. First, resources folders:

  * **Images** Includes all the images which we used in all the .jrxml file. So images in reports should point to the repo: link before they are deployed in the JasperReport Server. This does require a annoying switching of the images links in the report when working between development in JasperSoft Studio and production in JasperServer.
  * **Templates** Similarly to images, this folder includes all the .jrtx files which is used to apply particular styles in reports. The advantage of centralizing styles are well known. The same annoying switching of the links is reports is require before deploying.

Then there are all the folders that hold the reports. The Pacific EMIS is usually made up of simple modules (e.g. Schools, Teachers, Exams). Each of those modules typically have individual entities (e.g. an individual School, an individual Teacher.) Reports can be designed and place in particular folders to automatically appear in the Pacific EMIS through the RESTful API. 

For example, if you want a new report to go under the Schools (e.g. List of school without annual census submission this year) module you would design it and put in a a folder **Schools**. When published all the published reports in here will appear in the Pacific EMIS' Schools module as shown in the figure below.

{{ :sysadmin-manual:jasperreports-integration-1.png?nolink |}}

Now if you wanted to have a report for individual schools (e.g. A School Report Card). You would locate it in a folder called **School** (not without the plural "s"). In this case, it would appear in any of the individual school as shown below.
{{ :sysadmin-manual:jasperreports-integration-2.png?nolink |}}

The same will work for any other module (i.e. Indicators, Exams, Teachers, Individual Teachers, etc.)

==== Required Libraries ====

Some or all reports require some additional jar files in essence small dependencies. They are listed and described here.

  * **font-extension.jar**: Used to support the new custom fonts in jasper server. Can be added directly in **<Jasper Server>\apache-tomcat\webapps\jasperserver\WEB-INF\lib**
  * **reporting-1.0.jar**: Used as a chart customizer to customize the look of exams reports among potentially others. Can be added directly in **<Jasper Server>\apache-tomcat\webapps\jasperserver\WEB-INF\lib**
  * **sqljdbc-VERSION.jar**: Used for JBDC connection to interact with the MS SQL Server. Often loaded directly from the UI of JasperServer when creating the data source or in JasperSoft Studio.
  
Restart the server when adding the jars for the first time.

==== Fonts ====

Reports have been standardized using the Open Sans famliy of fonts so those will need to be installed on the Windows Server. Just download them from https://fonts.google.com/specimen/Open+Sans or https://www.1001fonts.com/open-sans-font.html, extract and double click each one of them to install. Maybe now is a goo time to restart the server before testing out some reports.

Note that if you are designing reports you will also need to install them on your own workstation and you could also install them directly in the JasperSoft Studio. To do this you would go to **Window -> Preferences -> Jaspersoft Studio -> Fonts**. Click on Add from path and select the zip file. Install in JasperSoft Studio as shown below.

{{:developer-manual:jasper-add-font.png?nolink|}}



===== Backing Up =====

To fully backup the JasperServer one must backup at least two things carefully:

  * The repository of object. This can be automated or exported from the user interface
  * The keystore. These are typically two encrypted files containing security keys necessary for the secure and good functioning of the server.

Both are detailed below.

==== Scheduling Data Exports ====

While the preparations here are not necessary for whole platform backups they are important for data backups. You need to setup Windows Scheduled Tasks to export to JasperReports backups as shown below. The user is the admin user of the computer (or another user with enough permissions)

<note tip>You will need to install the JDK (and not just the JRE) for the JasperServer buildomatic scripts to work. Then set JAVA_HOME environment variable to its location.</note>

{{ :sysadmin-manual:task-schedule-backup-1.png?nolink |}}

Configured to run daily at night.

{{ :sysadmin-manual:task-schedule-backup-2.png?nolink |}}

Execute the script to backups the whole JasperServer. 

  * **Program/Script:** js-export.bat
  * **Add Arguments (optional):** --everything --output-zip "C:\EMIS\jasperserver_repository_data_backup.zip"
  * **Start in (optional):** C:\Jaspersoft\jasperreports-server-cp-7.2.0\buildomatic\

{{ :sysadmin-manual:task-schedule-backup-3.png?nolink |}}

Finally, you need to setup a SQL Server task to execute daily backups. From within SQL Management Studio you can easily create such task as shown below.

{{ :sysadmin-manual:sql-server-backup-task-1.png?nolink |}}

==== Keystore Backup ====

The keystore is usually only accessible by its owner, the one who deployed the JasperServer. The files are usually something like these:

  * C:\Users\Administrator\.jrsks
  * C:\Users\Administrator\.jrsksp

Make sure the password to access those--usually defined at installation--is not lost. And make to securely backup of those files. Perhaps special access permission will be needed as by default those files are accessible by Administrator who setup the JasperServer only. If a backup system uses another user (e.g. backuppc) then that user will need to be given explicit permission to access those files to back them up.

==== Catalog Restoration ====

With a backed up catalog (export.zip) and the keystore files (.jrsks and .jrsksp) you should be able to restore (import) all data from the backup.

First you'll need to manipulate the keystore. The .jrsks is Java keystore file and .jrsksp contains the keystore properties Base64 encoded. Read the .jrsksp file using following command and open the resulting text file in notepad.

<code>
> certutil -decode <path-to-file>/.jrsksp <path-to-file>/jrsksp.txt
</code>

You'll be interested in the following fields:

  * ksPwd: the keystore password
  * importExportEncSecret.keypass: the password for the key with alias importExportEncSecret. This is the key uses for encrypting exports and imports operations.

They are both base64 encoded in there also so you can decode them using the website https://www.base64decode.org/.

At this point you can access the keystore and the key. Provided you have downloaded your backed up keystore files somewhere on the new server (e.g. c:\Users\Administrator\Downloads\keys\) you could do things like list all keys in the store.

<code>
>keytool -v -list -storetype jceks -keystore C:\Users\Administrator\Downloads\keys\.jrsks
</code>

Or list only the key of interest.

<code>
>keytool -v -list -storetype jceks -keystore C:\Users\Administrator\Downloads\keys\.jrsks -alias importexportencsecret
</code>

I have found useful to temporarily change the passwords as using it later cause me more problem then I wanted to solved (special characters not handling well on the windows command line).

Change password of the keystore. I made it a convenient easy to type password since it is temporary and the keystore will be disposed later.

<code>
>keytool -v -storepasswd -storetype jceks -keystore C:\Users\Administrator\Downloads\keys\.jrsks
</code>

Change password of the key of interest. This password could also be made simple and convenient but then you would be best to change it in the production stored after ward for tighter security. Another approach is to make it a good password right away and as it gets imported it keeps this password.

<code>
>keytool -v -keypasswd -storetype jceks -keystore C:\Users\Administrator\Downloads\keys\.jrsks -alias importexportencsecret
</code>

<note tip>After manipulating the keystore you might have to restart the JasperServer.</note>

Changing the password made it easier to import and override the key in the new keystore generated from a fresh installation on the new server. Note that the only key being imported and in effect overriding the default one of the new installation is the importExportEncSecret key.

<code>
C:\Jaspersoft\jasperreports-server-cp-8.2.0\buildomatic>js-import.bat --input-key --keystore C:\Users\Administrator\Downloads\keys\.jrsks --storepass temporarypasswd --keyalias importExportEncSecret --keypass temporarypasswd
</code>

Then in the JasperAdmin you should now be able to import the backed up catalog (i.e. export.zip) as normal as shown in the following figure.

{{ :sysadmin-manual:jasperserver-import-1.png?nolink |}}

Once that the catalog has been successfully been updated you can do some final cleanups including:

  * Dispose of the original keystore (.jrsks and jrsksp from the previous server). They were tempered with changing to simple passwords for convenience and are no longer needed. Keep the original backup in the backup server of course.
  * The new keystore from the fresh installation on the new server now has a new secure password, but the imported and overriden key alias importExportEncSecret has the simple password carried from the change above. It would be a better idea to change it again to a strong password using the same technique as above but on the new keystore (you will need the new password which you can obtain from adapted commands above). If you do change the password for the key importExportEncSecret then you would also need to decode the properties (.jrsksp) edit the base64 string for that key and encode it again using the following command.

<code>
>certutil -encode jrsksp.txt tmp.b64 && findstr /v /c:-tmp.b64 > .jrsksp
</code>

<note important>You may need to make sure the permission on your newly encoded file have the exact same has the one before.</note>

There are actually a few different ways to handle backup and restores with more recent and secure JasperServer versions. More details can be found in the guide JasperReport Server Security Guide.