OpenReports: Installation GuideWeb Site : OpenReportsRevision : Revision: 1.3Last Modified : Date: 03/31/2006

OpenReports: Installation Guide

1 OpenReports

Table Of Contents

1. Introduction.......................................................................................................................... 3

2. Configuration ...................................................................................................................... 4

2.1. Schema......................................................................................................................... 5

2.2. Administration User....................................................................................................... 6

2.3. Hibernate ...................................................................................................................... 7

2.4. Scheduler...................................................................................................................... 8

3. Deployment ......................................................................................................................... 9

4. General Settings................................................................................................................ 10

5. FAQ .................................................................................................................................. 11

5.1. Common Problems ..................................................................................................... 12

5.2. Encrypted Passwords ................................................................................................. 14

5.3. Database Schema ...................................................................................................... 15

6. Resources ......................................................................................................................... 16

7. License .............................................................................................................................. 17

8. Credits ............................................................................................................................... 18

OpenReports: Installation Guide

2 OpenReports

1. IntroductionOpenReports is a flexible open source web reporting solution that allows users to generatedynamic reports in a browser. OpenReports uses JasperReports, an excellent full featuredopen source reporting engine, and was developed using leading open source componentsincluding WebWork, Velocity, Quartz, and Hibernate.

OpenReports supports a wide range of reporting requirements through three levels ofreport generation:

• QueryReports

Table based reports built from SQL Queries featuring sorting, paging, and exportto CSV, XLS, and PDF.

• QueryReportTemplates

QueryReports customized through the use of Velocity templates.

• JasperReports

Full support for JasperReports, including a number export formats (PDF, HTML,CSV, XLS, and Image), chart generation, and scheduled reports.

OpenReports provides a web based report generation and administration interface withthe following features:

• Web based administration of users, groups, reports, parameters, anddatasources.

• Define groups of reports, and grant users access to reports by group.• Define reusable report parameters including Date, Text, and Query Parameters.• Define multiple JNDI or Connection Pool DataSources for use in generating

reports.• Upload and hot deploy new reports.• Cross platform database support via Hibernate based persistence layer.

Note: This document contains instructions to install and run OpenReports. If you are using OpenReports forthe first time, the OpenReportsTomcat bundle is a preconfigured demo installation of OpenReports thatcontains a sample database and example reports that illustrate many core OpenReports concepts.

OpenReports: Installation Guide

3 OpenReports

2. Configuration

Note: If you have downloaded the preconfigured OpenReportsTomcat bundle, and would like to get startedimmediately, unzip OpenReportsTomcat to the root directory of your hard drive, change to the'openreports-tomcat/bin' directory, start Tomcat via 'catalina run', open 'http://localhost:8080/openreports' inyour browser, and login using a username of 'admin', and a password of 'admin'

4 OpenReports

2.1. Create OpenReports Schema

OpenReports stores information about reports, users, groups, etc. in database tables.These tables must be created before using OpenReports. The SQL scripts for somecommon databases are located in the /database/schema directory.

Note: The Database Schema Help section of the FAQ includes instructions for creating and updating theOpenReports schema via ANT tasks. In order to use the schema related ANT tasks you must first configureHibernate as outlined below and use the ANT compile task to compile OpenReports.

OpenReports: Installation Guide

5 OpenReports

2.2. Create OpenReports Admininistration User

Once you have created the OpenReports tables in your database, you must insert a recordinto the REPORT_USER table in order to create an Admin user that you can use to log intoand administer the application.

The following example creates a user with the name 'admin', a password of 'password' andAdministrative rights:

INSERT INTO REPORT_USER (NAME, PASSWORD, ADMIN, EXTERNAL_ID,EMAIL_ADDRESS, PDF_EXPORT_TYPE)

VALUES ('admin','password',1,'','',0)

Note: The value of the ADMIN field in the INSERT statement may be 1 or 'true' depending on how yourdatabase handles boolean fields.

6 OpenReports

2.3. Configure Hibernate

The next step in the configuration process is to configure Hibernate so that OpenReportscan connect your database.

In order to configure Hibernate you must set the SQL Dialect, and connection properties inthe hibernate.properties file that is located in the src directory.

Here are some common examples:

HSQL

hibernate.dialect=net.sf.hibernate.dialect.HSQLDialect

MySql

hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect

SQL Server

hibernate.dialect=net.sf.hibernate.dialect.SQLServerDialect

PostgreSQL

hibernate.dialect=net.sf.hibernate.dialect.PostgreSQLDialect

The next step is to set the connection properties. If you are going to use a JNDI connection,the only property you need to set is "hibernate.connection.datasource". Forexample:

hibernate.connection.datasource=java:comp/env/jdbc/OrDb

If you are not using JNDI, you must supply all the properties needed to create a connectionsuch as the URL and Driver. Examples of these properties are included in thehibernate.properties file.

OpenReports: Installation Guide

7 OpenReports

2.4. Configure Scheduler

OpenReports uses Quartz, an open source enterprise-class Job Scheduler, to provide theability to schedule reports to be sent via email.

The scheduling feature of OpenReports can be enabled or disabled by uncommenting orcommenting out the following lines in the components.xml file.

<component>

<scope>application</scope>

<class>org.efs.openreports.providers.impl.SchedulerProviderImpl</class>

<enabler>org.efs.openreports.providers.SchedulerProviderAware</enabler>

</component>

Quartz is configured, in the quartz.properties file, to persist jobs to a database via aJDBCJobStore. In order to use the JDBCJobStore, the Quartz schema must be createdusing one of the Quartz database scripts located in the database/schema/quartzdirectory, the DataSource settings in quartz.properties file must be updated with theconnection information for your database, and theorg.quartz.jobStore.driverDelegateClass must be set to the proper delegateclass for your database.

