This documents updated for JasperServer version 3.0.0

What is JasperServer

JasperServer is an open source business intelligence suite, built by the developers of JasperReports. It providing common services like security and metadata management, and the capability to easily add additional functionality.It also provides a Web and Web services based environment for reporting, data analysis (OLAP), and data integration.

What is JasperReports

JasperReports is a powerful open source Java reporting tool that has the ability to deliver rich content onto the screen, to the printer or into PDF, HTML, XLS, CSV and XML files. It is entirely written in Java and can be used in a variety of Java enabled applications, including J2EE or Web applications, to generate dynamic content. Its main purpose is to help creating page oriented, ready to print documents in a simple and flexible manner.

System requirements

In order to install JasperServer, you need to setup and configure the following application.

• Apache Tomcat (with JDK1.6) - to be use as Java container
• PostgreSQL - to be use to store JasperServer metadata files

Note: You may use JBoss and MySQL as an alternative to the above application.

How to install JasperServer?

JasperServer installation is very easy as no complicated process involved. In this guide, we will use the stand-alone WAR file distribution. Follow the step-by-step below to complete the installation.

A. Download and Unpack JasperServer file

The WAR file distribution comes in a ZIP file format. Please download the file from www.jasperforge.com. Once you have downloaded the WAR file distribution, you need to unpack it in order to access the contained files. Go to any working directory location to unpack the ZIP file.

user@server:~# unzip jasperserver-3.0-bin.zip
user@server:~# ls
docs  jasperserver.war  js-installer-version.txt  license.txt  releaseNotes.txt  samples  scripts

B. Setup the JasperServer database

• Connect to the PostgreSQL database and create a user for JasperServer. In this document, we will use jasperadmin.
  

  postgres> CREATE USER jasperadmin PASSWORD '<password>';

• Create a database for JasperServer with jasperadmin as owner and UTF-8 encoding
  

  postgres> CREATE DATABASE prd_jasperserver OWNER jasperadmin ENCODING 'UTF-8';

• Connect to the JasperServer database
  

  postgres> \c prd_jasperserver
  prd_jasperserver>

• Create schema for main JasperServer tables. If you already have the database dump, please skip the steps below.
  

  prd_jasperserver> \i js-create-schema.sql

• Create default security.
  

  prd_jasperserver> \i js-create-default-security.sql

• Create trigger to delete the BLOB data if the reference records is deleted.
  

  prd_jasperserver> \i js-create-trigger.sql

C. Install/Deploy JasperServer into Tomcat

Because the JasperServer is stand-alone JSP files, the installation process involves dropping the files into the webapps directory of the Tomcat server. If you decided to use Jasper Server as default page, then you should put the files into ROOT directory.

user@server:~# cd $TOMCAT_ROOT/webapps
user@server:~# mkdir jasperserver
user@server:~# cd jasperserver/
user@server:~# jar xvf /home/user/jasperserver.war
user@server:~# ls
cal  externalResource.htm  images  index.htm  inputControl.htm  jpivot  META-INF  scripts  stylesheets  wcf  WEB-INF

Allocate static memory for Tomcat (Java). The default memory is not enough to extract data which is more than 1000 records (estimation only). To do this, edit the $TOMCAT_ROOT/bin/setclasspath.sh and add the following lines at the end of file.

JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx768m -XX:PermSize=32m -XX:MaxPermSize=128m -Xss2m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled "

Note: -Xs128m is referring to minimum allocated memory wheres the -Xmx768m is maximum allocated memory. Change the value based on total memory installed on the machine.

D. Edit configuration files

There are few configuration files that need to edit. The list of files and its contents as below:

• $JASPER_ROOT/META-INF/context.xml
  

  <Context path="/jasperserver" debug="5" reloadable="true" crossContext="true">            
      <Resource name="jdbc/jasperserver" auth="Container" type="javax.sql.DataSource"
          maxActive="100" maxIdle="30" maxWait="10000"
          username="jasperadmin" password="mypassword" driverClassName="org.postgresql.Driver"
          url="jdbc:postgresql://localhost:5432/prd_jasperserver" defaultAutoCommit="false"/>
  </Context>

• $JASPER_ROOT/WEB-INF/hibernate.properties
  

  # Property that determines the Hibernate dialect
  metadata.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
  metadata.hibernate.dataSource.jndiName=jdbc/jasperserver

• $JASPER_ROOT/WEB-INF/js.mail.properties
  

  report.scheduler.mail.sender.host=smtp.raj2u.net
  report.scheduler.mail.sender.username=user@raj2u.net
  report.scheduler.mail.sender.password=password
  report.scheduler.mail.sender.from=user@raj2u.net
  report.scheduler.mail.sender.protocol=smtp
  report.scheduler.mail.sender.port=25

• $JASPER_ROOT/WEB-INF/js.quartz.properties
  

  org.quartz.scheduler.instanceName=JasperServerScheduler
  org.quartz.threadPool.threadCount=20
  org.quartz.threadPool.threadPriority=5
  org.quartz.jobStore.misfireThreshold=180000
  org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
  org.quartz.jobStore.tablePrefix=QRTZ_