Note: For more information on configuring Quartz, visit the Quartz project site athttp://www.opensymphony.com/quartz/

8 OpenReports

3. DeploymentOpenReports can be deployed as an expanded Web Application or as a WAR file.

In order to deploy OpenReports as an expanded Web Application, first update theproperties files in the src directory as described above. Next, use the ANT compile taskto compile the source code and move the properties files to theWebRoot/WEB-INF/classes directory. Finally, copy the entire WebRoot directory intoyour target application server and rename the directory, for example to openpeports.

In order to deploy OpenReports as a WAR file, first update the properties files in the srcdirectory as described above. After updating the properties files, a WAR file can be createdby ANT using the war task from the build.xml file. This task will compile the source codeinto WebRoot/WEB-INF/classes, create an openreports.jar file inWebRoot/WEB-INF/lib and finally build an openreports.war file in the deploy directory.

Important: If you are not using JNDI DataSources, the JDBC drivers for all database servers used byOpenReports, including the OpenReports database, the Quartz database, and any reporting databases, mustbe included in the WebRoot/WEB-INF/lib directory. The FAQ contains links to the JDBC drivers for anumber of common databases.

Note: OpenReports will not run as a WAR file under WebLogic due to problems related to WebWork andVelocity. In order to deploy under WebLogic, copy the WebRoot directory to the applications directory of thetarget domain.

OpenReports: Installation Guide

9 OpenReports

4. General SettingsAfter deploying the OpenReports Web Application, you must login to OpenReports as anAdminstrator and set the baseDirectory and mail.smtp.host via the GeneralSettings Administration page.

The baseDirectory property must be set to the full path of the directory containing yourJasperReports files.

The mail.smtp.host property must be set to a valid mail host in order to generate andemail scheduled reports.

OpenReports General Settings Screen

10 OpenReports

5. FAQ

OpenReports: Installation Guide

11 OpenReports

5.1. Common Problems

1) Error loading object from file (or reports not being generated):

JasperReports requires that you compile your reports using the same version of theJasperReports jar file as the application you are using to run the reports (in this caseOpenReports) is using.

To fix this problem, recompile your JasperReport files using the same version of the jar filethat is in the openreports/WEB-INF/lib directory.

Another possible solution is to replace the JasperReports jar file inopenreports/WEB-INF/lib with the jar file you are using to compile your reports. Inmost cases they should be compatible, but backwards compatiblity is not guaranteed.

2) java.lang.NoClassDefFoundError on Linux:

The JasperReports library will generate java.lang.NoClassDefFoundErrorexceptions when running on a Linux machine without an X-Server running. The easiestsolution is to run in headless mode, which is available in JDK 1.4+. For example, if you areusing Tomcat, add the following to your catalina.sh file:

CATALINA_OPTS="-Djava.awt.headless=true"

For more information, search the JasperReports forums on SourceForge for 'headless' or'NoClassDefFoundError'.

3) Misc problems inserting records into OpenReports database:

Make sure you are using the latest versions of the appropriate JDBC drivers for yourdatabase. Here are links to the JDBC drivers for some common databases:

HSQL

http://sourceforge.net/projects/hsqldb

MySql

http://www.mysql.com/products/connector/j

Oracle

http://www.oracle.com/technology/software/tech/java/sqlj_jdbc

PostgreSQL

http://jdbc.postgresql.org/

SQL Server

http://sourceforge.net/projects/jtds

12 OpenReports

OpenReports: Installation Guide

13 OpenReports

5.2. Encrypted Passwords

OpenReports provides the ability to store OpenReports user passwords as Base64encoded Strings.

To enabled this feature you must edit the ReportUser.hbml.xml file in thesrc/org/efs/openreports/objects directory. Comment out the default passwordproperty entry and uncomment the password property entry that has the type set toorg.efs.openreports.util.EncryptedStringUserType.

EncryptedStringUserType can be extended if stronger encryption is required.

14 OpenReports

5.3. Database Schema

OpenReports uses Hibernate to provide cross platform database support and theOpenReports distribution includes the DDL for a number of databases. OpenReports alsoincludes two utility classes that can be used to create or update the OpenReports schema.These two classes can be run by ANT using build.xml file included with OpenReports.

1) ant schemaExporter - this target will create the entire OpenReports schema in thedatabase indicated in the hibernate.properties file.

2) ant schemaUpdater - this target can be run to update the OpenReports schema in thedatabase indicated in the hibernate.properties file to the latest version.

If you are having problems with the DDL included in the OpenReports distribution, it may beeasier to export or update the schema directly using the ANT targets.

Also, make sure that the hibernate.dialect in the hibernate.properties file is setto the proper dialect for your database.

More information on Hibernate can be found at:

http://www.hibernate.org

OpenReports: Installation Guide

15 OpenReports

6. ResourcesFor additional information, visit:

http://www.oreports.com

16 OpenReports

7. LicenseOpenReports is distributed under the GPL License

For alternative licensing, contact info@oreports.com

OpenReports: Installation Guide

17 OpenReports

8. CreditsOpenReports uses the following open-source projects:

JasperReports - Java report-generating library

http://jasperreports.sourceforge.net

WebWork - MVC web application framework

http://sourceforge.net/projects/opensymphony

Hibernate - a powerful, ultra-high performance object/relational persistence and queryservice for Java

http://sourceforge.net/projects/hibernate

Quartz - a Java open source enterprise-class Job Scheduler,

http://sourceforge.net/projects/quartz

JFreeCharts - a Java charting library

http://www.jfree.org/jfreechart/index.html

OpenReports also uses a variety of other open-source software including softwaredeveloped by the Apache Software Foundation (http://www.apache.org)

18 OpenReports

OpenReports: Installation Guide

19 OpenReports