Note: Don't forget to put all the required JDBC drivers in $TOMCAT_ROOT/lib or $TOMCAT_ROOT/common/lib

Now you may start the Tomcat and check the Tomcat's log file to see that there are not serious errors on the startup. If JasperServer started up properly, you should be able to login. Login by going to the following URL: http://host-address:port/jasperserver. The default login information is written in the js-create-default-security.sql file.

JasperServer Customization -> HOW-TO

A. How to enable password encryption?

File that need to be edited is $JASPER_ROOT/META-INF/WEB-INF/ApplicationContext-security.xml

In the definition of the "daoAuthenticationProvider" bean, there is a commented-out reference to the passwordEncoder bean. Uncomment the reference to passwordEncoder and this causes the passwordEncoder logic to be used. After removing the commenting characters the line should look like the following:

 <property name="passwordEncoder"><ref local="passwordEncoder"/></property>

Now under the “passwordEncoder” bean, the property "allowEncoding" should be changed from false to true so that it looks like the following:

 <property name="allowEncoding"><value>true</value></property>

Once the changes described above are made, encryption is enabled for the JasperServer application upon the next restart.

Note: If the password in database is in clear text, please update to "A34FAB575B828B127AC85B236B096043" as we are using encryption and the password in clear text will be "mypassword".

B. How to change the login page?

Edit the $JASPER_ROOT/WEB-INF/bundles/jasperserver_messages.properties and change your desired text as below.

#Welcome Login Page
LOGIN_WELCOME_OS=Welcome to JasperServer Reporting System!
 
# the following 2 strings belong to the same sentence
LOGIN_ONLINE_DEMO_PRE=JasperServer is an open source business intelligence suite ....
LOGIN_ONLINE_DEMO=JasperReports is a powerful open source Java reporting tool ...

Now, replace the $JASPER_ROOT/WEB-INF/jsp/login_welcome.jsp with the one i attached here. You may see the differents before replace. Once the file replaced, the login page will look like below.

C. How to change report export parameters?

You need to edit $JASPER_ROOT/WEB-INF/applicationContext.xml and $JASPER_ROOT/WEB-INF/applicationContext-report-scheduling.xml. Look for "export parameters" section:

<!-- export parameters -->
 
    <bean id="xlsExportParameters" class="com.jaspersoft.jasperserver.api.engine.jasperreports.common.XlsExportParametersBean">
        <property name="detectCellType" value="true"/>
        <property name="onePagePerSheet" value="false"/>
        <property name="removeEmptySpaceBetweenRows" value="false"/>
        <property name="removeEmptySpaceBetweenColumns" value="true"/>
        <property name="whitePageBackground" value="false"/>
        <property name="ignoreGraphics" value="false"/>
        <property name="collapseRowSpan" value="true"/>
        <property name="ignoreCellBorder" value="true"/>
        <property name="fontSizeFixEnabled" value="true"/>
        <property name="maximumRowsPerSheet" value="0"/>
        <property name="xlsFormatPatternsMap" ref="formatPatternsMap"/>
    </bean>
 
    <bean id="csvExportParameters" class="com.jaspersoft.jasperserver.api.engine.jasperreports.common.CsvExportParametersBean">
        <property name="fieldDelimiter" value="|"/>
    </bean>
 
    <bean id="pdfExportParameters" class="com.jaspersoft.jasperserver.api.engine.jasperreports.common.PdfExportParametersBean">
        <property name="localizedFontMap" ref="localePdfFontMap"/>
    </bean>
 
    <util:map id="formatPatternsMap">
        <!-- entry key="¤ #,##0.00" value="$ #,##0.00"/-->
    </util:map> 
 
    <!-- end export parameters -->

D. How to restrict report scheduling function?

You need to edit $JASPER_ROOT/WEB-INF/jsp/repository/repositoryExplorer.jsp and add the "authz:authorize ifAllGranted" to set the permission based on role. In example below, i have granted scheduling / run background to role "Administrator" only.

<authz:authorize ifAllGranted="ROLE_ADMINISTRATOR">
    <td style="cursor: pointer;" width='50' height='50' onClick='' id='schedule_td' align="center">
     <a href='#' class='normalpx' id='schedule_td_a'><img src="images/schedule_enabled.gif" border='0' title='<spring:message code="RM_BUTTON_SCHEDULE_REPORT" javaScriptEscape="true"/>' id='schedule' /></a>
    </td>
 
    <td style="cursor: pointer;" width='50' height='50' onClick='' id='send_output_td' align="center">  
     <a href='#' class='normalpx' id='send_output_td_a'><img src="images/send_output_enabled.gif" border='0' title='<spring:message code="RM_BUTTON_RUN_IN_BACKGROUND" javaScriptEscape="true"/>' id='send_output' /></a>
    </td>
</authz:authorize>

References

For more information on the installation guide and troubleshooting, please visit http://wwww.jasperforge.org